From 7ca0c189e3dda06b847037bd6c04700d6014ab19 Mon Sep 17 00:00:00 2001
From: Andrew Kuchling <amk@amk.ca>
Date: Fri, 15 Mar 2019 23:09:09 -0400
Subject: [PATCH] Various documentation fixes [ci skip]

* TIFF: describe num_frames and seek()/tell()
* Link methods to PIL.Image class instead of the Python file object
* It doesn't seem like the Spider plug-in actually has an 'nimages' attribute
* Fix markup for exception name
---
 docs/handbook/image-file-formats.rst | 37 ++++++++++++++++++++--------
 1 file changed, 27 insertions(+), 10 deletions(-)

diff --git a/docs/handbook/image-file-formats.rst b/docs/handbook/image-file-formats.rst
index fc7b92e45..22828e5a1 100644
--- a/docs/handbook/image-file-formats.rst
+++ b/docs/handbook/image-file-formats.rst
@@ -104,11 +104,11 @@ The :py:meth:`~PIL.Image.Image.open` method sets the following
 Reading sequences
 ~~~~~~~~~~~~~~~~~
 
-The GIF loader supports the :py:meth:`~file.seek` and :py:meth:`~file.tell`
-methods. You can combine these methods to seek to the next frame
-(``im.seek(im.tell() + 1)``).
+The GIF loader supports the :py:meth:`~PIL.Image.Image.seek` and
+:py:meth:`~PIL.Image.Image.tell` methods. You can combine these methods
+to seek to the next frame (``im.seek(im.tell() + 1)``).
 
-``im.seek()`` raises an ``EOFError`` if you try to seek after the last frame.
+``im.seek()`` raises an :py:exc:`EOFError` if you try to seek after the last frame.
 
 Saving
 ~~~~~~
@@ -569,7 +569,7 @@ Pillow reads and writes SPIDER image files of 32-bit floating point data
 ("F;32F").
 
 Pillow also reads SPIDER stack files containing sequences of SPIDER images. The
-:py:meth:`~file.seek` and :py:meth:`~file.tell` methods are supported, and
+:py:meth:`~PIL.Image.Image.seek` and :py:meth:`~PIL.Image.Image.tell` methods are supported, and
 random access is allowed.
 
 The :py:meth:`~PIL.Image.Image.open` method sets the following attributes:
@@ -580,7 +580,7 @@ The :py:meth:`~PIL.Image.Image.open` method sets the following attributes:
 **istack**
     Set to 1 if the file is an image stack, else 0.
 
-**nimages**
+**n_frames**
     Set to the number of images in the stack.
 
 A convenience method, :py:meth:`~PIL.Image.Image.convert2byte`, is provided for
@@ -640,6 +640,9 @@ The :py:meth:`~PIL.Image.Image.open` method sets the following
 
     .. versionadded:: 1.1.5
 
+**n_frames**
+    Number of frames in the TIFF file.
+
 **resolution**
     Image resolution as an ``(xres, yres)`` tuple, where applicable. This is a
     measurement in whichever unit is specified by the file.
@@ -665,6 +668,20 @@ numbers are returned as a tuple of ``(numerator, denominator)``.
     .. deprecated:: 3.0.0
 
 
+Reading Multi-frame TIFF Images
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The TIFF loader supports the :py:meth:`~PIL.Image.Image.seek` and
+:py:meth:`~PIL.Image.Image.tell` methods, taking and returning frame
+numbers within the image file.  Frames are numbered from 0 to
+`im.num_frames - 1`.  You can seek to the next frame
+(``im.seek(im.tell() + 1)``), or rewind the file by seeking to the
+first frame.  Images can be accessed in any order.
+
+``im.seek()`` raises an :py:exc:`EOFError` if you try to seek after the
+last frame.
+
+
 Saving Tiff Images
 ~~~~~~~~~~~~~~~~~~
 
@@ -851,7 +868,7 @@ is commonly used in fax applications. The DCX decoder can read files containing
 ``1``, ``L``, ``P``, or ``RGB`` data.
 
 When the file is opened, only the first image is read. You can use
-:py:meth:`~file.seek` or :py:mod:`~PIL.ImageSequence` to read other images.
+:py:meth:`~PIL.Image.Image.seek` or :py:mod:`~PIL.ImageSequence` to read other images.
 
 
 DDS
@@ -943,8 +960,8 @@ MIC
 ^^^
 
 Pillow identifies and reads Microsoft Image Composer (MIC) files. When opened,
-the first sprite in the file is loaded. You can use :py:meth:`~file.seek` and
-:py:meth:`~file.tell` to read other sprites from the file.
+the first sprite in the file is loaded. You can use :py:meth:`~PIL.Image.Image.seek` and
+:py:meth:`~PIL.Image.Image.tell` to read other sprites from the file.
 
 Note that there may be an embedded gamma of 2.2 in MIC files.
 
@@ -952,7 +969,7 @@ MPO
 ^^^
 
 Pillow identifies and reads Multi Picture Object (MPO) files, loading the primary
-image when first opened. The :py:meth:`~file.seek` and :py:meth:`~file.tell`
+image when first opened. The :py:meth:`~PIL.Image.Image.seek` and :py:meth:`~PIL.Image.Image.tell`
 methods may be used to read other pictures from the file. The pictures are
 zero-indexed and random access is supported.