[Emacs-diffs] trunk r116107: Some doc for image-format-suffixes

[Glenn Morris]

------------------------------------------------------------
revno: 116107
revision-id: address@hidden
parent: address@hidden
committer: Glenn Morris <address@hidden>
branch nick: trunk
timestamp: Wed 2014-01-22 00:30:00 -0800
message:
  Some doc for image-format-suffixes
  
  * doc/lispref/display.texi (ImageMagick Images):
  Expand on image-format-suffixes.
  
  * lisp/image.el (image-format-suffixes): Doc fix.
  
  * etc/NEWS: Related markup.
modified:
  doc/lispref/ChangeLog          changelog-20091113204419-o5vbwnq5f7feedwu-6155
  doc/lispref/display.texi       
display.texi-20091113204419-o5vbwnq5f7feedwu-6172
  etc/NEWS                       news-20100311060928-aoit31wvzf25yr1z-1
  lisp/ChangeLog                 changelog-20091113204419-o5vbwnq5f7feedwu-1432
  lisp/image.el                  image.el-20091113204419-o5vbwnq5f7feedwu-1320

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2014-01-20 20:05:04 +0000
+++ b/doc/lispref/ChangeLog     2014-01-22 08:30:00 +0000
@@ -1,3 +1,7 @@
+2014-01-22  Glenn Morris  <address@hidden>
+
+       * display.texi (ImageMagick Images): Expand on image-format-suffixes.
+
 2014-01-20  Glenn Morris  <address@hidden>
 
        * hash.texi (Other Hash): Do not mention subr-x.el functions;

=== modified file 'doc/lispref/display.texi'
--- a/doc/lispref/display.texi  2014-01-07 07:51:20 +0000
+++ b/doc/lispref/display.texi  2014-01-22 08:30:00 +0000
@@ -4690,6 +4690,16 @@
 ImageMagick entirely.
 @end defopt
 
address@hidden image-format-suffixes
+This variable is an alist mapping image types to file name extensions.
+Emacs uses this in conjunction with the @code{:format} image property
+(see below) to give a hint to the ImageMagick library as to the type
+of an image.  Each element has the form @code{(@var{type}
address@hidden)}, where @var{type} is a symbol specifying an image
+content-type, and @var{extension} is a string that specifies the
+associated file name extension.
address@hidden defvar
+
   Images loaded with ImageMagick support the following additional
 image descriptor properties:
 
@@ -4700,13 +4710,13 @@
 supports transparency.  If the value is @code{nil}, it defaults to the
 frame's background color.
 
address@hidden :width, :height
address@hidden :width @var{width}, :height @var{height}
 The @code{:width} and @code{:height} keywords are used for scaling the
 image.  If only one of them is specified, the other one will be
 calculated so as to preserve the aspect ratio.  If both are specified,
 aspect ratio may not be preserved.
 
address@hidden :max-width, :max-height
address@hidden :max-width @var{max-width}, :max-height @var{max-height}
 The @code{:max-width} and @code{:max-height} keywords are used for
 scaling if the size of the image of the image exceeds these values.
 If @code{:width} is set it will have precedence over @code{max-width},
@@ -4715,19 +4725,16 @@
 wish.  @code{:max-width} and @code{:max-height} will always preserve
 the aspect ratio.
 
address@hidden FIXME: ':format-type' or ':format'?  --xfq
address@hidden :format
-ImageMagick tries to auto-detect the image type, but it isn't always
-able to.  By using @code{:format-type}, we can give ImageMagick a hint
-to try to help it.  It's used in conjunction with the
address@hidden variable, which provides a mapping from
-content types to file name suffixes.  This is then given to
-ImageMagick as a file name hint.
address@hidden :format @var{type}
+The value, @var{type}, should be a symbol specifying the type of the
+image data, as found in @code{image-format-suffixes}.  This is used
+when the image does not have an associated file name, to provide a
+hint to ImageMagick to help it detect the image type.
 
address@hidden :rotation
address@hidden :rotation @var{angle}
 Specifies a rotation angle in degrees.
 
address@hidden :index
address@hidden :index @var{frame}
 @c Doesn't work: http://debbugs.gnu.org/7978
 @xref{Multi-Frame Images}.
 @end table

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2014-01-22 07:55:53 +0000
+++ b/etc/NEWS  2014-01-22 08:30:00 +0000
@@ -175,9 +175,11 @@
 +++
 *** ImageMagick images now support the :max-width and :max-height keywords.
 
-*** Some data types aren't auto-detected by ImageMagick.
-Adding :format to `create-image' may help if the content type is in
-the new variable `image-format-suffixes'.
++++
+*** When using `create-image' with image data, you can pass a :format
+attribute (via the property-list argument) in order to help
+ImageMagick detect the image type.  The value should be a MIME
+content-type that is found in the new variable `image-format-suffixes'.
 
 ** Frame and window changes
 

=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog    2014-01-22 07:55:53 +0000
+++ b/lisp/ChangeLog    2014-01-22 08:30:00 +0000
@@ -1,5 +1,7 @@
 2014-01-22  Glenn Morris  <address@hidden>
 
+       * image.el (image-format-suffixes): Doc fix.
+
        * international/quail.el (quail-define-package): Doc fix.
 
        * emacs-lisp/authors.el (authors-valid-file-names):

=== modified file 'lisp/image.el'
--- a/lisp/image.el     2014-01-01 07:43:34 +0000
+++ b/lisp/image.el     2014-01-22 08:30:00 +0000
@@ -104,11 +104,13 @@
 
 (defvar image-format-suffixes
   '((image/x-icon "ico"))
-  "Alist of MIME Content-Type headers to file name suffixes.
+  "An alist associating image types with file name suffixes.
 This is used as a hint by the ImageMagick library when detecting
-image types.  If `create-image' is called with a :format
-matching found in this alist, the ImageMagick library will be
-told that the data would have this suffix if saved to a file.")
+the type of image data (that does not have an associated file name).
+Each element has the form (MIME-CONTENT-TYPE EXTENSION).
+If `create-image' is called with a :format attribute whose value
+equals a content-type found in this list, the ImageMagick library is
+told that the data would have the associated suffix if saved to a file.")
 
 (defcustom image-load-path
   (list (file-name-as-directory (expand-file-name "images" data-directory))