Instructions to help writing reference documentation

I’m not sure. Why that ? Did you see any difference in the rendering of the HTML page ?

Current generation of orientation.html:


Note the “blue monkey bounce”

Removing white space:


No blue monkey bounce, and the bottom margins of the following three images have consistent margins all around.

In the current orientation.html, use the HTML inspector. You’ll see space characters in the cell.

I don’t know if you want to go the route of automagically trimming white space in the implementation. Seems easier to suggest to folk not to stick white space around images unless (for some tricky reason) you are deliberately putting white space. Can’t imagine what that tricky reason might be.

Apropos of nothing on this thread: Thanks for bringing Fingerpainting forward!

1 Like

I’ll check that. Putting a space is more natural than not, so the rendering should be the same with a space or not.

It should be OK now, after a gmic up.

Probably, in the spirit of Markdown, preparing the presentation should not entail fiddle-faddle, including fiddling with white space around images in a table. That kind of fiddling indeed seems contrary to the Markdown spirit. But in the meantime, while this tool develops… take care with the white space around images.

Thank you for being particular about this, David.

David. As always - thank you for the quick turnaround!
But… Darn…

gmic update
cd git_repositories/gmic-community
git tag oldspace 'HEAD@{1 day ago}'
git branch --create OldSpace oldspace
git checkout OldSpace
cd tutorial/valuesmanip
gmic it orientation.gmd gmd2html 2 ot orientation.html

gmic update? check.

gmic it orientation.gmd gmd2html 2 ot orientation.html
[gmic]-0./ Start G'MIC interpreter.
[gmic]-0./ Input text-data file 'orientation.gmd'.
[gmic]-1./ Output image [0] as text-data file 'orientation.html'.
[gmic]-1./ End G'MIC interpreter.

And… I still get the bounce.

By any chance, you didn’t happen to test at the current HEAD? orientation.gmd and friends already had space characters taken out of the table this morning, EDT, and would not reflect the issue. To test, I kicked back a few commits (to a local OldSpace branch)

Markup looks like this (at OldSpace: be3064bc)

|| __Original__ | __Color Vectors__ | __Vector Lengths__ | __Factors__
|  ![orig](img/m_alpha.png) | ![colorvecs](img/m_cpv.png) | ![vectorlen](img/m_nrm.png) | ![factors](img/m_fac.png)

It looks like this, now, at HEAD on master 80d227f8

||__Original__|__Color Vectors__|__Vector Lengths__|__Factors__
|![orig](img/m_alpha.png)|![colorvecs](img/m_cpv.png)|![vectorlen](img/m_nrm.png)|![factors](img/m_fac.png)

I.e., white space removed from the current version. It wouldn’t reflect the problem.

I’ve just detected one whitespace around the |, if you have more (two) there will be still a whitespace in the generated code. Maybe this could explain that ?

1 Like

Yes. In fact, before the exclamation point ![orig] there are two space characters. What appears to be happening in the table cell (in HTML) for my browser (Firefox 78.8) is that the browser is wrapping after the second space character, putting the blue monkey on the second line in that particular cell, so it appears to bounce down.

This particular behavior is in no way hindering me: as noted, I just remove white space now. I do, DO, appreciate the care and attention you are giving this for the general Markdown user - who shouldn’t really need to fiddle with things like white space around images. Take care!

1 Like

Addendum: To be truthful, the browser is wrapping after a space character. I actually didn’t do a count.

Just noticed this oddity…
G’MIC command line help always points to an “oldtutorial” URL even if one never existed, as in -store, which was composed fresh as a 2.9 tutorial; an “oldtutorial” form was never written:

The Technical Reference Page page has a Tutorial Page for -store that points to the right place. Alas, at the bottom of that tutorial page, there is an expansion of $gmic -h store which, as you know, is just a reproduction of the shell command and therefore points to the phantom tutorial. That could be a trifling confusing.

Only done spot-checking, but it seems that all command line help references a page in the oldtutorial section, whether the target URL exists or not. :face_with_monocle:

This is Version 2.9.8 (pre-release #210605)

Edit:
Rummaging around gmic/src/gmic_stdlib.gmic:4151-4252

  • 4230-4231 - I get the impression that - regardless of flags being set - the eventual setting of $url will have an ‘oldtutorial’ form. Haven’t grasped the logic yet on how flags are set.

Bookmarked for further contemplation, when east-pointing shadows grow long here on the Eastern Seaboard of North America. Civilization calls now…

I noticed this too but didn’t report it because I thought something was being done under the hood. Gives G’MIC an old world feel. :stuck_out_tongue:

1 Like

Guye Mick’s Ye Olde Tutorial Shoppe: Tutorials, New, Used, Some Slightly Abused - Follow At Your Own Risk!

Thanks Garry for noticing this.
This commit Fix wrong url to tutorial pages. · dtschump/gmic@2e755a7 · GitHub should hopefully fix that issue.

2 Likes

Consider -shared, presently 1.6x, but on my todo for refurbishing to 2.9x There is this line in the #@cli : comment block in gmic_stdlib.gmic:

7333: #@cli : $$ https://gmic.eu/oldtutorial/_shared.shtml

I could make a patch and make a pull request on the gmic project for these and analogous lines when I upgrade the tutorial; just a bit of maintenance akin to patching the tutorial directory Command_Guide.gmd Would that be helpful? It becomes a minor checkbox in my tutorial release procedure. There is nothing else I would have to add, no? just the URL of the new/refurbished tutorial in the same pattern as the others in the tutorial directory, following the $$ marker

When a new tutorial page is set, we just have to replace this line by :

#@cli : $$

I guess I’ll try to manage that when I see new tutorial pages coming in the gmic-community repository. Of course, just let me know if I forget to do this.

I could do that.

By the way, the tutorial for the -index command appears to have been regenerated from index.gmd as index.html so it is now (inadvertently) functioning as the directory page for the entire tutorial directory, masking the real index page. You see the problem from the main gmic.eu page. Choose Resources -> ScrIpting Tutorial and you are immediately in the tutorial for the -index command. I think you solved this issue the last time by the simple expedient of naming the tutorial page _index.html.

Edit: Seems simpler, in the long run, just to rename the tutorial file.

commit c7439d3cb64038e0506ce4ac01f5e9cbe759c3b0 (HEAD -> master, upstream/master, origin/master, origin/HEAD)
Author: Garry R. Osgood <grosgood@garryosgood.com>
Date:   Tue Jun 8 07:14:08 2021 -0400

    moved:      valuesmanip/index.gmd -> valuesmanip/gindex.gmd
    modified:   Command_Guide.gmd
    
                index.gmd->gindex.gmd: No content change, but the
                tutorial file under the old name tended to generate
                an 'index.html', which - unless special intervention
                was done - would mask or overwrite the real tutorial
                directory index file, making navigation difficult.
                This change lays to rest the need for special intervention
                Command_Guide.gmd: Updated valuesmanip/_index.html
                2.9x series to valuesmanip/gindex.html.
    
    note:       Need to sync src/gmic_stdlib.gmic
                8384: x "mv -f index.html _index.html" - obsolete? Not needed anymore
                9982: #@cli : $$ https://gmic.eu/tutorial/_index.html -->
                      #@cli : $$ https://gmic.eu/tutorial/gindex.html

I think that checks all the boxes… Ah! The Technical Reference Guide: -index _index.htmlgindex.html

Right, I don’t think most people would care about the file name, except for people wondering how to pronounce it: jin-dex, gin-dex, guh-in-dex, gee-in-dex or …? I didn’t mind the underscore either.

Human readability is not the issue. The issue is index.gmd (tutorial about the index command).

That G’MIC Markdown file translates to index.html through the scripting which populates the /tutorial/ web server directory. As you know, web servers ascribe special significance to index.html files; they are taken to be the visual directory/home page of whatever directory they inhabit in a web server’s document tree. So, as of this writing (15:00-ish UTC) the Resource -> Scripting Tutorial menu choice at gmic.eu does not bring up the tutorial home page, with links to various flavors of tutorials, but the specific tutorial for the -index command - and the remaining tutorials are not accessible (you have to already know their URL to get at them).

Now this is an abnormal circumstance, methinks, bought about by the /tutorial/ content generation script ending prematurely. When it does complete, the scripting which populates the /tutorial/ directory on the web server (which @David_Tschumperle wrote) does have exception processing to - after-the-fact - rename /tutorial/index.html to /tutorial/_index.html, and, also, /tutorial/Introduction.html to /tutorial/index.html, because Introduction.gmd actually functions as the directory index. So, this exception processing routinely masks the issue created by index.gmd not having an apt name. So why should I take action at all if David has already written some exception processing to cover my butt?

The problem with exception processing, in general is that it assumes that processing overall always successfully completes, that exception processing checks all the boxes that need to be checked. But sometimes exception processing does not complete (as in the present case), all the boxes that need to be checked don’t get checked, and you are in an inconsistent state. So - basic rule-of-thumb for systems scripting: minimize wherever and whenever possible, exception processing, so that when the system ABENDS (which always happens at some point), the number of boxes that should have gotten checked (but didn’t) is kept to a minimum.

In this case, the source of exception processing is merely a less-than-aptly named file (index.gmd). Easy enough to call it gindex.gmd or even birdseed.gmd - any name whatsoever so that it doesn’t create an index.html that requires a bit of exception processing to fix. However, gindex.gmd is somewhat mnemonic of its content. while birdseed.gmd isn’t (but it is a fun name).

In the same vein, /tutorial/Introduction.gmd should move to /tutorial/index.gmd to eliminate another bit of exception processing, since that file actually does serve as the index to the /tutorial/ directory.

1 Like

I do know what you are talking about; didn’t expect such a long response. :medal_sports:

Done. Commit 285be48df042