Merge pull request #6632 from radarhere/options

docs/handbook/image-file-formats.rst

@@ -31,6 +31,9 @@ BLP is the Blizzard Mipmap Format, a texture format used in World of
 Warcraft. Pillow supports reading ``JPEG`` Compressed or raw ``BLP1``
 images, and all types of ``BLP2`` images.
 
+Saving
+~~~~~~
+
 Pillow supports writing BLP images. The :py:meth:`~PIL.Image.Image.save` method
 can take the following keyword arguments:
 
@@ -46,6 +49,9 @@ or ``RGB`` data. 16-colour images are read as ``P`` images. 4-bit run-length enc
 is not supported. Support for reading 8-bit run-length encoding was added in Pillow
 9.1.0.
 
+Opening
+~~~~~~~
+
 The :py:meth:`~PIL.Image.open` method sets the following
 :py:attr:`~PIL.Image.Image.info` properties:
 
@@ -78,6 +84,9 @@ EPS images. The EPS driver can read EPS images in ``L``, ``LAB``, ``RGB`` and
 than leaving them in the original color space. The EPS driver can write images
 in ``L``, ``RGB`` and ``CMYK`` modes.
 
+Loading
+~~~~~~~
+
 If Ghostscript is available, you can call the :py:meth:`~PIL.Image.Image.load`
 method with the following parameters to affect how Ghostscript renders the EPS
 
@@ -134,6 +143,11 @@ To restore the default behavior, where ``P`` mode images are only converted to
     from PIL import GifImagePlugin
     GifImagePlugin.LOADING_STRATEGY = GifImagePlugin.LoadingStrategy.RGB_AFTER_FIRST
 
+.. _gif-opening:
+
+Opening
+~~~~~~~
+
 The :py:meth:`~PIL.Image.open` method sets the following
 :py:attr:`~PIL.Image.Image.info` properties:
 
@@ -171,6 +185,8 @@ to seek to the next frame (``im.seek(im.tell() + 1)``).
 
 ``im.seek()`` raises an :py:exc:`EOFError` if you try to seek after the last frame.
 
+.. _gif-saving:
+
 Saving
 ~~~~~~
 
@@ -278,6 +294,11 @@ sets the following :py:attr:`~PIL.Image.Image.info` property:
     ask for ``(512, 512, 2)``, the final value of
     :py:attr:`~PIL.Image.Image.size` will be ``(1024, 1024)``).
 
+.. _icns-saving:
+
+Saving
+~~~~~~
+
 The :py:meth:`~PIL.Image.Image.save` method can take the following keyword arguments:
 
 **append_images**
@@ -292,6 +313,11 @@ ICO
 
 ICO is used to store icons on Windows. The largest available icon is read.
 
+.. _ico-saving:
+
+Saving
+~~~~~~
+
 The :py:meth:`~PIL.Image.Image.save` method supports the following options:
 
 **sizes**
@@ -337,6 +363,11 @@ their original size while loading them.
 By default Pillow doesn't allow loading of truncated JPEG files, set
 :data:`.ImageFile.LOAD_TRUNCATED_IMAGES` to override this.
 
+.. _jpeg-opening:
+
+Opening
+~~~~~~~
+
 The :py:meth:`~PIL.Image.open` method may set the following
 :py:attr:`~PIL.Image.Image.info` properties if available:
 
@@ -383,6 +414,10 @@ The :py:meth:`~PIL.Image.open` method may set the following
 
     .. versionadded:: 7.1.0
 
+.. _jpeg-saving:
+
+Saving
+~~~~~~
 
 The :py:meth:`~PIL.Image.Image.save` method supports the following options:
 
@@ -464,6 +499,11 @@ itself.  It is also possible to set ``reduce`` to the number of resolutions to
 discard (each one reduces the size of the resulting image by a factor of 2),
 and ``layers`` to specify the number of quality layers to load.
 
+.. _jpeg-2000-saving:
+
+Saving
+~~~~~~
+
 The :py:meth:`~PIL.Image.Image.save` method supports the following options:
 
 **offset**
@@ -575,6 +615,11 @@ called.
 By default Pillow doesn't allow loading of truncated PNG files, set
 :data:`.ImageFile.LOAD_TRUNCATED_IMAGES` to override this.
 
+.. _png-opening:
+
+Opening
+~~~~~~~
+
 The :py:func:`~PIL.Image.open` function sets the following
 :py:attr:`~PIL.Image.Image.info` properties, when appropriate:
 
@@ -613,6 +658,11 @@ decompression bombs. Additionally, the total size of all of the text
 chunks is limited to :data:`.PngImagePlugin.MAX_TEXT_MEMORY`, defaulting to
 64MB.
 
+.. _png-saving:
+
+Saving
+~~~~~~
+
 The :py:meth:`~PIL.Image.Image.save` method supports the following options:
 
 **optimize**
@@ -803,6 +853,11 @@ Pillow also reads SPIDER stack files containing sequences of SPIDER images. The
 :py:meth:`~PIL.Image.Image.seek` and :py:meth:`~PIL.Image.Image.tell` methods are supported, and
 random access is allowed.
 
+.. _spider-opening:
+
+Opening
+~~~~~~~
+
 The :py:meth:`~PIL.Image.open` method sets the following attributes:
 
 **format**
@@ -819,8 +874,10 @@ is provided for converting floating point data to byte data (mode ``L``)::
 
     im = Image.open("image001.spi").convert2byte()
 
-Writing files in SPIDER format
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. _spider-saving:
+
+Saving
+~~~~~~
 
 The extension of SPIDER files may be any 3 alphanumeric characters. Therefore
 the output format must be specified explicitly::
@@ -837,6 +894,11 @@ Pillow reads and writes TGA images containing ``L``, ``LA``, ``P``,
 ``RGB``, and ``RGBA`` data. Pillow can read and write both uncompressed and
 run-length encoded TGAs.
 
+.. _tga-saving:
+
+Saving
+~~~~~~
+
 The :py:meth:`~PIL.Image.Image.save` method can take the following keyword arguments:
 
 **compression**
@@ -871,6 +933,11 @@ uncompressed files.
     support for reading Packbits, LZW and JPEG compressed TIFFs
     without using libtiff.
 
+.. _tiff-opening:
+
+Opening
+~~~~~~~
+
 The :py:meth:`~PIL.Image.open` method sets the following
 :py:attr:`~PIL.Image.Image.info` properties:
 
@@ -922,8 +989,10 @@ and 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
-~~~~~~~~~~~~~~~~~~
+.. _tiff-saving:
+
+Saving
+~~~~~~
 
 The :py:meth:`~PIL.Image.Image.save` method can take the following keyword arguments:
 
@@ -1035,6 +1104,11 @@ WebP
 Pillow reads and writes WebP files. The specifics of Pillow's capabilities with
 this format are currently undocumented.
 
+.. _webp-saving:
+
+Saving
+~~~~~~
+
 The :py:meth:`~PIL.Image.Image.save` method supports the following options:
 
 **lossless**
@@ -1058,7 +1132,7 @@ The :py:meth:`~PIL.Image.Image.save` method supports the following options:
     the system WebP library was built with webpmux support.
 
 Saving sequences
-~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~
 
 .. note::
 
@@ -1173,6 +1247,11 @@ GBR
 
 The GBR decoder reads GIMP brush files, version 1 and 2.
 
+.. _gbr-opening:
+
+Opening
+~~~~~~~
+
 The :py:meth:`~PIL.Image.open` method sets the following
 :py:attr:`~PIL.Image.Image.info` properties:
 
@@ -1188,6 +1267,11 @@ GD
 Pillow reads uncompressed GD2 files. Note that you must use
 :py:func:`PIL.GdImageFile.open` to read such a file.
 
+.. _gd-opening:
+
+Opening
+~~~~~~~
+
 The :py:meth:`~PIL.Image.open` method sets the following
 :py:attr:`~PIL.Image.Image.info` properties:
 
@@ -1227,6 +1311,11 @@ image when first opened. The :py:meth:`~PIL.Image.Image.seek` and :py:meth:`~PIL
 methods may be used to read other pictures from the file. The pictures are
 zero-indexed and random access is supported.
 
+.. _mpo-saving:
+
+Saving
+~~~~~~
+
 When calling :py:meth:`~PIL.Image.Image.save` to write an MPO file, by default
 only the first frame of a multiframe image will be saved. If the ``save_all``
 argument is present and true, then all frames will be saved, and the following
@@ -1326,6 +1415,11 @@ XPM
 
 Pillow reads X pixmap files (mode ``P``) with 256 colors or less.
 
+.. _xpm-opening:
+
+Opening
+~~~~~~~
+
 The :py:meth:`~PIL.Image.open` method sets the following
 :py:attr:`~PIL.Image.Image.info` properties:
 
@@ -1350,6 +1444,11 @@ Pillow can write PDF (Acrobat) images. Such images are written as binary PDF 1.4
 files, using either JPEG or HEX encoding depending on the image mode (and
 whether JPEG support is available or not).
 
+.. _pdf-saving:
+
+Saving
+~~~~~~
+
 The :py:meth:`~PIL.Image.Image.save` method can take the following keyword arguments:
 
 **save_all**