# Instructions to help writing reference documentation

@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

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.

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

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
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.

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
$...$ 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 ?

Current generation of orientation.html:

Note the “blue monkey bounce”

Removing white space:

No blue monkey bounce, and the bottom margins of the following three images have consistent margins all around.

In the current orientation.html, use the HTML inspector. You’ll see space characters in the cell.

I don’t know if you want to go the route of automagically trimming white space in the implementation. Seems easier to suggest to folk not to stick white space around images unless (for some tricky reason) you are deliberately putting white space. Can’t imagine what that tricky reason might be.

Apropos of nothing on this thread: Thanks for bringing Fingerpainting forward!

1 Like

I’ll check that. Putting a space is more natural than not, so the rendering should be the same with a space or not.

It should be OK now, after a gmic up.

Probably, in the spirit of Markdown, preparing the presentation should not entail fiddle-faddle, including fiddling with white space around images in a table. That kind of fiddling indeed seems contrary to the Markdown spirit. But in the meantime, while this tool develops… take care with the white space around images.

David. As always - thank you for the quick turnaround!
But… Darn…

gmic update
cd git_repositories/gmic-community
git tag oldspace 'HEAD@{1 day ago}'
git branch --create OldSpace oldspace
git checkout OldSpace
cd tutorial/valuesmanip
gmic it orientation.gmd gmd2html 2 ot orientation.html


gmic update? check.

gmic it orientation.gmd gmd2html 2 ot orientation.html
[gmic]-0./ Start G'MIC interpreter.
[gmic]-0./ Input text-data file 'orientation.gmd'.
[gmic]-1./ Output image [0] as text-data file 'orientation.html'.
[gmic]-1./ End G'MIC interpreter.


And… I still get the bounce.

By any chance, you didn’t happen to test at the current HEAD? orientation.gmd and friends already had space characters taken out of the table this morning, EDT, and would not reflect the issue. To test, I kicked back a few commits (to a local OldSpace branch)

Markup looks like this (at OldSpace: be3064bc)

|| __Original__ | __Color Vectors__ | __Vector Lengths__ | __Factors__
|  ![orig](img/m_alpha.png) | ![colorvecs](img/m_cpv.png) | ![vectorlen](img/m_nrm.png) | ![factors](img/m_fac.png)


It looks like this, now, at HEAD on master 80d227f8

||__Original__|__Color Vectors__|__Vector Lengths__|__Factors__
|![orig](img/m_alpha.png)|![colorvecs](img/m_cpv.png)|![vectorlen](img/m_nrm.png)|![factors](img/m_fac.png)


I.e., white space removed from the current version. It wouldn’t reflect the problem.

I’ve just detected one whitespace around the |, if you have more (two) there will be still a whitespace in the generated code. Maybe this could explain that ?

1 Like

Yes. In fact, before the exclamation point  ![orig] there are two space characters. What appears to be happening in the table cell (in HTML) for my browser (Firefox 78.8) is that the browser is wrapping after the second space character, putting the blue monkey on the second line in that particular cell, so it appears to bounce down.

This particular behavior is in no way hindering me: as noted, I just remove white space now. I do, DO, appreciate the care and attention you are giving this for the general Markdown user - who shouldn’t really need to fiddle with things like white space around images. Take care!

1 Like

Addendum: To be truthful, the browser is wrapping after a space character. I actually didn’t do a count.

Just noticed this oddity…
G’MIC command line help always points to an “oldtutorial” URL even if one never existed, as in -store, which was composed fresh as a 2.9 tutorial; an “oldtutorial” form was never written:

The Technical Reference Page page has a Tutorial Page for -store that points to the right place. Alas, at the bottom of that tutorial page, there is an expansion of $gmic -h store which, as you know, is just a reproduction of the shell command and therefore points to the phantom tutorial. That could be a trifling confusing. Only done spot-checking, but it seems that all command line help references a page in the oldtutorial section, whether the target URL exists or not. This is Version 2.9.8 (pre-release #210605) Edit: Rummaging around gmic/src/gmic_stdlib.gmic:4151-4252 • 4230-4231 - I get the impression that - regardless of flags being set - the eventual setting of $url` will have an ‘oldtutorial’ form. Haven’t grasped the logic yet on how flags are set.

Bookmarked for further contemplation, when east-pointing shadows grow long here on the Eastern Seaboard of North America. Civilization calls now…

I noticed this too but didn’t report it because I thought something was being done under the hood. Gives G’MIC an old world feel.

1 Like