At this point, if you want to contribute to improve the content of the documentation, you are welcome to do so
I’ve set up a markdown-like syntax in the G’MIC documentation generator, which can be used to decorate the description of the commands. This G’MIC markdown (a.k.a gmd) recognize the following patterns :
__words in italic__ \rightarrowwords in italic
**words in bold**\rightarrowwords in bold
`words in bold monospace` \rightarrowwords in bold monospace (should be used for highlighting values or choices for arguments).
single_word_in_monospace'\rightarrowsingle_word_in_monospace (should be used for highlighting variable and command names).
''reference to page or command''\rightarrow auto-link to URL describing the page or command (useful for the See also: subsections).
~~~code block~~~\rightarrow
code block
^^ Image URL ^^\rightarrow display image in a centered block.
{ list of values }\rightarrow highlight the list of values.
http[s]://address.url\rightarrow highlight and make a clickable link.
# Section name\rightarrow Start a new section.
## Subsection name\rightarrow Start a new subsection.
### Subsubsection name\rightarrow Start a new sub-subsection.
* Item of a list \rightarrow Display item as a list item.
- Item of a sub-list\rightarrow DIsplay item as a sub-list item.
. Item of a sub-sub-list\rightarrow Display item as a sub-sub-list item.
For now, there are not other syntax recognized, but I think this is already enough to make the reference documentation better looking than before. Maybe I’ll add other gmd-rules in the future, if there are needs for new stuffs.
I’m now planning to implement a gmd->ascii converter, to allow G’MIC displaying the gmd-formatted text on the console (when using the CLI tool gmic). The gmd->html command is already used for generating the HTML doc.
That’s all for now. As always, Feedback appreciated!
I think I’m done with the reference documentation manager in G’MIC.
Now, we have a quite flexible system able to generate the technical reference documentation, based on two distinct commands: parse_cli and reference.
Command parse_cli generates the help about the use of one specific command (or a set of commands).
Command reference generates the help about the general G’MIC syntax (substitution mechanism, image terminology, grammar of the language and so on…).
These two commands are able to generate the documentation in the following formats:
VT100-colored ascii (for terminal output): this is the output format used by command help (global help) and help command_name, when invoked from the CLI tool gmic. The command help has been recoded at this occasion. Below a screenshot of what it renders, in the terminal:
HTML: this is the output format used to generate the reference pages on the G’MIC website : https://gmic.eu/reference . Sections and commands of the reference doc are generated as distinct pages. Here is how it looks:
The cool stuff with the new documentation manager is that it understands something I called gmd, for G’MIC Markdown, which is a light markdown-like syntax allowing to render the documentation with text decoration, images, cross-reference links, etc.
Note that at this point, I haven’t really improved the content of the documentation, just the way it is (automatically) generated, and the formatting features it supports.
Honestly, all this took me much more time than I thought at the beginning, but at least it’s there and I’ll be able to enrich the documentation more easily (I have a new command update_reference_html that generates and update the doc automatically on the G’MIC server, it could even be cron-ed if necessary).
As a result, I’ve removed the old doc generator (command document_gmic) that is no more of use.
Now, I’m thinking about taking a few dozen minutes each day, to write detailed documentation for each command. Any suggestion on with what command I should start?
Just one remark to pdf documentation. There are still links pointing to David internal locations of type file: e.g. “file:///home/dtschump/work/src/gmic/html/reference/examples_of_use.html#top”!
