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.