References to other web pages aren’t hotlinks, eg “pixelsort” references " Pixel Sorting - satyarth.me" but it’s not a hotlink so I have to copy-paste the address.
There is generally no description of what parameters do, or what values are permitted. For example, in “pixelsort”, what values are permitted for “sorting criterion”? Some kind of text, or does it have to be an image? What does “mask” do?
Sort_list also has a criterion, with default “i”, but what does “i” mean? What alternatives might I use?
I would prefer keywords instead of numbers for parameters. Eg “linear” or “lanczos” instead of “3” or “6”. This would help me to understand commands like “+resize[-1] 120%,120%,1,3,0,1,0.5,0.5”, which I find cryptic.
Indeed, the docs can be daunting. Case in point: the number of questions I asked when getting into G’MIC, so many that there are still questions left unanswered or unread.
Hi,
documentation is a costly thing. Still trials to get an overview are sometimes helpful!
What about some sort of matrix similar to the beginning of http://www.aljacom.com/~gmic/commandes_gmic.pdf ?
An index is quite long …
That is also missing yes. Here I was speaking about the Technical reference documentation, which is for me the base documentation we should at least have
Personally, I’m not using the plug-in very often, and I’m not sure I’d be the best person to write a doc about it. If people are interested to do so, then I guess the wiki pages of the gmic-community repo (Home · GreycLab/gmic-community Wiki · GitHub) could be the best location fot that kind of documentation.
That is fixed, I’ve replaced all url by HTML links.
Just here to let the OP know that I actually prefer highlighting. For me, it’s a quick and easy way to see information I need if I’m looking to make a new filter. I know others might hate it because that it looks distracting, and I completely get that as the style isn’t consistent in a way. Can there be at least a option to enable highlighting?
Currently, as things are formatted, I agree that no highlighting is actually worse. I don’t have the old version but I think it has to do with the fact that the font is thinner and lighter. As said,
Try using http://wave.webaim.org/ to evaluate your web page. I haven’t tried it before and when I have just now it stalls my browser. Maybe I have a plugin that is blocking it…
About highlighting, the way I have just back ticked the web address, http://wave.webaim.org/, looks good to me. Perhaps, you could use a similar style.
I’ve make the code highlighting a bit more contrasted.
On the github issue (Bad English in the docs · Issue #107 · dtschump/gmic · GitHub), the OP suggests to replace the term list used everywhere in the doc by stack. It’s not really clear to me if that is a good idea or not. in algorithmics, a stack is a particular data structure which does not correspond to the G’MIC list of image (see Stack (abstract data type) - Wikipedia), because in G’MIC you can access to each elements individually, change their position and so on…
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.
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. 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.
Edit: 4. Perhaps, indicate the type of interpolation happening where the tiles are overlapping. (I am also curious about that. )
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: https://www.imagemagick.org/www/script/command-line-options.php. 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.
Secondly, for consistency, keep both 
)
