emacs-29 96714c106b7: Improve documentation of image-related commands

[Eli Zaretskii]

branch: emacs-29
commit 96714c106b7a3f86ca4c78052178a62d351f1751
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    Improve documentation of image-related commands
    
    * lisp/image.el (image-map): Make it inherit from
    'image-slice-map' instead of repeating the bindings.
    
    * doc/emacs/files.texi (Image Mode): Document the key bindings set
    by 'insert-image'.  Add indexing.
    
    * doc/lispref/display.texi (Showing Images): Make the description
    of user commands more concise.  Add index entries and
    cross-reference to the Emacs manual.
    
    * etc/NEWS: Rearrange entries relevant to image commands.
---
 doc/emacs/files.texi     | 93 ++++++++++++++++++++++++++++++++++++++++++++++++
 doc/lispref/display.texi | 30 +++++++++-------
 etc/NEWS                 | 32 ++++++++---------
 lisp/image.el            | 24 +++++--------
 4 files changed, 135 insertions(+), 44 deletions(-)

diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi
index c0e702da947..29cc22e7557 100644
--- a/doc/emacs/files.texi
+++ b/doc/emacs/files.texi
@@ -2281,10 +2281,15 @@ behavior by using the options @code{image-auto-resize} 
and
 @code{image-auto-resize-on-window-resize}.
 
 @findex image-transform-fit-to-window
+@kindex s w (Image mode)
 @findex image-transform-set-percent
+@kindex s p (Image mode)
 @findex image-transform-set-scale
+@kindex s s (Image mode)
 @findex image-transform-reset-to-initial
+@kindex s 0 (Image mode)
 @findex image-transform-reset-to-original
+@kindex s o (Image mode)
 To resize the image manually you can use the command
 @code{image-transform-fit-to-window} bound to @kbd{s w} that fits the
 image to both the window height and width.  To scale the image to a
@@ -2345,6 +2350,94 @@ frames at once.  You can go to a specific frame with 
@kbd{F}
 (@code{image-reverse-speed}) reverses it.  The command @kbd{a 0}
 (@code{image-reset-speed}) resets the speed to the original value.
 
+In addition to the above key bindings, which are specific to Image
+mode, images shown in any Emacs buffer have special key bindings when
+point is at or inside the image:
+
+@table @kbd
+@cindex resize images
+@cindex image resize
+@findex image-increase-size
+@kindex i + (Image mode)
+@item i +
+Increase the image size (@code{image-increase-size}) by 20%.  Prefix
+numeric argument controls the increment; the value of @var{n} means to
+multiply the size by the factor of @w{@code{1 + @var{n} / 10}}, so
+@w{@kbd{C-u 5 i +}} means to increase the size by 50%.
+
+@findex image-decrease-size
+@kindex i - (Image mode)
+@item i -
+Decrease the image size (@code{image-increase-size}) by 20%.  Prefix
+numeric argument controls the decrement; the value of @var{n} means to
+multiply the size by the factor of @w{@code{1 - @var{n} / 10}}, so
+@w{@kbd{C-u 3 i -}} means to decrease the size by 30%.
+
+@cindex rotating images
+@cindex image rotation
+@findex image-rotate
+@kindex i r (Image mode)
+@item i r
+Rotate the image by 90 degrees clockwise (@code{image-rotate}).
+With the prefix argument, rotate by 90 degrees counter-clockwise instead.
+Note that this command is not available for sliced images.
+
+@findex image-flip-horizontally
+@kindex i h (Image mode)
+@item i h
+Flip the image horizontally (@code{image-flip-horizontally}).  This
+presents the image as if reflected in a vertical mirror.
+Note that this command is not available for sliced images.
+
+@findex image-flip-vertically
+@kindex i v (Image mode)
+@item i v
+Flip the image vertically (@code{image-flip-vertically}).  This
+presents the image as if reflected in a horizontal mirror.
+Note that this command is not available for sliced images.
+
+@findex image-save
+@kindex i o (Image mode)
+@item i o
+Save the image to a file (@code{image-save}).  This command prompts
+you for the name of the file to save the image.
+
+@cindex cropping images
+@vindex image-crop-crop-command
+@findex image-crop
+@kindex i c (Image mode)
+@item i c
+Crop the image (@code{image-crop}).  This command is available only if
+your system has an external program installed that can be used for
+cropping and cutting of images; the user option
+@code{image-crop-crop-command} determines what program to use, and
+defaults to the ImageMagick's @command{convert} program.  The command
+displays the image with a rectangular frame superimposed on it, and
+lets you use the mouse to move and resize the frame.  Type @kbd{m} to
+cause mouse movements to move the frame instead of resizing it; type
+@kbd{s} to move a square frame instead.  When you are satisfied with
+the position and size of the cropping frame, type @kbd{@key{RET}} to
+actually crop the part under the frame; or type @kbd{q} to exit
+without cropping.  You can then save the cropped image using @w{@kbd{i
+o}} or @w{@kbd{M-x image-save}}.
+
+@findex image-cut
+@kindex i x (Image mode)
+@vindex image-cut-color
+@vindex image-crop-cut-command
+@item i x
+Cut a rectangle from the image (@code{image-cut}).  This works the
+same as @code{image-crop} (and also requires an external program,
+defined by the variable @code{image-crop-cut-command}, to perform the
+image cut), but instead of cropping the image, it removes the part
+inside the frame and fills that part with the color specified by
+@code{image-cut-color}.  With prefix argument, the command prompts for
+the color to use.
+@end table
+
+The size and rotation commands are ``repeating'', which means that you
+can continue adjusting the image without using the @kbd{i} prefix.
+
 @cindex ImageMagick support
 @vindex imagemagick-enabled-types
 @vindex imagemagick-types-inhibit
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 85fac4b30a6..8184021d998 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -6876,7 +6876,7 @@ This function puts image @var{image} in front of 
@var{pos} in the
 current buffer.  The argument @var{pos} should be an integer or a
 marker.  It specifies the buffer position where the image should appear.
 The argument @var{string} specifies the text that should hold the image
-as an alternative to the default.
+as an alternative to the default @samp{x}.
 
 The argument @var{image} must be an image descriptor, perhaps returned
 by @code{create-image} or stored by @code{defimage}.
@@ -6889,7 +6889,7 @@ buffer's text.
 
 Internally, this function creates an overlay, and gives it a
 @code{before-string} property containing text that has a @code{display}
-property whose value is the image.  (Whew!)
+property whose value is the image.  (Whew! that was a mouthful@dots{})
 @end defun
 
 @defun remove-images start end &optional buffer
@@ -6936,41 +6936,47 @@ This function returns @code{t} if point is on an image, 
and @code{nil}
 otherwise.
 @end defun
 
+@cindex operations on images
 Images inserted with the insertion functions above also get a local
 keymap installed in the text properties (or overlays) that span the
 displayed image.  This keymap defines the following commands:
 
 @table @kbd
+@findex image-increase-size
 @item i +
-Increase the image size (@code{image-increase-size}).  A prefix value
-of @samp{4} means to increase the size by 40%.  The default is 20%.
+Increase the image size (@code{image-increase-size})
 
+@findex image-decrease-size
 @item i -
-Decrease the image size (@code{image-increase-size}).  A prefix value
-of @samp{4} means to decrease the size by 40%.  The default is 20%.
+Decrease the image size (@code{image-decrease-size}).
 
+@findex image-rotate
 @item i r
-Rotate the image by 90 degrees clockwise (@code{image-rotate}).
-A prefix means to rotate by 90 degrees counter-clockwise instead.
+Rotate the image (@code{image-rotate}).
 
+@findex image-flip-horizontally
 @item i h
 Flip the image horizontally (@code{image-flip-horizontally}).
 
+@findex image-flip-vertically
 @item i v
 Flip the image vertically (@code{image-flip-vertically}).
 
+@findex image-save
 @item i o
 Save the image to a file (@code{image-save}).
 
+@findex image-crop
 @item i c
-Crop the image interactively (@code{image-crop}).
+Interactively crop the image (@code{image-crop}).
 
+@findex image-cut
 @item i x
-Cut a rectangle from the image interactively (@code{image-cut}).
+Interactively cut a rectangle from the image (@code{image-cut}).
 @end table
 
-The size and rotation commands are ``repeating'', which means that you
-can continue adjusting the image without using the @kbd{i} prefix.
+@xref{Image Mode,,, emacs, The GNU Emacs Manual}, for more details
+about these image-specific key bindings.
 
 @node Multi-Frame Images
 @subsection Multi-Frame Images
diff --git a/etc/NEWS b/etc/NEWS
index d0ae723587d..84dbb94a71a 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -222,9 +222,9 @@ In previous Emacs versions, images have had the '+', '-' 
and 'r' keys
 bound when point is over an image.  In Emacs 29.1, additional commands
 were added, and this made it more likely that users would trigger the
 image commands by mistake.  To avoid this, all image commands have
-moved to the 'i' keymap, so '+' is now 'i +', '-' is now 'i -', and
-'r' is now 'i r'.  In addition, these commands are now repeating, so
-you can rotate an image twice by saying 'i r r', for instance.
+moved to the 'i' prefix keymap, so '+' is now 'i +', '-' is now 'i -',
+and 'r' is now 'i r'.  In addition, these commands are now repeating,
+so, for example, you can rotate an image twice by typing 'i r r'.
 
 +++
 ** Emacs now picks the correct coding-system for X input methods.
@@ -2628,11 +2628,6 @@ This controls whether or not to show a message when 
opening certain
 image formats saying how to edit it as text.  The default is to show
 this message for SVG and XPM.
 
-+++
-*** New commands: 'image-flip-horizontally' and 'image-flip-vertically'.
-These commands horizontally and vertically flip the image under point,
-and are bound to 'i h' and 'i v', respectively.
-
 +++
 *** New command 'image-transform-set-percent'.
 It allows setting the image size to a percentage of its original size,
@@ -2648,6 +2643,19 @@ The old name was confusing, and is now an obsolete 
function alias.
 
 ** Images
 
++++
+** New commands 'image-crop' and 'image-cut'.
+These commands allow interactively cropping/cutting the image at
+point.  The commands are bound to keys 'i c' and 'i x' (respectively)
+in the local keymap over images.  They rely on external programs, by
+default "convert" from ImageMagick, to do the actual cropping/eliding
+of the image file.
+
++++
+*** New commands: 'image-flip-horizontally' and 'image-flip-vertically'.
+These commands horizontally and vertically flip the image under point,
+and are bound to 'i h' and 'i v', respectively.
+
 +++
 *** Users can now add special image conversion functions.
 This is done via 'image-converter-add-handler'.
@@ -3243,14 +3251,6 @@ macro, which allows you to isolate package configuration 
in your init
 file in a way that is declarative, tidy, and performance-oriented.
 See the new Info manual "(use-package) Top" for more.
 
-+++
-** New commands 'image-crop' and 'image-cut'.
-These commands allow interactively cropping/cutting the image at
-point.  The commands are bound to keys 'i c' and 'i x' (respectively)
-in the local keymap over images.  They rely on external programs, by
-default "convert" from ImageMagick, to do the actual cropping/eliding
-of the image file.
-
 ---
 ** New package 'wallpaper'.
 This package provides the command 'wallpaper-set', which sets the
diff --git a/lisp/image.el b/lisp/image.el
index 818679a4d7b..6a8293fedf3 100644
--- a/lisp/image.el
+++ b/lisp/image.el
@@ -172,22 +172,6 @@ or \"ffmpeg\") is installed."
 
 (define-error 'unknown-image-type "Unknown image type")
 
-(defvar-keymap image-map
-  :doc "Map put into text properties on images."
-  "i" (define-keymap
-        "-" #'image-decrease-size
-        "+" #'image-increase-size
-        "r" #'image-rotate
-        "o" #'image-save
-        "c" #'image-crop
-        "x" #'image-cut
-        "h" #'image-flip-horizontally
-        "v" #'image-flip-vertically)
-  "C-<wheel-down>" #'image-mouse-decrease-size
-  "C-<mouse-5>"    #'image-mouse-decrease-size
-  "C-<wheel-up>"   #'image-mouse-increase-size
-  "C-<mouse-4>"    #'image-mouse-increase-size)
-
 (defvar-keymap image-slice-map
   :doc "Map put into text properties on sliced images."
   "i" (define-keymap
@@ -201,6 +185,14 @@ or \"ffmpeg\") is installed."
   "C-<wheel-up>"   #'image-mouse-increase-size
   "C-<mouse-4>"    #'image-mouse-increase-size)
 
+(defvar-keymap image-map
+  :doc "Map put into text properties on images."
+  :parent image-slice-map
+  "i" (define-keymap
+        "r" #'image-rotate
+        "h" #'image-flip-horizontally
+        "v" #'image-flip-vertically))
+
 (defun image-load-path-for-library (library image &optional path no-error)
   "Return a suitable search path for images used by LIBRARY.