Instructions to help writing reference documentation

Today, I’ve added new reference documentation pages about the G’MIC Markdown syntax (which is used to format the documentation pages) and how to write new reference documentation pages.

There is no a way for gmic-community members to add new pages to the reference documentation. I’m not sure what to put there (rather than on the wiki), but my guess is the reference documentation is more visible and organized than the wiki pages, so it could be better to use it.

Just another available option, by the way.
Do not hesitate to test and contribute !

Sorry if this sounds stupid, but what would we be editing/adding there? New pages to add to the actual g’mic reference docs?

Yes exactly!
I’m currently converting the “Funny Oneliners” command as a new reference page.

Wow OK that’s pretty cool then, but I do worry a little about ensuring quality - will it be curated somehow? Or do we trust that mistakes will just get corrected over time?

It’s actually open only for people having writing rights in gmic-community, so I guess we can trust them. Other contributors would have to open a pull request, which will be of course reviewed before acceptation.

1 Like

Will probably be a while before I can test this myself and contribute properly. This caught my eye in the markdown syntax:

A command between two consecutives exclamation marks is evaluated and rendered as an inlined image.

I suppose we should try to be reasonable with that!

For what reason ? Once the image is computed, it is not re-generated each time the doc is updated. To force the update, you have to explicitely remove the image file.

1 Like

Here is the newly added Funny Onliner page :

https://gmic.eu/reference/funny_oneliners.html

I think I’ll try having a more ‘classical’ markdown syntax, just as the one we can use here on pixls.us. That would be much easier to write doc.
(maybe with additional stuffs, as the G’MIC-generated image).

Not bad the idea! And acceptable for unpro gmic script rogrammers.

What about the already documented functions in gmic-community? Is there a possible space/section in the references too?

Some news:
I’m basically rewriting the G’MIC Markdown parser.
It should be more close to a “classical” Markdown syntax (e.g. the one used here, on discuss.pixls.us), but with some G’MIC extensions.
It will probably take a bit of time before it’s ready.

1 Like

Some updates:

I’ve completely rewritten a Markdown parser and its corresponding HTML translator.
So far, so good. Most of the useful classical Markdown syntax is supported.
I’m almost done with this part. Writing a markdown engine is actually quite fun!

I’ve already succeeded in generating the G’MIC reference documentation with this new markdown engine (and it is faster than the one used before).

What remains to be done, is having markdown translators to ascii (for the command-line help) and to groff (manpage). But these should be easier than HTML.

When it’s done, I’ll explain how new reference pages can be written and added to the official doc.
It will be really more simple than what I proposed before. Basically, you’ll have to add a single file My Page.gmd into the new doc/ folder of gmic-community, written in G’MIC-Markdown (usual markdown with some G’MIC-specific extensions). And this is it !

I hope everything will be fine during next week.

1 Like

Another update:

In the stdlib, there is now a command gmd2html that can be used to convert a G’MIC-markdown formatted text file (supposed to have extension .gmd) into a HTML page.
It should be as simple as:

$ gmic it input.gmd gmd2html ot out.html

So, it is now easy to write a .gmd file and see how it renders in HTML.
Do not hesitate to test and populate the gmic-community/doc/ folder !

The gmd syntax has been changed so it is almost equivalent to a classical markdown.
The G’MIC-specific extensions are :

  • You can center text and images, with:
===
Centered text
===
  • You can insert a G’MIC-computed image, with:
This is an image: %% sp bottles,200 blur 5 %%.

This is still work in progress, so expect a few bugs :slight_smile:

Things are going well and faster than expected.
The G’MIC Markdow engine seems to be ready (at least a first version) and is able to generate the HTML pages of the reference documentation (already available on the G’MIC website).

I wrote a Guide to the G’MIC Markdown syntax, as you can see this is really close to the “usual” markdown syntax, with some cool extensions available (and things that are missing, like arrays, but I’m not sure we need them for the G’MIC reference doc).

Now it’s just a matter of writing interesting content for the reference documentation :slight_smile:
Feel free to contribute, it’s now very simple to add a new page in the reference doc
(just add a new file.gmd in the doc/ folder of the gmic-community).

One request to clarification. Do these new “.gmd” files documentation have anything to do with the documentations already put into custom function? Or asked different, are the the custom function documentation pieces some sort of gmd files extended by #@cli or #@gui?

This is a way to write complete documentation pages, from scratch, and make them appear on the following page :

https://gmic.eu/reference/

(see G'MIC Markdown, Funny Oneliners and Help Writing Reference Documentation.

This will be useful only for the HTML doc I think, because I probably won’t embed it in the CLI executable (nor in the plug-in).

Ok, understood, that might thin also the gmic-stdlib.

I have still a minor problem with parse_cli images: See http://karo03.bplaced.net/gmic/html/karsten_rodenacker/region_feature.html#top

The result don’t correspond to cli output. The leftmost image should contain some text!

Maybe a suggestion: the image are not re-rendered if they already exist in the img/ folder
(because it often takes a long time).
Remove the img/ folder before regenerating the documentation ensures you’ll get the images up-to-date.

Hmm, that’s what I am doing: The folder is completely erased before.

rm -rf karsten_rodenacker
mkdir karsten_rodenacker
cd karsten_rodenacker
mkdir img
cp …/zoom.png img/.
cp /Users/karo/sw/gmic-community/include/karsten_rodenacker.gmic .
/usr/local/bin/gmic _vt100=0 karsten_rodenacker.gmic raw:karsten_rodenacker.gmic,uchar parse_cli ascii 2>&1 > karsten_rodenacker.txt
cd img
/usr/local/bin/gmic …/karsten_rodenacker.gmic raw:…/karsten_rodenacker.gmic,uchar parse_cli images
cd …
/usr/local/bin/gmic karsten_rodenacker.gmic raw:karsten_rodenacker.gmic,uchar parse_cli html

@KaRo, testing your example for command region_feature gives exactly the same result as in the page generated on your web server. I don’t see any text (I haven’t searched for the reason).

Apart from that, today, I’ve ben able to write the implementation of the Markdown->Ascii generator and plugged it in the help command. As a result, when you invoke gmic -h or gmic -h command, the output text on the console is generated by the new Markdown engine.

Hopefully, there shouldn’t be much differences with the previous version.

There are still a few bugs to fix and a few improvements to do, but I think I’m almost done with the internals of this G’MIC Markdown implementation!

Hmm, without .gmic I get for gmic 297 and the actual update297.gmic

gmic run ‘100,200 follic +threshold. 18.6% negate. label_fg. 0,1 repeat 10 region_feature… .,{$>+1},“ia,h” text[0] ${},5,{$>*20},13,1,255 done’