New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Bad English in the docs #107

Open
ilyaza opened this Issue Jan 22, 2019 · 11 comments

Comments

Projects
None yet
2 participants
@ilyaza
Copy link

ilyaza commented Jan 22, 2019

Is there any interest in making the docs more readable? IIRC, I reported some issues about 10 years ago — and there was no reaction…

@dtschump

This comment has been minimized.

Copy link
Owner

dtschump commented Jan 23, 2019

Yes, we are interested by having people working on the documentation.
The best way would be to open a pull request with fixes.

@ilyaza

This comment has been minimized.

Copy link
Author

ilyaza commented Jan 23, 2019

I still live in the age of working with patches…


Anyway, a lot of things need to be resolved first. For example: what is the purpose of documentation as it stands now?! Apparently, somebody thinks that content-free sentences like

Apply non local means denoising using a image for weight and a map for scaling

have a chance to useful to somebody. What is the purpose of “documenting” things when the docs cannot be deciphered without reading the source anyway?

I do not think it makes sense to start doing anything in particular without understanding the general atmosphere first…

@dtschump

This comment has been minimized.

Copy link
Owner

dtschump commented Jan 23, 2019

It's not as conceptualized as that.
I wrote a raw documentation, lot of parts and details are still missing because I simply didn't have time to do it in detail, and no one has come forward to contribute so far (except Garry Osgood with his tutorial pages).

The reference documentation is clearly perfectible, and is intended to describe how the G'MIC language works and what commands do.

Any good contribution is welcome !

@ilyaza

This comment has been minimized.

Copy link
Author

ilyaza commented Jan 23, 2019

Given that I have (estimated) 25 man-years of stuff on my TODO list, it is hard to expect that I would be able to do anything very specific NOW. But I may be able to contribute a tiny amount of time in the form of review.

Anyway: the simplest thing (and surprisingly annoying!): there is no such word as indice. It is index/indices. (Appears 19 times…)


I may also walk through all the commands with shortcuts. The problem is that with the current state of the documentation, I would not have any clue about what it wants to say — without reading the sources… (Such as: what does it mean to “cut”?! — and such usage is everywhere…)

@dtschump

This comment has been minimized.

Copy link
Owner

dtschump commented Jan 23, 2019

Given that I have (estimated) 25 man-years of stuff on my TODO list,

This is also my case.

But I may be able to contribute a tiny amount of time in the form of review.

A small contribution is always better than no contribution at all.

Anyway: the simplest thing (and surprisingly annoying!): there is no such word as indice. It is index/indices. (Appears 19 times…)

Not sure what is the best between index and indice. I'm not a native English speaker, so
I am happy to rely on the experience of people who are more competent in English than I am.

I would not have any clue about what it wants to say 

That's a good question indeed. I'd say that as a reference documentation, it should describe as much technical information as possible about the commands and algorithms available in G'MIC, with examples. That's what I've tried to do so far, but the work is immense.

@ilyaza

This comment has been minimized.

Copy link
Author

ilyaza commented Jan 23, 2019

Let’s start: what is the target audience of https://gmic.eu/reference.shtml#subsection22? If this is people who do not know the shortcuts (like me), then how they are supposed to find a shortcut in this list?

The list is not sorted. I presume it reflects some order of sections — but if the reader does not know what the shortcut means, how grouping by sections may be relevant?

Formatting: a command takes a row — with most of the content repeated in every row. Does not this fit the format of a table better?

Shortcut h m (+) d (+) d0
Meaning help command display display0

(Although, I do not know how to choose an appropriate width of this table…)

@ilyaza

This comment has been minimized.

Copy link
Author

ilyaza commented Jan 25, 2019

A few remarks (mostly on the substitution rules):

At any time, G'MIC manages one list of numbered (and optionally named) pixel-based images,
entirely stored in computer memory (uncompressed).

Later, this list is typically refered to as “the list”. Would not it be more clear to give a name to this list of images? “Image stack”?


In G'MIC, an image processing pipeline is described as a sequence of items separated by the
space character ' '. Such items are interpreted and executed from the left to the right.

Is it correct that an item is terminated by the first space not inside “a quoted string” (meaning "…"), or a substituted expression (meaning {…})?

In particular, ${foo bar} won’t actually access the environment variable named foo bar — or does it?

Hmm, looks like ${"-pipeline"} would typically contain spaces… Is it the only exception to the rule above? Can -pipeline contain matched braces ({})? What about ${/string}?


The following reserved variables are predefined by the G'MIC interpreter:

Are they RO or R/W?


I could not find any description of what are $> and $<. I propose:

  • Add “On the first iteration $> is 0???, and $< is nb_iterations???.” to the item about them.
  • Make repeat...done into a hyperlink in the same item.

$/: The current call stack. Stack items are separated by slashes /.

What is a stack item? Is there whitespace about the separating slash?


$_cpus: The number of computation cores available on your machine.

Given that OpenCL is used, it is the number of cores in the graphic card — or what???


${"-pipeline"} is substituted by the status value after the execution of the specified
G'MIC pipeline (see command status).

Replace by

${"-pipeline"} executes the specified G'MIC pipeline, then returns the current status value (see command status).


{/string} is substituted by the escaped version of the specified string.

Escaping what and how?


u: screen width (actually independent on the window size).

I suspect that “Independent” cannot be “on”. Moreover, I have no clue what is the meaning of the remark in parentheses. In fact, I also have no clue what “display width” means. Is it the sum of widths of all the attached independent displays, or the minimal width of dependent displays, or what?

Similarly: no clue about “display width” and “window width”. Which is larger, and by what?

n: current normalization type of the instant display.

BTW, I do not see where what “normalization” means is described, and/or what the different values given to w0 mean.

o: state of the mouse wheel.

Which one of mouse wheels? What are the possible values of this? BTW, is there access to Prev/Next mouse buttons???

k: decimal code of the pressed key if any, 0 otherwise.

Which decimal code? Scancode, virtial code?

c: boolean (0 or 1) telling if the instant display has been closed recently.

How “recently”? Is not it just “is closed”? Same for r and m. Or are they related to the last display() function or wait command?

Any other feature stands for a keycode name (in capital letters), and is substituted by

What is a “keycode name”? Name matching the C macro for a virtual key?

(works for keys, mouse and window events).

Do not see any mention of window events… Does it mean r and m?


One can also disable the substitution mechanism on items outside double quotes, by escaping the
{,} or $ characters, as in {3+4} doesn't evaluate.

Looks like escape characters are lost somewhere…

@dtschump

This comment has been minimized.

Copy link
Owner

dtschump commented Jan 25, 2019

A few remarks (mostly on the substitution rules):

At any time, G'MIC manages one list of numbered (and optionally named) pixel-based images,
entirely stored in computer memory (uncompressed).

Later, this list is typically refered to as “the list”. Would not it be more clear to give a name to this list of images? “Image stack”?

I've already seen this terminology of "stack" used here and there to describe how G'MIC works , but I'm not really sure this is the correct way of describing it. In algorithmics, a "stack" is actually a particular data structure which does not correspond to what the G’MIC list of images is (see https://en.wikipedia.org/wiki/Stack_(abstract_data_type)). In G’MIC, you can access to each elements individually, change their relative positions, insert or delete a new image everywhere and so on…
It's clearly more close to what a "list" is (https://en.wikipedia.org/wiki/List_(abstract_data_type)).

In G'MIC, an image processing pipeline is described as a sequence of items separated by the
space character ' '. Such items are interpreted and executed from the left to the right.

Is it correct that an item is terminated by the first space not inside “a quoted string” (meaning "…"), or a substituted expression (meaning {…})?

Yes.

In particular, ${foo bar} won’t actually access the environment variable named foo bar — or does it?

No, an environment variable cannot have space in its name, nor does a G'MIC variable.
${foo bar} defines indeed two items ${foo and bar}.

Hmm, looks like ${"-pipeline"} would typically contain spaces… Is it the only exception to the rule above? Can -pipeline contain matched braces ({})? What about ${/string}?

Yes, it will often contain spaces, but then you need to double-quote it, e.g.

A=${"-bin2dec 10011011"}

The following reserved variables are predefined by the G'MIC interpreter:

Are they RO or R/W?

Those with valid variable names are R/W ($_cpus, $_pid, $_prerelease, $_version, $_vt100, $_path_rc, $_path_user), the others only RO.

I could not find any description of what are $> and $<. I propose:

  • Add “On the first iteration $> is 0???, and $< is nb_iterations???.” to the item about them.

Yes, except that $< goes from nb_iterations-1 to 0 .

  • Make repeat...done into a hyperlink in the same item.

$/: The current call stack. Stack items are separated by slashes /.

What is a stack item? Is there whitespace about the separating slash?

A call stack is usually something like ./command1/command2/*if/ so, a string composed of stack items separated by /.

$_cpus: The number of computation cores available on your machine.

Given that OpenCL is used, it is the number of cores in the graphic card — or what???

No, OpenCL is not used in G'MIC. But OpenMP is. And it corresponds to the number of CPU cores OpenMP is able to use when multi-threading algorithm executions.

${"-pipeline"} is substituted by the status value after the execution of the specified
G'MIC pipeline (see command status).

Replace by

${"-pipeline"} executes the specified G'MIC pipeline, then returns the current status value (see command status).

{/string} is substituted by the escaped version of the specified string.

Escaping what and how?

Typically, replacing the non alpha characters to a sequence of backlashed ones.
like in this example:

foo:
  (10)       # Image a single value 10 (LF ascii code).
  txt={t}    # 'txt' contains non-alphanumerical character 10
  txt2={/$txt} # ''txt2' contains '/n'

u: screen width (actually independent on the window size).

I suspect that “Independent” cannot be “on”. Moreover, I have no clue what is the meaning of the remark in parentheses. In fact, I also have no clue what “display width” means. Is it the sum of widths of all the attached independent displays, or the minimal width of dependent displays, or what?

The display width is the width of the display window. Maybe 'window width' could be better.
A display window is displayed on a screen, which has its own width. And {*1,u}, {*2,u} {*3,u} will always return the same values if the windows are on the same screen (so the width of the screen is independent on the display window number invoked to get this info).

Similarly: no clue about “display width” and “window width”. Which is larger, and by what?

Sometimes, the display width is really large, and the WM decided to displays it in a smaller window, so usually 'display width>=display_width'.

n: current normalization type of the instant display.

BTW, I do not see where what “normalization” means is described, and/or what the different values given to w0 mean.

Meaning:
0 = no values normalization
1 = always normalize values between 0 and 255 before displaying an image
2 = normalize only once, then keep the same normalization factor afterwards.

o: state of the mouse wheel.

Which one of mouse wheels? What are the possible values of this? BTW, is there access to Prev/Next mouse buttons???

{*,o} is a signed integer which counts the number of steps the mouse wheel has been scrolled. Depending on your mouse settings, it can have a quite high absolute value.
G'MIC only knows how to access the three main mouse buttons and the wheel. That's it for the mouse buttons.

k: decimal code of the pressed key if any, 0 otherwise.

Which decimal code? Scancode, virtial code?

Yes, I think this is an hard-coded code. Nobody really uses this I guess, because it's more convenient to test for '{*,ESC}' for instance to check if the ESC key has been pressed or not.
I guess I could even remove this feature.

c: boolean (0 or 1) telling if the instant display has been closed recently.

How “recently”? Is not it just “is closed”? Same for r and m. Or are they related to the last display() function or wait command?

Same as before. This is not used in practice.

Any other feature stands for a keycode name (in capital letters), and is substituted by

What is a “keycode name”? Name matching the C macro for a virtual key?

(works for keys, mouse and window events).

Do not see any mention of window events… Does it mean r and m?

One can also disable the substitution mechanism on items outside double quotes, by escaping the
{,} or $ characters, as in {3+4} doesn't evaluate.

Looks like escape characters are lost somewhere…

@ilyaza

This comment has been minimized.

Copy link
Author

ilyaza commented Jan 26, 2019

Thanks for clarifications! My point was that this should be reflected in documentation.

Below, I address issues not yet clarified enough.

Later, this list is typically refered to as “the list”. Would not it be more clear to give a name to this list of images? “Image stack”?

I've already seen this terminology of "stack" used here and there to describe how G'MIC works , but I'm not really sure this is the correct way of describing it. In algorithmics, a "stack" is actually a particular data structure which does not correspond to what the G’MIC list of images is (see https://en.wikipedia.org/wiki/Stack_(abstract_data_type)). In G’MIC, you can access to each elements

Well, there are “theory of algorithms” stacks, and there is the programming-languages practice. I do not recall ever seeing the main stack of the programming environment implemented so that only the abstract stack operations are available. What is common for all stacks is that it is easy to put something at the end.

Anyway, my suggestion was, in fact, more about an adjective than about the noun. “The stack” is way worse than “the image stack”; likewise, the current usage of just “the list” is kinda horrible.

In G'MIC, an image processing pipeline is described as a sequence of items separated by the
space character ' '. Such items are interpreted and executed from the left to the right.

Is it correct that an item is terminated by the first space not inside “a quoted string” (meaning "…"), or a substituted expression (meaning {…})?

Yes.

In particular, ${foo bar} won’t actually access the environment variable named foo bar — or does it?

No, an environment variable cannot have space in its name.

This is definitely absolutely wrong.

${foo bar} defines indeed two items ${foo and bar}.

David, your choice of words baffles me all the time…. When you say “defines”, do you mean “accesses”, as in “${foo bar} is the same as $foo" "$bar”? Does it produce 2 items, or 1?

BTW, can expansion create several items (as in Bourne shell)?

Hmm, looks like ${"-pipeline"} would typically contain spaces… Is it the only exception to the rule above? Can -pipeline contain matched braces ({})? What about ${/string}?

Yes, it will often contain spaces, but then you need to double-quote it, e.g.

A=${"-bin2dec 10011011"}

Again, this is completely unclear. It is already documented as requiring double-quotes! And what about A=${"name=11011 name1="100"${name} -bin2dec ${name1}"} — is is a legal syntax? What about including a pipeline inside a pipeline? Including double-quoted things inside a pipeline?

Looking in std library, I have no clue how to explain how

L_origine=${"-samj_RGB_to_LCH_or_Lab[] 1,"{/$R_val}","{/$G_val}","{/$B_val}","{/$Matrices_RGB}","{/$XYZ_Tristimulus}","{/$Choix}""}

is expanded…

$/: The current call stack. Stack items are separated by slashes /.

What is a stack item? Is there whitespace about the separating slash?

A call stack is usually something like ./command1/command2/*if/ so, a string composed of stack items separated by /.

I still have no clue what is “a stack item”! .?! *if?! BTW, is the last item in your example empty?

$_cpus: The number of computation cores available on your machine.

Given that OpenCL is used, it is the number of cores in the graphic card — or what???

No, OpenCL is not used in G'MIC. But OpenMP is. And it corresponds to the number of CPU cores OpenMP is able to use when multi-threading algorithm executions.

??? Did you just say that the target directive is not used in the current implementation?

{/string} is substituted by the escaped version of the specified string.

Escaping what and how?

Typically, replacing the non alpha characters to a sequence of backlashed ones.
like in this example:

foo:
  (10)       # Image a single value 10 (LF ascii code).
  txt={t}    # 'txt' contains non-alphanumerical character 10
  txt2={/$txt} # ''txt2' contains '/n'

“Alpha” or “alphanum” or “alphanum or _”? Is this behaviour useful anywhere? Looking in the standard library, I can see it only used

  • in undocumented example with L_origine quoted above;
  • to be put into "…", or
  • as narg({/$foo}), or
  • as ${'{/$foo}'}.

However, I’m not sure the corresponding behavior of ${'…'} is defined in the docs. How is ${'…'} treating \n?

And: the behavior of "…" w.r.t. backslashed characters is not described. Likewise for narg(…) — what exactly is needed for this “protection”; is narg(…) just counting commas in a string? But as you said, there is going to be no commas — or what? What if the string contains parentheses?

BTW, I presume /n is a misprint…

u: screen width (actually independent on the window size).

… In fact, I also have no clue what “display width” means. Is it the sum of widths of all the attached independent displays, or the minimal width of dependent displays, or what?

The display width is the width of the display window. Maybe 'window width' could be better.

Again, this is very vague. Does this include windows decorations (border etc), or not?

Similarly: no clue about “display width” and “window width”. Which is larger, and by what?

Sometimes, the display width is really large, and the WM decided to displays it in a smaller window, so usually 'display width>=display_width'.

This does not correlate with what you have written above!

Such notions are usually addressed by using terms like “canvas” and/or “viewport”. So “a window” is shown to the user on “a monitor’s screen”, and the window shows a certain subset of the “canvas” (which you call “display”, right?). So my question about decorations should be transplanted to a different word you use — but it still remains!

n: current normalization type of the instant display.

BTW, I do not see where what “normalization” means is described, and/or what the different values given to w0 mean.

Meaning:
0 = no values normalization
1 = always normalize values between 0 and 255 before displaying an image
2 = normalize only once, then keep the same normalization factor afterwards.

David!!! Did not you notice that you still did not define “normalization”?!

o: state of the mouse wheel.

{*,o} is a signed integer which counts the number of steps the mouse wheel has been scrolled. Depending on your mouse settings, it can have a quite high absolute value.

And the sign means what?! (Do you remember that the default interpretation was changed between Win7 and Win8?) Let me restate: which sign matches “the typical action” of PgDn key?

G'MIC only knows how to access the three main mouse buttons and the wheel. That's it for the mouse buttons.

Again: when you say “the wheel”, you mean “the wheel for vertical scrolling”, right?

k: decimal code of the pressed key if any, 0 otherwise.

Which decimal code? Scancode, virtial code?

Yes, I think this is an hard-coded code.

This sentence does not help to understand what the term means…

I guess I could even remove this feature.

Well, one could just say something like “system-dependent code”, or “G’Mic-internal code (see foo.c)”…

@ilyaza

This comment has been minimized.

Copy link
Author

ilyaza commented Jan 26, 2019

Thinking about this more: all you need to say to explain your “normalization” is which value is shown as black, and which is shown as white.

@ilyaza

This comment has been minimized.

Copy link
Author

ilyaza commented Jan 26, 2019

Hmm, Win7 vs. Win8 may have been related to touchpad→scrollwheel translation, not the scrollwheel itself — I do not remember details. Anyway, the “up” movement of the scrollwheel may correspond to

  • moving the viewport up w.r.t. the canvas;
  • moving the canvas up w.r.t. the scrollport.

Different systems have different default interpretations of this — and sometimes (at least on Windows) the interpretation may be changed.

Is this somehow reflected in the sign of reported value?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment