some more docs and polish

2 files changed, 71 insertions, 52 deletions

diff --git a/README.imagemagick b/README.imagemagick
index d297c76675a..600fb393632 100644
--- a/README.imagemagick
+++ b/README.imagemagick
@@ -1,3 +1,5 @@
+* README for the ImageMagick Emacs branch
+
 This is the imagemagick branch of Emacs. Imagemagick can now be used
 to load many new image formats, and also do useful transforms like
 scaling and rotation.
@@ -13,14 +15,15 @@ autoconf
 ./configure --with-imagemagick
 
 
-* TODO
-
-- image-type-header-regexps priorities the jpeg loader over the
+* TODO  image-type-header-regexps priorities the jpeg loader over the
 imagemagick one. This is not wrong, but how should a user go about
 prefering the imagemagick loader? The user might like zooming etc in
-jpegs.
+jpegs. 
+
+try (setq image-type-header-regexps nil) for a quick hack to prefer
+imagemagick over the jpg loader.
 
-#B _  For some reason its unbearably slow to look at a page in a large
+* TODO  For some reason its unbearably slow to look at a page in a large
   image bundle using the :index feature. The imagemagick "display"
   command is also a bit slow, but nowhere near as slow as the emacs
   code. It seems imagemagick tries to unpack every page when loading
@@ -31,60 +34,72 @@ jpegs.
   It is now way faster to use the :index feature, but its still not
   very fast.
 
-#B X optimize number of pages calculation for bundles as suggested by
+** DONE optimize number of pages calculation for bundles as suggested by
   imagemagick forum: "set the density to something low like 2 and use
   MagickPingImage()"
   
-  
-#B _ zooming the image like what is done for fonts in face-remap.el would
-  be a useful and demo friendly addition. Some work has been done on
-  image-mode.el to acihieve this.
+** TODO try to cache the num pages calculation. it can take a while to
+  calculate the number of pages, and if you need to do it for each
+  page view, page-flipping becomes uselessly slow.
 
-#B _ look for optimizations for handling images with low depth
-  
+* TODO integrate with image-dired
+
+* TODO integrate with docview. 
   
-* TODO
+* TODO integrate with image-mode
+Some work has been done, M-x image-transform-fit-to-height will fit
+the image to the height of the Emacs window for instance.
 
-#B _ complete documentation drafts below
+* TODO look for optimizations for handling images with low depth
+Currently the code seems to default to 24 bit RGB which is costly for
+images with lower bit depth.
 
-#B X fix inconsistencys with spelling of imagemagick in the src
-#B X report number of images in image bundle types somehow
+* TODO complete documentation drafts below
+
+* DONE fix inconsistencys with spelling of imagemagick in the src
+* DONE report number of images in image bundle types somehow
 Works like for "gif" support. Thanks to Juri Linkov.
-#B X probably add pdf to inhibited types
-#B X inhibit types is defconst should probably be defcustom
-#B _ decide what to do with some uncommitted imagemagick support
+* DONE probably add pdf to inhibited types
+* DONE inhibit types is defconst should probably be defcustom
+* TODO decide what to do with some uncommitted imagemagick support
   functions for image size etc.
-#B _ Test with more systems
+* TODO Test with more systems
 Tested on Fedora 12 so far, and the libmagick that ships with it.
-Ubuntu 8.04 was also tested, but it seems it ships a broken ImageMagick.
-#B X Also need some way to handle render methods that only work on newer ImageMagicks
+Ubuntu 8.04 was also tested, but it seems it ships a broken
+ImageMagick.
+
+I also tried using an imagemagick compiled from their SVN, in
+parallell with the one packaged by Fedora, it worked well.
+
+* DONE Also need some way to handle render methods that only work on newer ImageMagicks
 Is handled by configure now
 
 * Some nits from Stefan Monnier
 I just took a quick look at the code and I see the following nits to fix:
-#B _ obviously a merge will have to come with a good ChangeLog.
-#B X also the merge will need to come with documentation.  Maybe not in the
+
+** TODO obviously a merge will have to come with a good ChangeLog.
+** DONE also the merge will need to come with documentation.  Maybe not in the
    Texinfo form yet, but at least in the etc/NEWS with enough info that
    describes the `scale' and other such arguments that someone can start
    using them.
-#B X the README talks about naming inconsistencies, I think these should be
+** DONE the README talks about naming inconsistencies, I think these should be
   fixed before a first commit (should be straightforward).
 
-#B X the "let" in image.el should not be followed by a line break and the while
+** DONE the "let" in image.el should not be followed by a line break and the while
    should be replaced by a dolist.
 
-#B X the prototype of imagemagick_load_image has some odd indentation in ([[2010.06.14]])
+** DONE the prototype of imagemagick_load_image has some odd indentation in ([[2010.06.14]])
    its args, not sure what happened.
-#B X a few lines in the C code break the 80columns limit.
-#B X please use ANSI style function declarations rather than K&R for new code. ([[2010.06.14]])
-#B X you can get rid of the prototypes by reordering the code. ([[2010.06.14]])
-#B X the docstrings in DEFUN should not be indented (they'll display ([[2010.06.14]])
+** DONE a few lines in the C code break the 80columns limit.
+** DONE please use ANSI style function declarations rather than K&R for new code. ([[2010.06.14]])
+** DONE you can get rid of the prototypes by reordering the code. ([[2010.06.14]])
+** DONE the docstrings in DEFUN should not be indented (they'll display ([[2010.06.14]])
    weirdly otherwise in C-h f).
-#B X Some "{" are at the end of a for/if rather than on their own line. ([[2010.06.14]])
-#B X why use "*( imtypes + i)" rather than "imtypes[i]"? ([[2010.06.14]])
-#B X some "," lack a space after them. ([[2010.06.14]])
-#B X several "=" and "==" lack spaces around them. ([[2010.06.14]])
-
+** DONE Some "{" are at the end of a for/if rather than on their own line. ([[2010.06.14]])
+** DONE why use "*( imtypes + i)" rather than "imtypes[i]"? ([[2010.06.14]])
+** DONE some "," lack a space after them. ([[2010.06.14]])
+** DONE several "=" and "==" lack spaces around them. ([[2010.06.14]])
+  
 
 * NEWS entry
 ** ImageMagick support
@@ -147,4 +162,4 @@ of images in an image bundle. This is simmilar to how GIF files work.
            * config.in, Makefile.in, configure.in
 
 * Manual entry
-nothing yet, but the NEWS entry could be adapted.
\ No newline at end of file
+nothing yet, but the NEWS entry could be adapted.
diff --git a/lisp/image-mode.el b/lisp/image-mode.el
index 78ec4772d16..9bd5a76d5da 100644
--- a/lisp/image-mode.el
+++ b/lisp/image-mode.el
@@ -543,8 +543,8 @@ the image file and `image-mode' showing the image as an image."
 ;    (define-key map  [(control ?+)] 'image-scale-in)
 ;    (define-key map  [(control ?-)] 'image-scale-out)
 ;    (define-key map  [(control ?=)] 'image-scale-none)
-;;    (define-key map "c f h" 'image-scale-fit-height)    
-;;    (define-key map "c ]" 'image-rotate-right)            
+;;    (define-key map "c f h" 'image-scale-fit-height)
+;;    (define-key map "c ]" 'image-rotate-right)
     map)
   "Minor mode keymap for transforming the view of images Image mode.")
 
@@ -553,23 +553,16 @@ the image file and `image-mode' showing the image as an image."
   nil "image-transform"
   image-transform-minor-mode-map)
 
-;;these are supposed to be buffer local
-;(defvar image-transform-height 100);;nil should mean 100%
-;;the interface could rather be:
-(defvar image-transform-resize
-  nil
-  "values: fit-height  number=scale nil=scale100% TODO fit-width fit-page"
-  )
+(defvar image-transform-resize   nil
+  "The image resize operation. See the command
+  `image-transform-set-scale' for more information." )
 
-;;TODO 0 90 180 270 degrees are the only reasonable angles here
-;;otherwise combining with rescaling will get very awkward
 (defvar image-transform-rotation 0.0)
 
-;;then it would be nice with a bunch of globals like:
-;; image-transform-always-resize values: 'fit-height nil=100% number=scale TODO  'fit-width 'fit-page
-;; image-transform-always-rotate value: angle
 
 (defun image-transform-properties (display)
+  "Calculate the display properties for transformations; scaling
+and rotation. "
   (let*
       ((size (image-size display t))
        (height
@@ -588,28 +581,39 @@ the image file and `image-mode' showing the image as an image."
       ,@(if width (list :width width))
       ,@(if (not (equal 0.0 image-transform-rotation))
             (list :rotation image-transform-rotation))
+      ;;TODO fit-to-* should consider the rotation angle
       )))
 
 (defun image-transform-set-scale (scale)
+  "SCALE sets the scaling for images. "
   (interactive "nscale:")
   (image-transform-set-resize (float scale)))
 
 (defun image-transform-fit-to-height ()
+  "Fit image height to window height. "
   (interactive)
   (image-transform-set-resize 'fit-height))
 
 (defun image-transform-fit-to-width ()
+  "Fit image width to window width. "
   (interactive)
   (image-transform-set-resize 'fit-width))
 
 (defun image-transform-set-resize (resize)
+  "Set the resize mode for images. The RESIZE value can be the
+symbol fit-height which fits the image to the window height. The
+symbol fit-width fits the image to the window width.  A number
+indicates a scaling factor. nil indicates scale to 100%. "
   (setq image-transform-resize resize)
   (if (eq 'image-mode major-mode) (image-toggle-display-image)))
 
 (defun image-transform-set-rotation (rotation)
+  "Set the image ROTATION angle. "
   (interactive "nrotation:")
+  ;;TODO 0 90 180 270 degrees are the only reasonable angles here
+  ;;otherwise combining with rescaling will get very awkward
   (setq image-transform-rotation (float rotation))
-  (image-toggle-display-image))
+  (if (eq major-mode 'image-mode) (image-toggle-display-image)))
 
 (provide 'image-mode)