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.

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.

1 Like

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.

1 Like

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:)

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

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

The clut list under clut is getting unwieldy and hard to read and find the clut that I want.

It doesn’t even fit on my laptop or mobile screens!

I suggest you have a link to a separate page for clut and map_clut that has an interactive preview where the cluts are a) organized by category, b) selectable for preview and c) the user gets to choose a list of sample images or a crop from an upload.

I really appreciate the demos that provides. That is the sort of thing I would like it to be like. I know you have G’MIC Online as well. Maybe a way to integrate a simpler version of that into the examples and long lists would make things much more accessible. Of course, this would take more effort than you (@David_Tschumperle) might have time for. :timer_clock:

That’s right, I’m currently working hard on adding new CLUTs to G’MIC (amost 500 now!).
Most of them are illustrated on the ‘Color Grading’ page :

I’ll probably tell more in a few weeks/months about the way CLUTs are managed in G’MIC.

Yes, it has been around for some time but I still find it hard to search what I would be interested in. There has to be a better and faster way. :wink::thinking:

PS From the top of my mind, select a sample image, or a small crop of a large input image, and then have it displayed 500+ ways, with pagination of course. :stuck_out_tongue: It is simple but it would be good to select by seeing and comparing[1] the visual outcome. Then click on the preview to get more info about that particular clut.

[1] Speaking of comparison, perhaps have the ability to choose 5 to compare side to side, like buying a car, app or finding a date (the last one is a joke, obviously).

The tutorial link is giving me a 404.

There are other typos but I forget where they are.

There is an error with your doc page. See bottom.

1 Like

Thanks for showing me. I’ve fixed the bug and I’ll update the doc in a few minutes.

1 Like