Instructions to help writing reference documentation

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 G'MIC - GREYC's Magic for Image Computing: A Full-Featured Open-Source Framework for Image Processing - Reference Documentation - region_feature

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’

Confirmed. I’m investigating.

Basically, your command line should be:

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

(i.e. replace the ${} by {``${}} ).

because as ${} contains a comma , and so, the second value of ${} is assumed to be the second argument of text (the y-coordinate), and as this value is very high, it just outside the image boundaries, and the text does not show up.

Then, I would say that the behavior obtained with the parse_cli images is the good one.
Now I have to understand why the run command does not behaves the same…

EDIT:

If you run the command line directly from the shell, without using run,

$ gmic 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

then you get the same result as with parse_cli images.

So there must be something wrong with the run command!

@KaRo, if you create this command:

foo : 
  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"

then, you’ll get the same (expected) result as with parse_cli.
Thus, I suspect some bash wizardry here : probably there is something substituted in the command line before passing it to G’MIC. Probably ${}

EDIT : Found it!
the double quotes in the "ia,h" part should be escaped: \"ia,h\" in the command line to make it working as expected.
So, sorry but this time, not a bug from G’MIC :slight_smile:

Puah, thank you David for your work. Just these are the traps of gmic script mentioned from the other programmers!

I have still more of that type: I am not able to preserve under Windows the “\” in

gmic 400,200 kr_draw_vars 1

This is just a routine for gimp tests in case of trouble. Also just the function showing in my virtual Windows is_macos and is_windows both true with

gmic 400,200 kr_draw_vars 0

Thank you again.

By the way I’m using zsh and sometimes bash, since Apple has changed the default shell to zsh.

A trap from the shell instead… For complex command lines with substituting expressions, avoid as much as possible running it directly from the command line, to avoid to deal with the shell substitution.
Even if run helps a bit, it does not solve all the possible problems due to shell substitutions.

Should be fixed (I’ve made some modifications to your files).

Fixed as well (was a bug in is_macos in the stdlib).

Some news:
@grosgood and I have started to write/convert new tutorial pages, with the new G’MIC Markdown engine. Some cool stuffs going on :slight_smile:

You should be able to see the pages here: https://gmic.eu/newtutorial/

There’s not much to see right now, but at least everything seems to be here to construct something interesting!

Let us know what you think.

1 Like

@grosgood is in a rush! Tutorial pages are starting to take shape:

https://gmic.eu/newtutorial/

Some notes about what I’ve done these last days, trying to make things better, in parallel to the pages written by @grosgood.

In particular :

  • Automatic anchors put for each section/subsection.
  • Explicit anchor links in text (equivalent to invisible sections).
  • Rendering of math formula as embedded images (with pdflatex and gs).
  • Blockquotes.
  • Detail block.
  • Shell command.

I’m probably done with it, unless someone has a very special need that could not be replaced by an existing syntax.
I was thinking about adding tables, but I’m not really fan of the idea anymore, mainly because:

  • The G’MIC-Markdown has to generate, not only HTML pages, but also ascii (for console) and man pages. Formating tables in ascii is a pain, and it’s almost impossible to get a coherent rendering of a table in ascii.
  • I believe tables can actually be replaced most of the time by a different presentation. And if you really need tables, then it’s still possible to generate one, either with a G’MIC pipeline, or a LaTeX formula.

I’ve also re-implemented a “tutorial generation script” from scratch, that generates the tutorial pages according to the G’MIC website structure. I’ll be able to re-generate the complete tutorial pages at each new G’MIC release (just as I do for the reference documentation). It will ensure that the generated image and text will be always up-to-date.

What I need to do now is:

  • Finalize the ascii and man output for the Markdown generator, implementing the latest features for these outputs.
  • Continue converting the existing tutorial pages into the new markdown format.
  • Convince people other than @grosgood to write documentation pages as well. It’s now easier than ever :slight_smile:
2 Likes

Yes, it is. git pull/push to gmic-community, markdown, gmd2html for previewing. gitk, (the git GTK repository browser), seems to be the essential tools here. All of these substantially reduce the logistics of posting documentation and seeing what other contributors are doing. Kudo’s to @David_Tschumperle and whoever helped him.

That leads to the writing.

Every FOSS project lacks documentation. To my mind, it is the single greatest barrier to FOSS adoption. If people don’t understand how to use it, they won’t use it. Period. Full stop. Faster to buy a license to a commercial product and call the support line, look at the slick videos they’ve prepared. Maybe (!) read the user manual.

I think everybody is a born writer. But eighty percent of us develop a permanent writer’s block. Sets in after the age of seven or eight, I think. Fifteen percent of us can manage tweets, maybe email. Five percent can hit the ground running.

I’m a professional writer. But I’m not in that five percent. Most days, I feel awful when I start to write. Words don’t come. There’s a barrier I have to get over. Once I’m over it, I’m fine. How to get over that barrier? How do I get over that barrier?

A very long time ago, my technical writing mentor suggested that I close my eyes and imagine someone sitting across from me. I just need to explain something to that person, that’s all. Imagining writing as a kind of conversation with another person has always helped getting over that barrier.

In that line, I like to think that I need to tell that person three things about a gmic command:
(1) An essential summary that covers what the command does. I imagine that the person may be suddenly called away with the phone or a baby crying (!!! can’t ignore that!). So if they get the gist of the command, that is something accomplished.
(2) Then (if the person is still with me), a few examples of how the command is used.
a. Usually one example that is straightforward,
b. One that is a little more complicated, but serving a ‘real world’ purpose,
c. And one - if possible! - that uses the command in a novel, unexpected way: it has an ‘Ah HA!’ twist. If nothing else, people find plot-twists amusing.
(3) Then, the command reference.

That’s my outline, (1), (2), (3). That’s how I’m (re) organizing these tutorials in the present round. You’ll see that Summary-Example-Command reference template throughout. Having that template also organizes my thinking, so I can imagine what I need to say to that imaginary person, so I can imagine myself saying that to the imaginary person. So writing is just transcribing that inner voice talking to the imaginary person.

In the flow of writing, (3) is much easier than (2), (2) is usually easier than (1), and (1) is hard. Recall the famous apology: “I’m sorry I wrote you a long letter. I did not have time to write you a short one.”

Distillation is always hard. Distillation is what happens from (2) to (1). David has made (3) trivial: just write the inclusion markdown for a command and you have exactly what gmic -h supplies. Perhaps write a few helpful notes after the inclusion. (2) arises from just playing/experimenting with the command. Seeing examples here at pixls.us/gmic is always useful. Everybody: please post more! Playing and experimenting is the fun part of tutorial experience. At its conclusion, it is a matter of choosing the best examples and writing those up. Then there is the gist of the command; (1). I save that to the last. I find that if I’ve played a lot during (2), (1) becomes easier to write.

As you may have gathered, I write these tutorials backwards: (3) - study the reference (2) - play with the command. Then try doing useful things. Then trying for that "ah HA!’ moment. Then organizing my thoughts for (1).

So you have trouble starting to write. I feel that pain. But there is this: I’m almost 70 (!). As a project planner once quipped to me: “In the long run, we’re all dead.” Funny. Ha, Ha. But in the heart of that bittersweet joke there is this truth: If we care about this thing, we got to tell the people coming on board how to play with it. How to work with it.

While we still can.

2 Likes

Love Wikipedia. Among other things, it is a repository of pdflatex markup for math. You can use it as a big cheat sheet.

  1. Browse math articles `til you see a construct near to what you like.
  2. Edit the section (your browser fills with media-wiki markup) You may have to click past the offer to use the new article editor. You want to go Old School.
  3. In the media-wiki markup, find your desired math construct. It will be nestled between
    <math>...</math> tags. These are analogous to $$...$$ notation.
  4. copy - paste to your document.
  5. Cancel out of editing the Wikipedia section.
  6. You may have to tweak a few constructs. \begin{alignat}, common for matrices, seems problematical, but can be deleted. If you do such, don’t forget to delete the matching \end{alignat} too.
  7. You may see {math}...{math} notation as well. Those appear to have a different syntax and markup conventions. I haven’t been able to use them.
  8. You don’t need an editor account unless the article is in the midst of an edit war and Wikipedia administrators have put restrictions in place. Edit wars are not common with math articles. And if you can’t get into one, there are other, more peaceful articles.

Back to documentation…

Whitespace fixes following 3/16 discussion with David T. on the insertion of images in tables. Addendum: Unless one has a specific reason in mind, it is generally not a good idea to have leading or trailing whitespace on images in a table. Bad form: | ![e1](img/eigen_01.png) |. Trailing and leading whitespace around the table marker |. Good form: |![e1](img/eigen_01.png)|. Note that the table intrinsically furnishes its own padding around text and images in table cells. Such excess white space has to go somewhere, and it may unceremoniously wrap images, causing misalignment, or lead to excessive margins around images. Some Rainy Day Sunday after Breakfast, I’ll write a G’MIC Markdown Cheat Sheet, but until then, read it first in git log.

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