ImageMagick is very powerful, but the lack of documentation makes its usage very complicated. (For example, for me it is much easier to write a shell script to drive PBM utilities than to try to decipher what is written in the current scheleton of documentation. Keep in mind that it is not a question of me being more familiar with PBMutils: I'm not a frequent user of PBMutils, so I need to read its manpages anyway.)
Are there any plans on documenting ImageMagick? If I knew which files to edit, I might be able to contribute a little bit (I spent several hours reading the sources - just to understand things which should have been mentioned in the docs...). The most salvageable piece of the current scheleton looks the processing part: http://www.imagemagick.com/www/command-line-processing.html The density of misinformation looks quite low, so maybe it is a good place to start with. Unfortunately, I did not read the source of the command-line parser, so I cannot help here. Can somebody look at: a) "Input filename" section does not mention special pseudo-images, such as xc: etc. IIRC, there is a special docpage for them, and it should better be linked in. The current link to "builtin images and patterns" does not help much; 25% of the "Built-in Images" (the Netscape: part) section is uncomprehensible: is it an image, a flag, an operator, or what? b) Style: "persists" in "persists as it appears on the command line" --> I do not know...; something like "does not affect what appears before it on the command line". It is a very important distinction that some options "act to the left" on the command line (operators), and some "act to the right". I do not think that the word "persist" reflect well the "right" side of this dichotomy. It would make things clearer if one could mention something like this too: Each setting in this list affects some specific input/transformation operations only. If the corresponding operation does not appear c) "Image settings" is very misleading. Maybe it makes sense to break it into "image settings", and "operator settings"? Or maybe 3 parts: "input/output/operator settings"? And maybe explicitly call them somewhat like "*future* image/operator settings"? d) "An image operator differs from a setting in that it affects the image immediately as it appears on the command line." Is not it very misleading? *Which* image? I suspect that "it affects all the images in the `current' image sequence in the same way", or some such... e) "An image sequence operator differs from a setting in that it affects an image sequence immediately as it appears on the command line." It looks identical to the description in the section "image operator". Should not it be better to break it into several paragraphs: These operators replace the `current' image sequence by one compound image: ... These operators modify what is the `current' image sequence without editing individual images: ... Any other type? f) "Notice the parenthesis are escaped." In addition to the grammar: whoever knows their shell, does not need it; the rest would not understand... Maybe something like: The example above assumes Unixish shell, which wants to process unescaped parentheses itself. So the parentheses in this example are escaped. With DOSish shells, they should be not escaped. g) "are most useful when processing images in an image stack": *what else* may be processed? Maybe the splitting in "e" makes this paragraph redundant? Or move it to the second part of "e"? h) Some of those in (g) are listed in the previous section, some not. Why? i) "Output Filename" does not mention pseudo-names, such as "info:" "null:". Mention "Pseudo-images with mode containing `W'"? Thanks, Ilya _______________________________________________ Magick-bugs mailing list [email protected] http://studio.imagemagick.org/mailman/listinfo/magick-bugs
