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.

2 files changed, 111 insertions, 12 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