Improvement of reference documentation



IMO “list” is fine, as you say stack has a specific meaning in CS. In fact if you compare to another language e.g. java the behaviour of “arraylist” is much the same.


List is definitely the correct word in both the technical and English sense. That said, the language could be phrased better. E.g.,

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

G'MIC keeps track of images in a numbered list starting from 0. A name could also be assigned to an image.

Of course, this is just an example and doesn’t include all the information from Overall Context. Just as it was when we worked on the slides and content for the G’MIC presentation, it is obvious that there is room for improvement in the language department. However, nowhere is this a barrier to understanding the technical information. What @snibgo, others and I have mentioned is more pertinent.

(Alan Gibson) #23

In this context, we have a list of images, not a stack. (ImageMagick developers use stack, but I don’t agree.)

Singular “index”, plural “indices” or “indexes”. There is no English word “indice”. Non-English words hinder translation into other languages, so are best avoided.

But lack of information is a bigger problem.


I agree that it would be best to change indice for the sake of translation (even though Google Translate understands it just fine). As I indicated above, its usage is rare: dictionaries mark it as obsolete. Generally, it is index and indices. There is a subtle difference between indices and indexes; either is fine.


This is not the best example because the two different code types are organized in distinct parts of this entry. What makes it confusing is when they appear in flowing text. E.g., sometimes the same word is highlighted and other times it isn’t.

There are other reasons why I included this screenshot.

1. The non-highlighted code text is way too thin. Very hard to read. I suggest you highlight them as well. If you want them to be distinct, use another colour.

2. I have decided that bolded code is too distracting to the eye. All I could see is apply_tiles. :see_no_evil: Secondly, for consistency, keep both apply_tiles the same style (size). Maybe change the bold (<strong>) to an italic (<em>), or maybe it would be better to just make it the same style as default values, since it is a proper title anyway and not code.

3. Remember how I suggested that you change bloc to tile? You forgot to change the other blocs in the description. :wink:

Edit: 4. Perhaps, indicate the type of interpolation happening where the tiles are overlapping. (I am also curious about that. :stuck_out_tongue:)

(G'MIC staff) #26
  • Replaced all uses of indice to index.
  • Make the code font in “example of use” sections bold.
  • Changed uses of bloc to tile in description of apply_tiles.


Black bolded links are distracting, esp. when there is also thin non-black monospace in this section.

Same here: bolded inline text generally diminishes readability.


Can we have more differences in colors. From my end, these are shades of dark blue/violet with some red in there. That would make it a bit easier to read.


Definitions have always been hard to find since the doc is a single web page and parameters are repeated many times (some more than 100 times!) throughout the page and / or are normal words to begin with. In fact, it is harder to search now: at least, before, code used to have single quotes (') and commands used to have colons (:), which reduced the amount of text search hits.

I don’t have a good solution but this should be addressed eventually. Maybe include a long table of contents / terms; e.g., Imagemagick’s command page: However, it only contains a list of links to commands; a list of commands and definitions of G’MIC would be what I would be looking for.

(G'MIC staff) #30

Maybe one page for each command would be good ?


That might be too excessive. Let’s try 1 page per section. How does that sound?

If we could have more pages, perhaps we could expose the visual examples. That would make the docs more colourful.

Also, I forgot to mention that image.jpg isn’t very helpful when one copy-pastes the code. Better have something like sample instead (though sometimes we need a RGB and other times a G).