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 !
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.
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.
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).
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.
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 !
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
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
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?
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.
@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!
