[Emacs-diffs] /srv/bzr/emacs/trunk r111833: Lispref updates for multi-frame images

[Glenn Morris]

------------------------------------------------------------
revno: 111833
committer: Glenn Morris <address@hidden>
branch nick: trunk
timestamp: Wed 2013-02-20 00:34:28 -0800
message:
  Lispref updates for multi-frame images
  
  * doc/lispref/display.texi (GIF Images, TIFF Images): Delete these nodes.
  (ImageMagick Images): For :index, use an xref rather than duplicating.
  (Other Image Types): Add GIF, adjust formatting.
  (Multi-Frame Images): Rename from Animated Images.  Expand section.
  
  * doc/lispref/elisp.texi (Top): Update menu for these changes.
modified:
  doc/lispref/ChangeLog
  doc/lispref/display.texi
  doc/lispref/elisp.texi

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2013-02-19 03:29:28 +0000
+++ b/doc/lispref/ChangeLog     2013-02-20 08:34:28 +0000
@@ -1,3 +1,11 @@
+2013-02-20  Glenn Morris  <address@hidden>
+
+       * display.texi (GIF Images, TIFF Images): Delete these nodes.
+       (ImageMagick Images): For :index, use an xref rather than duplicating.
+       (Other Image Types): Add GIF, adjust formatting.
+       (Multi-Frame Images): Rename from Animated Images.  Expand section.
+       * elisp.texi (Top): Update menu for these changes.
+
 2013-02-19  Glenn Morris  <address@hidden>
 
        * text.texi (Change Hooks): Fix typo.

=== modified file 'doc/lispref/display.texi'
--- a/doc/lispref/display.texi  2013-01-05 21:18:01 +0000
+++ b/doc/lispref/display.texi  2013-02-20 08:34:28 +0000
@@ -4199,14 +4199,12 @@
 * Image Descriptors::   How to specify an image for use in @code{:display}.
 * XBM Images::          Special features for XBM format.
 * XPM Images::          Special features for XPM format.
-* GIF Images::          Special features for GIF format.
-* TIFF Images::         Special features for TIFF format.
 * PostScript Images::   Special features for PostScript format.
 * ImageMagick Images::  Special features available through ImageMagick.
 * Other Image Types::   Various other formats are supported.
 * Defining Images::     Convenient ways to define an image for later use.
 * Showing Images::      Convenient ways to display an image once it is defined.
-* Animated Images::     Some image formats can be animated.
+* Multi-Frame Images::  Some images contain more than one frame.
 * Image Cache::         Internal mechanisms of image display.
 @end menu
 
@@ -4541,35 +4539,6 @@
 specifies the actual color to use for displaying that name.
 @end table
 
address@hidden GIF Images
address@hidden GIF Images
address@hidden GIF
-
-  For GIF images, specify image type @code{gif}.
-
address@hidden @code
address@hidden :index @var{index}
-You can use @code{:index} to specify image number @var{index} from a
-GIF file that contains more than one image.  If the GIF file doesn't
-contain an image with the specified index, the image displays as a
-hollow box.  GIF files with more than one image can be animated,
address@hidden Images}.
address@hidden table
-
address@hidden TIFF Images
address@hidden TIFF Images
address@hidden TIFF
-
-  For TIFF images, specify image type @code{tiff}.
-
address@hidden @code
address@hidden :index @var{index}
-You can use @code{:index} to specify image number @var{index} from a
-TIFF file that contains more than one image.  If the TIFF file doesn't
-contain an image with the specified index, the image displays as a
-hollow box.
address@hidden table
-
 @node PostScript Images
 @subsection PostScript Images
 @cindex postscript images
@@ -4653,10 +4622,7 @@
 
 @item :index
 @c Doesn't work: http://debbugs.gnu.org/7978
-This has the same meaning as it does for GIF images (@pxref{GIF Images}),
-i.e., it specifies which image to view inside an image bundle file format
-such as address@hidden  You can use the @code{image-metadata} function to
-retrieve the total number of images in an image bundle.
address@hidden Images}.
 @end table
 
 @node Other Image Types
@@ -4681,13 +4647,27 @@
 background color.
 @end table
 
-  For JPEG images, specify image type @code{jpeg}.
-
-  For TIFF images, specify image type @code{tiff}.
-
-  For PNG images, specify image type @code{png}.
-
-  For SVG images, specify image type @code{svg}.
address@hidden
+The remaining image types that Emacs can support are:
+
address@hidden @asis
address@hidden GIF
+Image type @code{gif}.
+Supports the @code{:index} property.  @xref{Multi-Frame Images}.
+
address@hidden JPEG
+Image type @code{jpeg}.
+
address@hidden PNG
+Image type @code{png}.
+
address@hidden SVG
+Image type @code{svg}.
+
address@hidden TIFF
+Image type @code{tiff}.
+Supports the @code{:index} property.  @xref{Multi-Frame Images}.
address@hidden table
 
 @node Defining Images
 @subsection Defining Images
@@ -4923,20 +4903,45 @@
 @var{max-image-size} is subsequently changed (@pxref{Image Cache}).
 @end defvar
 
address@hidden Animated Images
address@hidden Animated Images
address@hidden Multi-Frame Images
address@hidden Multi-Frame Images
 
 @cindex animation
 @cindex image animation
-Some image files can contain more than one image.  This can be used to
-create animation.  Currently, Emacs only supports animated GIF files.
-The following functions related to animated images are available.
-
address@hidden image-animated-p image
-This function returns address@hidden if @var{image} can be animated.
-The actual return value is a cons @code{(@var{nimages} . @var{delay})},
-where @var{nimages} is the number of frames and @var{delay} is the
-delay in seconds between them.
address@hidden image frames
+Some image files can contain more than one image.  We say that there
+are multiple ``frames'' in the image.  At present, Emacs supports
+multiple frames for GIF, TIFF, and certain ImageMagick formats such as
address@hidden
+
+The frames can be used either to represent multiple ``pages'' (this is
+usually the case with multi-frame TIFF files, for example), or to
+create animation (usually the case with multi-frame GIF files).
+
+A multi-frame image has a property @code{:index}, whose value is an
+integer (counting from 0) that specifies which frame is being displayed.
+
address@hidden image-multi-frame-p image
+This function returns address@hidden if @var{image} contains more than
+one frame.  The actual return value is a cons @code{(@var{nimages}
+. @var{delay})}, where @var{nimages} is the number of frames and
address@hidden is the delay in seconds between them, if the image itself
+specifies a delay.  Images that are intended to be animated usually
+specify a frame delay, whereas ones that are intended to be treated as
+multiple pages do not.
address@hidden defun
+
address@hidden image-current-frame image
+This function returns the index of the current frame number for
address@hidden, counting from 0.
address@hidden defun
+
address@hidden image-show-frame image n &optional nocheck
+This function switches @var{image} to frame number @var{n}.  It
+replaces a frame number outside the valid range with that of the end
+of the range, unless @var{nocheck} is address@hidden  If @var{image}
+does not contain a frame with the specified number, the image displays
+as a hollow box.
 @end defun
 
 @defun image-animate image &optional index limit
@@ -4948,7 +4953,9 @@
 @end defun
 
 @noindent Animation operates by means of a timer.  Note that Emacs imposes a
-minimum frame delay of 0.01 seconds.
+minimum frame delay of 0.01 (@code{image-minimum-frame-delay}) seconds.
+If the image itself does not specify a delay, Emacs uses
address@hidden
 
 @defun image-animate-timer image
 This function returns the timer responsible for animating @var{image},

=== modified file 'doc/lispref/elisp.texi'
--- a/doc/lispref/elisp.texi    2013-02-09 12:52:01 +0000
+++ b/doc/lispref/elisp.texi    2013-02-20 08:34:28 +0000
@@ -1417,15 +1417,13 @@
 * Image Descriptors::       How to specify an image for use in @code{:display}.
 * XBM Images::              Special features for XBM format.
 * XPM Images::              Special features for XPM format.
-* GIF Images::              Special features for GIF format.
-* TIFF Images::             Special features for TIFF format.
 * PostScript Images::       Special features for PostScript format.
 * ImageMagick Images::      Special features available through ImageMagick.
 * Other Image Types::       Various other formats are supported.
 * Defining Images::         Convenient ways to define an image for later use.
 * Showing Images::          Convenient ways to display an image once
                               it is defined.
-* Animated Images::         Some image formats can be animated.
+* Multi-Frame Images::      Some images contain more than one frame.
 * Image Cache::             Internal mechanisms of image display.
 
 Buttons