Commit 7b997b14 authored by Glenn Morris's avatar Glenn Morris

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.
parent 44e76f9d
2014-01-22 Glenn Morris <>
* display.texi (ImageMagick Images): Expand on image-format-suffixes.
2014-01-20 Glenn Morris <>
* hash.texi (Other Hash): Do not mention subr-x.el functions;
......@@ -4690,6 +4690,16 @@ should never be rendered using ImageMagick, regardless of the value of
ImageMagick entirely.
@end defopt
@defvar 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}
@var{extension})}, where @var{type} is a symbol specifying an image
content-type, and @var{extension} is a string that specifies the
associated file name extension.
@end defvar
Images loaded with ImageMagick support the following additional
image descriptor properties:
......@@ -4700,13 +4710,13 @@ color, which is used as the image's background color if the image
supports transparency. If the value is @code{nil}, it defaults to the
frame's background color.
@item :width, :height
@item :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.
@item :max-width, :max-height
@item :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 @@ and if @code{:height} is set it will have precedence over
wish. @code{:max-width} and @code{:max-height} will always preserve
the aspect ratio.
@c FIXME: ':format-type' or ':format'? --xfq
@item :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
@code{image-format-suffixes} variable, which provides a mapping from
content types to file name suffixes. This is then given to
ImageMagick as a file name hint.
@item :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.
@item :rotation
@item :rotation @var{angle}
Specifies a rotation angle in degrees.
@item :index
@item :index @var{frame}
@c Doesn't work:
@xref{Multi-Frame Images}.
@end table
......@@ -175,9 +175,11 @@ Use `C-h C-\' (`describe-input-method') instead.
*** 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
2014-01-22 Glenn Morris <>
* image.el (image-format-suffixes): Doc fix.
* international/quail.el (quail-define-package): Doc fix.
* emacs-lisp/authors.el (authors-valid-file-names):
......@@ -104,11 +104,13 @@ AUTODETECT can be
(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))
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment