[Magick-bugs] On quality of options starting with -a...

[Ilya Zakharevich]

I wrote in article <gpi657$gpr$1 at ger.gmane.org>:

> Many many thanks.  Having a "correct" and understandable
> categorization of commands should be very useful.

To substantiate my claim:

 I scanned through the options startings with -A on
   http://www.imagemagick.com/www/command-line-options.html

 The result: Currently only 1 of 13 descriptions makes sense (-alpha).
 With a correct categorization of commands, 2.5 more (-antialias,
 -authenticate, and maybe -auto-orient) have a reasonable chance to
 become less ambiguous.

So just doing correct categorization in "Processing" page, and
(automatically) adding the category "icons" to the "Options" page
would improve this part of documentation by about 250%!

So: can the categorization of "Processing" page be done?

Thanks,
Ilya

P.S.  Here is my log when scanning (I also added the entry for -tint...).

=======================================================
-adaptive-blur radius[xsigma]
 "Adaptively blur" is "not documentation"; so: what does it do.
 "near edges": what does it mean (probably not edges of the image rectangle?),
 how exactly it is influenced and by what?

 Having the useless RADIUS mandatory and the crucial SIGMA optional shakes
 my feelings...

-adaptive-resize:
 the docs are so unclear that I do not even have particular questions.
 What they were trying to convey?  Some pieces are resized, some not, or
 what?

-adaptive-sharpen
 Same as for -adaptive-blur, but also no information on percentage...

-adjoin
 Is it an operation, or a setting for output operations?  E.g., what does it
 do if not a last one?   Are these equivalent:
   convert logo: rose: -morph 15 my%02dmorph.jpg
   convert logo: rose: -morph 15 +adjoin my%02dmorph.jpg

-affine: this contradicts the description of rotation by using c,s,-s,c:

 The size of the resulting image is that of the smallest rectangle that
 contains the transformed source image. The parameters tx and ty
 subsequently shift the image pixels so that those that are moved out of
 the image area are cut off.

	Or maybe the given formula is wrong, and there is an additional
        translation to move UL corner of bounding rectangle to 0,0?

-annotate:
 -gravity influences the choice of the corner of the text, or of the picture?
 If second, one should mention `-gravity sw', not just `-gravity'...

-antialias:
 Probably does nothing with pictures, just changes some setting?

-append
 "stacked top-to-bottom" is very ambiguous (y-direction, or z-direction?)
 (Can be clarified by "so appending three 200x100 images creates a 200x300
  image")

 "The  set  of  images  is  terminated  by the appearance of any option"
 - fine, but what is it started with?  Are the images to append given AFTER
 the -append?  What if it happens in the middle of the image sequence?

-attenuate value
   Lessen (or intensify) when adding noise to an image.

 I have no clue what they wanted to say...  Lessen WHAT?  And what this
 "when" means?

-authenticate password
 Is it a setting, or an operator?

-auto-orient
 No clue again...  E.g.: Is it a setting, or an operator?
 If an operator, then does it "rotates and flips image as
 needed" to match orientation info in EXIF header.  Does it
 update EXIF to reflect the new orientation?

-average
 Same as the second remark about -append...

==================================================================
-tint: 

 value: interpolates between results for value=0 and value=100%?
 if value=100%: midgray ==> ??? The rest modulated by 1 - S, S = saturation?
 Interpolated w.r.t. saturation?  What happens with intensity?