Commit 82c79220 authored by Eli Zaretskii's avatar Eli Zaretskii

Improve documentation of image conversion feature

* lisp/image/image-converter.el (image-converter)
(image-convert-p, image-convert):
* lisp/image.el (convert-images-externally):
* etc/NEWS:
* doc/lispref/display.texi (Defining Images): Fix recently
added documentation.
parent 8b5e9292
Pipeline #3363 passed with stage
in 55 minutes and 39 seconds
......@@ -6049,7 +6049,8 @@ If Emacs doesn't have native support for the image format in question,
and @code{convert-images-externally} is non-@code{nil}, Emacs will try
to determine whether there are external utilities that can be used to
transform the image in question to @acronym{PNG} before displaying.
GraphicsMagick, ImageMagick and ffmpeg are currently supported.
GraphicsMagick, ImageMagick and @command{ffmpeg} are currently
supported for image conversions.
The function returns @code{nil} if images of this type are not
supported. Otherwise it returns an image descriptor.
......
......@@ -2657,11 +2657,11 @@ data about creation times and orientation and the like.
functions.
*** New library image-converter.
To view exotic image formats that Emacs doesn't have native support
for, the new 'convert-images-externally' variable can be set to t. If
the system has GraphicsMagick, ImageMagick or ffmpeg installed, it
will be used to convert images automatically before displaying with
'create-image'.
If you need to view exotic image formats for which Emacs doesn't have
native support, customize the new variable 'convert-images-externally'
to t. If your system has GraphicsMagick, ImageMagick or 'ffmpeg'
installed, they will then be used to convert images automatically
before displaying them.
*** 'image-mode' now uses this library to automatically rotate images
according to the orientation in the Exif data, if any.
......
......@@ -143,11 +143,11 @@ based on the font pixel size."
(defcustom convert-images-externally nil
"If non-nil, `create-image' will use external converters for exotic formats.
Emacs handles most of the common image formats (JPEG, PNG, GIF
and so on) internally, but images that doesn't have native
support in Emacs can still be displayed by Emacs if external
conversion programs (like ImageMagick \"convert\", GraphicsMagick
\"gm\" or \"ffmpeg\") are installed."
Emacs handles most of the common image formats (SVG, JPEG, PNG, GIF
and some others) internally, but images that don't have native
support in Emacs can still be displayed if an external conversion
program (like ImageMagick \"convert\", GraphicsMagick \"gm\"
or \"ffmpeg\") is installed."
:type 'bool
:version "27.1")
......
......@@ -41,8 +41,11 @@ conversion programs (like ImageMagick \"convert\", GraphicsMagick
:version "27.1")
(defcustom image-converter nil
"What external converter to use.
`imagemagick', `graphicsmagick' and `ffmpeg' are supported."
"Type of the external image converter to use.
The value should a symbol, either `imagemagick', `graphicsmagick',
or `ffmpeg'.
If nil, Emacs will try to find one of the supported converters
installed on the system."
:group 'image
:type 'symbol
:version "27.1")
......@@ -57,7 +60,7 @@ conversion programs (like ImageMagick \"convert\", GraphicsMagick
"List of supported image converters to try.")
(defun image-convert-p (file)
"Return `image-convert' if FILE can be converted."
"Return `image-convert' if FILE is an image file that can be converted."
;; Find an installed image converter.
(unless image-converter
(image-converter--find-converter))
......@@ -66,7 +69,7 @@ conversion programs (like ImageMagick \"convert\", GraphicsMagick
'image-convert))
(defun image-convert (image)
"Convert IMAGE to a format Emacs can display.
"Convert IMAGE file to the PNG format.
IMAGE can either be a file name, which will make the return value
a string with the image data. It can also be an image object as
returned by `create-image'. If so, it has to be an image object
......@@ -75,7 +78,7 @@ where created with DATA-P nil (i.e., it has to refer to a file)."
(unless image-converter
(image-converter--find-converter))
(unless image-converter
(error "No external image converters installed"))
(error "No external image converters available"))
(when (and (listp image)
(not (plist-get (cdr image) :file)))
(error "Only images that refer to files can be converted"))
......
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