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.

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"))