Because I'm trying to benefit of what provided nicely to me so far (Ron, GC), therefore I read often the G'MIC Reference Manual to understand (when I succeed...) available commands, I was just wondering whether who is in charge of the R.M. could be interested in reading the comments of a novice about what a novice considers incomplete or missing or not easily understandable in the manual.
If so, I will use this topic to post from time to time my comments, otherwise please remove this topic.
Thanks

Yes, please tell us and do not hesitate to propose some words that could be added to the reference documentation. That's very interesting!

Good idea, I wish I'd taken notes while I was learning too.

I'd be confused about something and look through other people's code and experiment to figure it out. Then quite often I'd think "now why isn't that in the reference?", only to discover it is actually there - just in a very small bit of text that describes it as concisely as possible. It's SO easy to miss something because the commands are often short (as well as the description)!

Even if you have a suggestion that's too big for the reference it can always be put on the wiki

OK.
I will make distinct posts for each comment.

Comment #1
--------------
image definition
when defining a new image (let's say: 300,300,1,3 or 300,300,1,4)
is it possible to have it initialized with a colour?
I didn't find a way
so, any new image seems to be black
is it so?
doc should say it explicitly

Comment #2
---------------
command -shift
first two values can be entered both as percentage (of current image) or as absolute numbers
so, looking at the sample image and sample commands
-shift 50%,50%,0,0,0 shifts the top left quarter of the image to the bottom right quarter: fine!
I had an image with the top half filled with a real image and the bottom half purely black,
so I tried to say: 0%,50%,0,0,0: surprisingly, resulting image was totally black
I made some trials with different percentages of width: everything OK while I used a value different from 0%.
So, because I had the necessity to shift the top half to the bottom one, I was on the way to enter just 1% as width then adjusting with other tricks the result; but suddenly I had the curiosity to see whether using an absolute value could work and I put 0 as first parameter, instead of 0%: wow, it worked.
Is this inconsistency between 0% and 0 an error? or is it according to the mysterious rules of G'mic?
In both cases, doc should mention explicitly how to behave if the user wants to shift along only one dimension.

Comment #3
-----------------
what does it mean boundary=dirichlet or boundary=neumann?
I didn't find an explanation for such terms.
Doc should explain used terms, either in the preface or during first use

Excellent idea dinasset.
I too have been interested in writing some new G'MIC filters.It will be nice to check this topic for info when needed.

All of your comments are valid in the sense that it's not easy to spot the answers, but here are some things to note:

Comment #1 - From under heading "Input data items":
. 'width[%],_height[%],_depth[%],_spectrum[%],_values': Insert a new image with
specified size and values (adding '%' to a dimension means 'percentage of the size
along the same axis, taken from the last image '[-1]'')
Comment #2 - Not sure what's going on with that one, it doesn't do that for me

Comment #3 - These are mathematical expressions known in the image processing field, the library is intended mainly as a tool for scientists so to explain terms they probably already understand is not relevant for the reference (I don't understand many of them either since I'm no scientist so I tend to look them up on wikipedia!).
For most purposes the way I tend to think of boundaries is dirichlet = black, neumann = copy edge pixels. So if you shift an image with dirichlet boundary, any space gets filled in black.

@comment #1
OK, but how should values be entered? With one value (255) it works, fine! the image is created white, but when I tried to enter a triplet for rgb like (64,128,192) or [64,128,192]
it didn't accept the syntax; is it possible to enter separated values for r,g and b? if yes, how? just entering 3 separated values without parenthesis it creates grey stripes.
How should a novice reader extrapolate in advance from the description the result?
please, doc should specify: whether is it possible to enter a specific colour and how, and - if only a grey in accepted, what's the meaning of the series of values....

@comment #2
do what I did to try:
100%,50%,1,3 #create a new image with same width and half the height
this one goes on the top part of the existing image
fill it with some nice mix of colours, plasma, etc.
resize to 200% of height (which corresponds to the original image size)
bottom part is black
shift it using both types I shown:
1- 0,50%,0,0,0 the top half is shifted as expected to the bottom one
2- 0%,50%,0,0,0 everything is black
try to shift

@comment #3
sorry, I disagree: a reference manual should be for understanding/using the language
somebody who likes experimenting the language should be able to find full explanations,
not only the scientists...

You cannot do that when initializing an image. Assuming that an image contains 'color' pixels is already wrong :
We are more generic than that Command '-fill_color' (eq. to '-fc') can be used to fill a color image with prescribed values along the c-axis.

I agree with the image values thing - I wasn't sure about it myself for ages. All adding a list of values does is literally put those values in one by one repeatedly into the buffer. So for instance if you do 3,1,1,3,255,0 you will get a 3 pixel image with one magenta pixel, one green then another magenta. This is because it first adds 255,0,255 onto the red plane, then 0,255,0 onto green then 255,0,255 on blue (it's just repeating the 255,0 each time wrapping onto the next channel). And yes, as David says you can't really assume it's an image at all - you are creating an array of values which could represent anything you want.

When you say about full explanations, I assume you mean describing them in a way non-scientists can understand? Obviously giving full math explanations would be a HUGE undertaking! It's actually quite difficult to explain a lot of them in plain terms, perhaps this forum thread can be used as a start to doing just that... then maybe we can at least put some on the wiki. So keep the questions coming

@comment #1
so, IMO, it would be enough to enter in the doc at page 8, after 'spectrum' definizion,
"- assuming that the new image contains 'color' pixels is wrong, thus after having created a new image make use of command -fill_color to fill a color image with prescribed values along the c-axis." (I used David's words)
not a big addition but a very useful indication for the reader

@comment #3: so far, I just found the terms mentioned in my previous post as totally unclear for a non-scientist (well, I didn't read the whole manual of course!) and also in this case it would be a small note like "dirichlet=fill emptied pixels with black; neumann=replicate the boundary pixels into the emptied pixels" (very likely my words are incorrect, but was just to say that for a non-scientist is enough a small note, entered just once in the manual); I will continue mentioning what a non-scientist novice reader does not understand; if at the end it's just a matter of 10-20 terms it is enough a very very small dictionary at the end of the manual.

IMHO, there should be a separation between the 'Reference manual' and a 'User's guide'.
The reference manual should describe all the 'technical' aspects of the software, and should target experimented users (so, mainly image processing scientists probably that are not afraid of script languages, yes, there are probably only few people concerned on earth ).
This is what we already have, and it has already more than 350 pages ! It's a kind of forbidding document that you don't want to read in a single shot. Note that most of the current document is generated automatically from the command definitions, so we don't have many flexibility to add lot of examples and good-looking paragraphs to make it easier to read.

I don't think this kind of document should teach users what basic image processing is (it would require another set of 350 pages probably to make it clear enough for everyone, who'd like to read such a monster ? ).
On the other way, it appears clearly to me that having a 'User's guide' available would be necessary, mainly with 'tutorials', or explanations of basic terms we can meet in the reference manual.
Maybe this should be a compilation of the 'wiki pages' (if there were more of them).

There is clearly a lack of available documentation. But it is not really surprising as G'MIC has not (yet) gathered a lot of G'MIC script writers !

So, any contributions are welcome

These G'MIC Tutorials will be helpful for command line users.

I found a few more G'MIC tutorials.
Official G'MIC Tutorial
Flickr G'MIC (tutorial list)
18 most useful G'mic scripts for beginners.
A Tutorial only using G'MIC, Somewhat Painless Seamless Plaid Tutorial Using G'MIC

A G'MIC search of YouTube will find many more.

@David
I really don't understand your last post: not WHAT you say but WHY you say that.
In my last post I was just suggesting the addition of one-two lines to the image definition command and one-two lines to the first reference to "dirichlet, neumann, ...)
These kind of additions DO NOT double the manual and are related to the "technical" info.
I thought they were in the direction of your INITIAL reply-post:
"Yes, please tell us and do not hesitate to propose some words that could be added to the reference documentation. That's very interesting!".
This was my goal, I don't like to enter into the tutorials game, I like to stay on technical aspects (look for instance to my second comment: why 0% does not behave as 0? is it REALLY clear to a scientist?)
The real problem, I guess, which comes out from your last post is: the RM is produced MAINLY automatically from the command definitions.
In this case is more or less useless to ask for additions...
Thus I stop commenting on the RM.
Should I in the future be willing to contribute to tutorials (os User Manual), I will open a new topic.

I agree partially with you dinasset. Adding the lines you suggested will not double the size of the reference documentation.
But I'm definitely not sure we should mention what Dirichlet and Neumann boundary conditions are, in the reference doc, that's all. These terms are very common to define boundary conditions in the image processing field...
So, if we describe that, maybe someone will ask us to also define what a convolution is, what a PDE is, what a Fourier transform is, etc... and I'm afraid we will end up with a complete book on image processing at the end !
Those terms are nothing to do with G'MIC programming, which was the primary objective of the reference manual.

Concerning your shift problem : 0% behave as 0, this is not the problem. The problem is that if you shift an image with 50% along the y-axis, it will shift the image forward, so to the bottom. If you want to shift it to the top, you should call '-shift 0,-50%'. I guess this is one possible explanation of what you get.

David, what happened to me (maybe I can reproduce it again as soon as I have a little time) is that:
-using shift 0, 50%, 0, 0 I get what I want (top half moved to bottom)
-using shift 0%,50%,0,0 I get a totally black image
between the 2 trials nothing else was changed: I had 0% as first parameter in the command, I saw the black result, just changed 0% to 0 and I got what I wanted.
To re-check I re-changed back from 0 to 0% and I got again a black image, so I definitely fixed the first parameter to 0.
Maybe it only happens in my environment, don't know...

Ha that's an interesting point. Looks like a bug to me, as on my machine (Ubuntu Linux 32bits), it doesn't behave like that. I will try to reproduce this behavior on other machines.