Image transformations

[Eli Zaretskii]

Recent addition of native image transformations is a very welcome feature, but 
it's lacking some documentation and has a couple of other problems:

  . The :crop parameter of image specs doesn't seem to be documented anywhere.  
We previously supported it without documenting only for ImageMagick, which was 
already a problem; now it's a much bigger problem.
  . The ELisp manual doesn't mention that :rotation is generally supported only 
for multiples of 90 deg, except if ImageMagick is available.
  . The transformation matrix used by the implementation is not described; one 
needs to guess what its components mean, or search the Internet for docs of 
XRender and/or Cairo, which are generally not helpful enough, especially the 
XRender one.
  . There are no tests, AFAICT.  We should have a simple manual test which 
could be used to exercise all of the transformations, separately and in 
combinations.  I wonder how did the people who worked on the implementations 
for different platforns verify that the results are consistent, especially 
given the lack of documentation (e.g., is rotation of 90 deg clockwise or 
counter-clockwise?).
 . I question the wisdom of the current definition of image-transforms-p.  
First, it returns a simple yes/no value, under the assumption that either all 
of the transformations are supported or none of them; IMO, it is better to 
return a list of supported capabilities instead.  Second, it doesn't 
distinguish between capability to rotate by arbitrary angles and by 90 deg 
multiples only, which will require Lisp programs to test for ImageMagick, 
something that undermines the very raison d'etre of this function

Could someone please address these deficiencies ASAP?  Without that, the 
feature seems incomplete and frankly not very clean.

TIA