* doc/lispref/display.texi (ImageMagick Images): General update.

2 files changed, 39 insertions, 14 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 163ab80e8b8..1a7c71232c6 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,6 +1,6 @@
 2012-02-07  Glenn Morris  <rgm@gnu.org>
 
-        * display.texi (ImageMagick Images):
+        * display.texi (ImageMagick Images): General update.
         Move most details of imagemagick-render-type to the variable's doc.
 
 2012-02-06  Glenn Morris  <rgm@gnu.org>
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index e1b2f57e507..99eb996a773 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -4527,21 +4527,45 @@ specifying the bounding box of the PostScript image, analogous to the
 support, you can use the ImageMagick library to load many image formats.
 
 @findex imagemagick-types
+@findex imagemagick-register-types
 The function @code{imagemagick-types} returns a list of image file
 extensions that your installation of ImageMagick supports.  To enable
 support, you must call the function @code{imagemagick-register-types}.
+This enables Emacs to visit these file types in @code{image-mode}
+(@pxref{File Conveniences,,, emacs, The GNU Emacs Manual}).
+If your Emacs was not compiled with ImageMagick support, then
+@code{imagemagick-types} will be undefined and
+@code{imagemagick-register-types} will do nothing.
 
 @vindex imagemagick-types-inhibit
 The variable @code{imagemagick-types-inhibit} specifies a list of
-image types that you do @emph{not} want ImageMagick to handle.  There
-may be overlap between image loaders in your Emacs installation, and
-you may prefer to use a different one for a given image type (which
-@c FIXME how is this priority determined?
-loader will be used in practice depends on the priority of the loaders).
-@c FIXME why are these uppercase when image-types is lower-case?
-@c FIXME what are the possible options?  Are these actually file extensions?
-For example, if you never want to use the ImageMagick loader to use
-JPEG files, add @code{JPG} to this list.
+image types that you do @emph{not} want ImageMagick to handle.  It is
+a list of symbols, each of which has the same name as one of the
+format tags used internally by ImageMagick (i.e., as
+@code{imagemagick-types} returns).  ImageMagick has a very broad
+definition of what an image is, for example it includes such file
+types as C files and HTML files.  It is not appropriate to treat these
+as images in Emacs.  You can add any other ImageMagick type that you
+wish to this list.
+@ignore
+@c I don't know what this means.  I suspect it means eg loading jpg
+@c images via libjpeg or ImageMagick.  But it doesn't work.
+@c If you don't have libjpeg support compiled in, you cannot
+@c view jpeg images, even if you have imagemagick support:
+@c http://debbugs.gnu.org/9045
+@c And if you have both compiled in, then you always get
+@c the libjpeg version:
+@c http://debbugs.gnu.org/10746
+There may be overlap between image loaders in your Emacs installation,
+and you may prefer to use a different one for a given image type
+(which loader will be used in practice depends on the priority of the
+loaders).  
+@end ignore
+For example, if you never want to use the ImageMagick loader to view
+JPEG files, add @code{JPG} to this list.  Note that ImageMagick often
+distinguishes between several different types of a particular format
+(e.g., @code{JPG}, @code{JPEG}, @code{PJPEG}, etc.), and you may need
+to add all versions to this list.
 
 @c Not sure this should even be in the manual at all.
 @vindex imagemagick-render-type
@@ -4561,10 +4585,11 @@ aspect ratio may not be preserved.
 Specifies a rotation angle in degrees.
 
 @item :index
-Specifies which image to view inside an image bundle file format, such
-as TIFF or DJVM.  You can use the @code{image-metadata} function to
-retrieve the total number of images in an image bundle (this is
-similar to how GIF files work).
+@c Doesn't work: http://debbugs.gnu.org/7978
+This has the same meaning as it does for GIF images (@pxref{GIF Images}),
+i.e. it specifies which image to view inside an image bundle file format
+such as DJVM.  You can use the @code{image-metadata} function to
+retrieve the total number of images in an image bundle.
 @end table