From 82c79220f58caa8ee6b78c8704aa97191c2352c7 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sun, 29 Sep 2019 10:09:56 +0300 Subject: [PATCH] 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. --- doc/lispref/display.texi | 3 ++- etc/NEWS | 10 +++++----- lisp/image.el | 10 +++++----- lisp/image/image-converter.el | 13 ++++++++----- 4 files changed, 20 insertions(+), 16 deletions(-) diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index ec288b1c47d..a661eca13f0 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -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. diff --git a/etc/NEWS b/etc/NEWS index 677b710e223..3d8480cb461 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -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. diff --git a/lisp/image.el b/lisp/image.el index 3f953e65ae8..07ffefcbc5b 100644 --- a/lisp/image.el +++ b/lisp/image.el @@ -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") diff --git a/lisp/image/image-converter.el b/lisp/image/image-converter.el index f485c348426..25b49ff103b 100644 --- a/lisp/image/image-converter.el +++ b/lisp/image/image-converter.el @@ -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")) -- 2.39.2