libtiff: doc: Missing public functions added to TIFF documentation in Sphinx

From 644558a24f12fcd7ae226cb289686f91563c2cf3 Mon Sep 17 00:00:00 2001
From: Su Laus <[EMAIL REDACTED]>
Date: Sun, 7 Aug 2022 20:52:27 +0000
Subject: [PATCH] doc: Missing public functions added to TIFF documentation in
 Sphinx

---
 doc/Makefile.am                               |  14 +
 doc/addingtags.rst                            |  25 +-
 doc/conf.py                                   |  14 +
 doc/contrib.rst                               |   2 +-
 doc/functions.rst                             |  14 +
 doc/functions/TIFFAccessTagMethods.rst        |  30 ++
 doc/functions/TIFFClientInfo.rst              |  40 +++
 doc/functions/TIFFClose.rst                   |   8 +-
 doc/functions/TIFFCreateDirectory.rst         |  75 +++++
 doc/functions/TIFFCustomDirectory.rst         | 203 +++++++++++++
 doc/functions/TIFFCustomTagList.rst           |  47 +++
 doc/functions/TIFFDataWidth.rst               |   7 +-
 doc/functions/TIFFDeferStrileArrayWriting.rst |  67 +++++
 doc/functions/TIFFError.rst                   |  42 ++-
 doc/functions/TIFFFieldDataType.rst           |   4 +-
 doc/functions/TIFFFieldName.rst               |   5 +-
 doc/functions/TIFFFieldPassCount.rst          |  12 +-
 doc/functions/TIFFFieldQuery.rst              |  78 +++++
 doc/functions/TIFFFieldReadCount.rst          |  19 +-
 doc/functions/TIFFFieldTag.rst                |   3 +-
 doc/functions/TIFFFieldWriteCount.rst         |  32 +-
 doc/functions/TIFFFlush.rst                   |   2 +-
 doc/functions/TIFFGetField.rst                |   2 +-
 doc/functions/TIFFMergeFieldInfo.rst          |  34 +++
 doc/functions/TIFFOpen.rst                    |  37 ++-
 doc/functions/TIFFPrintDirectory.rst          |   4 +-
 doc/functions/TIFFProcFunctions.rst           |  57 ++++
 doc/functions/TIFFRGBAImage.rst               |   8 +-
 doc/functions/TIFFReadDirectory.rst           |   9 +-
 doc/functions/TIFFReadEncodedStrip.rst        |   3 +-
 doc/functions/TIFFReadEncodedTile.rst         |   1 +
 doc/functions/TIFFReadFromUserBuffer.rst      |  46 +++
 doc/functions/TIFFReadRGBAImage.rst           |   2 +
 doc/functions/TIFFReadRGBAStrip.rst           |   9 +-
 doc/functions/TIFFReadRGBATile.rst            |  11 +-
 doc/functions/TIFFReadRawTile.rst             |  10 +-
 doc/functions/TIFFSetDirectory.rst            |  13 +-
 doc/functions/TIFFSetField.rst                |   5 +
 doc/functions/TIFFSetTagExtender.rst          |  27 ++
 doc/functions/TIFFStrileQuery.rst             |  75 +++++
 doc/functions/TIFFWarning.rst                 |  40 ++-
 doc/functions/TIFFWriteDirectory.rst          |  25 +-
 doc/functions/TIFFWriteEncodedStrip.rst       |   2 +-
 doc/functions/TIFFWriteRawTile.rst            |   3 +-
 doc/functions/TIFFWriteScanline.rst           |   2 +-
 doc/functions/TIFFbuffer.rst                  |  20 +-
 doc/functions/TIFFcodec.rst                   |  19 ++
 doc/functions/TIFFmemory.rst                  |   8 +
 doc/functions/TIFFquery.rst                   |  89 ++++--
 doc/functions/TIFFsize.rst                    |  12 +
 doc/functions/TIFFstrip.rst                   |  29 +-
 doc/functions/TIFFswab.rst                    |  41 ++-
 doc/functions/TIFFtile.rst                    |  12 +
 doc/functions/_TIFFRewriteField.rst           |  33 +++
 doc/functions/_TIFFauxiliary.rst              |  34 +++
 doc/functions/libtiff.rst                     | 279 +++++++++++++++---
 doc/libtiff.rst                               |  10 +-
 57 files changed, 1576 insertions(+), 178 deletions(-)
 create mode 100644 doc/functions/TIFFAccessTagMethods.rst
 create mode 100644 doc/functions/TIFFClientInfo.rst
 create mode 100644 doc/functions/TIFFCreateDirectory.rst
 create mode 100644 doc/functions/TIFFCustomDirectory.rst
 create mode 100644 doc/functions/TIFFCustomTagList.rst
 create mode 100644 doc/functions/TIFFDeferStrileArrayWriting.rst
 create mode 100644 doc/functions/TIFFFieldQuery.rst
 create mode 100644 doc/functions/TIFFMergeFieldInfo.rst
 create mode 100644 doc/functions/TIFFProcFunctions.rst
 create mode 100644 doc/functions/TIFFReadFromUserBuffer.rst
 create mode 100644 doc/functions/TIFFSetTagExtender.rst
 create mode 100644 doc/functions/TIFFStrileQuery.rst
 create mode 100644 doc/functions/_TIFFRewriteField.rst
 create mode 100644 doc/functions/_TIFFauxiliary.rst

diff --git a/doc/Makefile.am b/doc/Makefile.am
index e451248f..e4460c4f 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -240,6 +240,20 @@ rst_sources = \
 	functions/TIFFReadRGBAStrip.rst \
 	functions/TIFFquery.rst \
 	functions/TIFFWriteEncodedTile.rst \
+	functions/_TIFFauxiliary.rst \
+	functions/_TIFFRewriteField.rst \
+	functions/TIFFAccessTagMethods.rst \
+	functions/TIFFClientInfo.rst \
+	functions/TIFFCreateDirectory.rst \
+	functions/TIFFCustomDirectory.rst \
+	functions/TIFFCustomTagList.rst \
+	functions/TIFFDeferStrileArrayWriting.rst \
+	functions/TIFFFieldQuery.rst \
+	functions/TIFFMergeFieldInfo.rst \
+	functions/TIFFProcFunctions.rst \
+	functions/TIFFReadFromUserBuffer.rst \
+	functions/TIFFSetTagExtender.rst \
+	functions/TIFFStrileQuery.rst \
 	libtiff.rst \
 	images.rst
 
diff --git a/doc/addingtags.rst b/doc/addingtags.rst
index d3f2d8a9..c035c75d 100644
--- a/doc/addingtags.rst
+++ b/doc/addingtags.rst
@@ -4,7 +4,9 @@ Defining New TIFF Tags
 Libtiff has built-in knowledge of all the standard TIFF tags, as
 well as extensions.  The following describes how to add knowledge of
 new tags as builtins to libtiff, or how to application specific tags can
-be used by applications without modifying libtiff. 
+be used by applications without modifying libtiff.
+
+.. _TIFFFieldInfo_Definition:
 
 TIFFFieldInfo
 -------------
@@ -103,15 +105,17 @@ definitions, including :c:func:`_TIFFFindFieldInfo`, and
 :file:`tif_dirinfo.c` for details.  There must be some mechanism to get the whole
 list, though I don't see it off hand.
 
+.. _Tag_Auto_registration:
+
 Default Tag Auto-registration
 -----------------------------
 
-In libtiff 3.6.0 a new mechanism was introduced allowing libtiff to 
-read unrecognised tags automatically.  When an unknown tags is encountered, 
-it is automatically internally defined with a default name and a type 
+In libtiff 3.6.0 a new mechanism was introduced allowing libtiff to
+read unrecognised tags automatically.  When an unknown tags is encountered,
+it is automatically internally defined with a default name and a type
 derived from the tag value in the file.  Applications only need to predefine
 application specific tags if they need to be able to set them in a file, or
-if particular calling conventions are desired for :c:func:`TIFFSetField` and 
+if particular calling conventions are desired for :c:func:`TIFFSetField` and
 :c:func:`TIFFGetField`.
 
 When tags are autodefined like this the :c:member:`field_readcount` and
@@ -128,11 +132,14 @@ Thus, to read anonymous auto-registered tags use the following:
     void* value;  //has to be a pointer to the expected value type.
     TIFFGetField(tif, TIFFTAG_UNKNOWN_TO_LIBTIFF, &count, &value);
 
+
+.. _Define_Application_Tags:
+
 Defining Application Tags
 -------------------------
 
 For various reasons, it is common for applications to want to define
-their own tags to store information outside the core TIFF specification. 
+their own tags to store information outside the core TIFF specification.
 This is done by calling :c:func:`TIFFMergeFieldInfo` with one or more
 :c:struct:`TIFFFieldInfo`.
 
@@ -143,7 +150,7 @@ information on the new tags:
 ::
 
     static const TIFFFieldInfo xtiffFieldInfo[] = {
-  
+
         /* XXX Insert Your tags here */
         { TIFFTAG_GEOPIXELSCALE,	-1,-1, TIFF_DOUBLE,	FIELD_CUSTOM,
           TRUE,	TRUE,	"GeoPixelScale" },
@@ -173,7 +180,7 @@ The tags need to be defined for each TIFF file opened - and when reading
 they should be defined before the tags of the file are read, yet a valid
 :c:expr:`TIFF *` is needed to merge the tags against.  In order to get them
 registered at the appropriate part of the setup process, it is necessary
-to register our merge function as an extender callback with libtiff. 
+to register our merge function as an extender callback with libtiff.
 This is done with :c:func:`TIFFSetTagExtender`.  We also keep track of the
 previous tag extender (if any) so that we can call it from our extender
 allowing a chain of customizations to take effect.
@@ -215,7 +222,7 @@ and then calls the next extender if there is one in effect.
     }
 
 The above approach ensures that our new definitions are used when reading
-or writing any TIFF file.  However, since on reading we already have 
+or writing any TIFF file.  However, since on reading we already have
 default definitions for tags, it is usually not critical to pre-define them.
 If tag definitions are only required for writing custom tags, you can just
 call :c:func:`TIFFMergeFieldInfo` before setting new tags.  The whole extender
diff --git a/doc/conf.py b/doc/conf.py
index 9cafcd32..dfa46eb4 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -114,27 +114,39 @@
     ('tools/tiffset', 'tiffset', 'set or unset a field in a TIFF header', author, 1),
     ('tools/tiffsplit', 'tiffsplit', 'split a multi-image TIFF into single-image TIFF files', author, 1),
 
+    ('functions/_TIFFauxiliary', '_TIFFauxiliary', 'auxiliary functions', author, '3tiff'),
+    ('functions/_TIFFRewriteField', '_TIFFRewriteField', 'rewrite a field in the directory on disk', author, '3tiff'),
+    ('functions/TIFFAccessTagMethods', 'TIFFAccessTagMethods', 'provides read/write access to the TIFFTagMethods', author, '3tiff'),
     ('functions/TIFFbuffer', 'TIFFbuffer', 'I/O buffering control routines', author, '3tiff'),
+    ('functions/TIFFClientInfo', 'TIFFClientInfo', 'provides a method to hand over user defined data from one routine to another', author, '3tiff'),
     ('functions/TIFFClose', 'TIFFClose', 'close a previously opened TIFF file', author, '3tiff'),
     ('functions/TIFFcodec', 'TIFFcodec', 'codec-related utility routines', author, '3tiff'),
     ('functions/TIFFcolor', 'TIFFcolor', 'color conversion routines', author, '3tiff'),
+    ('functions/TIFFCreateDirectory', 'TIFFCreateDirectory', 'routines to create a directory and retrieve information about directories', author, '3tiff'),
+    ('functions/TIFFCustomDirectory', 'TIFFCustomDirectory', 'routines to create a custom directory', author, '3tiff'),
+    ('functions/TIFFCustomTagList', 'TIFFCustomTagList', 'returns information about the custom tag list', author, '3tiff'),
     ('functions/TIFFDataWidth', 'TIFFDataWidth', 'get the size of TIFF data types', author, '3tiff'),
+    ('functions/TIFFDeferStrileArrayWriting', 'TIFFDeferStrileArrayWriting', 'defer strile array writing', author, '3tiff'),
     ('functions/TIFFError', 'TIFFError', 'library error handling interface', author, '3tiff'),
     ('functions/TIFFFieldDataType', 'TIFFFieldDataType', 'get TIFF data type from field information', author, '3tiff'),
     ('functions/TIFFFieldName', 'TIFFFieldName', 'get TIFF field name from field information', author, '3tiff'),
     ('functions/TIFFFieldPassCount', 'TIFFFieldPassCount', 'get whether to pass a count to TIFFGetField/TIFFSetField', author, '3tiff'),
+    ('functions/TIFFFieldQuery', 'TIFFFieldQuery', 'routines to query TIFF field information', author, '3tiff'),
     ('functions/TIFFFieldReadCount', 'TIFFFieldReadCount', 'get number of values to be read from field', author, '3tiff'),
     ('functions/TIFFFieldTag', 'TIFFFieldTag', 'get TIFF field tag value from field information', author, '3tiff'),
     ('functions/TIFFFieldWriteCount', 'TIFFFieldWriteCount', 'get number of values to be written to field', author, '3tiff'),
     ('functions/TIFFFlush', 'TIFFFlush', 'flush pending writes to an open TIFF file', author, '3tiff'),
     ('functions/TIFFGetField', 'TIFFGetField', 'get the value(s) of a tag in an open TIFF file', author, '3tiff'),
     ('functions/TIFFmemory', 'TIFFmemory', 'memory management-related functions for use with TIFF files', author, '3tiff'),
+    ('functions/TIFFMergeFieldInfo', 'TIFFMergeFieldInfo', 'add application-defined TIFF tags to the list of known libtiff tags', author, '3tiff'),
     ('functions/TIFFOpen', 'TIFFOpen', 'open a TIFF file for reading or writing', author, '3tiff'),
     ('functions/TIFFPrintDirectory', 'TIFFPrintDirectory', 'print a description of a TIFF directory', author, '3tiff'),
+    ('functions/TIFFProcFunctions', 'TIFFProcFunctions', 'set TIFF processing functions', author, '3tiff'),
     ('functions/TIFFquery', 'TIFFquery', 'query routines', author, '3tiff'),
     ('functions/TIFFReadDirectory', 'TIFFReadDirectory', 'get the contents of the next directory in an open TIFF file', author, '3tiff'),
     ('functions/TIFFReadEncodedStrip', 'TIFFReadEncodedStrip', 'read and decode a strip of data from an open TIFF file', author, '3tiff'),
     ('functions/TIFFReadEncodedTile', 'TIFFReadEncodedTile', 'read and decode a tile of data from an open TIFF file', author, '3tiff'),
+    ('functions/TIFFReadFromUserBuffer', 'TIFFReadFromUserBuffer', 'decode data using an user defined buffer', author, '3tiff'),
     ('functions/TIFFReadRawStrip', 'TIFFReadRawStrip', 'return the undecoded contents of a strip of data from an open TIFF file', author, '3tiff'),
     ('functions/TIFFReadRawTile', 'TIFFReadRawTile', 'return an undecoded tile of data from an open TIFF file', author, '3tiff'),
     ('functions/TIFFReadRGBAImage', 'TIFFReadRGBAImage', 'read and decode an image into a fixed-format raster', author, '3tiff'),
@@ -145,7 +157,9 @@
     ('functions/TIFFRGBAImage', 'TIFFRGBAImage', 'read and decode an image into a raster', author, '3tiff'),
     ('functions/TIFFSetDirectory', 'TIFFSetDirectory', 'set the current directory for an open TIFF file', author, '3tiff'),
     ('functions/TIFFSetField', 'TIFFSetField', 'set the value(s) of a tag in a TIFF file open for writing', author, '3tiff'),
+    ('functions/TIFFSetTagExtender', 'TIFFSetTagExtender', 'register the merge function for user defined tags as an extender callback with libtiff', author, '3tiff'),
     ('functions/TIFFsize', 'TIFFsize', 'return the size of various items associated with an open TIFF file', author, '3tiff'),
+    ('functions/TIFFStrileQuery', 'TIFFStrileQuery', 'get strile byte count and offset', author, '3tiff'),
     ('functions/TIFFstrip', 'TIFFstrip', 'strip-related utility routines', author, '3tiff'),
     ('functions/TIFFswab', 'TIFFswab', 'byte- and bit-swapping routines', author, '3tiff'),
     ('functions/TIFFtile', 'TIFFtile', 'tile-related utility routines', author, '3tiff'),
diff --git a/doc/contrib.rst b/doc/contrib.rst
index 58617b89..0b94970a 100644
--- a/doc/contrib.rst
+++ b/doc/contrib.rst
@@ -85,4 +85,4 @@ aren't directly TIFF related).
 
 
 Questions regarding these packages are usually best directed toward
-their authors. 
+their authors.
diff --git a/doc/functions.rst b/doc/functions.rst
index f544d0e0..774bb412 100644
--- a/doc/functions.rst
+++ b/doc/functions.rst
@@ -6,27 +6,37 @@ TIFF Functions Overview
     :titlesonly:
 
     functions/libtiff
+    functions/TIFFAccessTagMethods
     functions/TIFFbuffer
+    functions/TIFFClientInfo
     functions/TIFFClose
     functions/TIFFcodec
     functions/TIFFcolor
+    functions/TIFFCreateDirectory
+    functions/TIFFCustomDirectory
+    functions/TIFFCustomTagList
     functions/TIFFDataWidth
+    functions/TIFFDeferStrileArrayWriting
     functions/TIFFError
     functions/TIFFFieldDataType
     functions/TIFFFieldName
     functions/TIFFFieldPassCount
+    functions/TIFFFieldQuery
     functions/TIFFFieldReadCount
     functions/TIFFFieldTag
     functions/TIFFFieldWriteCount
     functions/TIFFFlush
     functions/TIFFGetField
     functions/TIFFmemory
+    functions/TIFFMergeFieldInfo
     functions/TIFFOpen
     functions/TIFFPrintDirectory
+    functions/TIFFProcFunctions
     functions/TIFFquery
     functions/TIFFReadDirectory
     functions/TIFFReadEncodedStrip
     functions/TIFFReadEncodedTile
+    functions/TIFFReadFromUserBuffer
     functions/TIFFReadRawStrip
     functions/TIFFReadRawTile
     functions/TIFFReadRGBAImage
@@ -37,7 +47,9 @@ TIFF Functions Overview
     functions/TIFFRGBAImage
     functions/TIFFSetDirectory
     functions/TIFFSetField
+    functions/TIFFSetTagExtender
     functions/TIFFsize
+    functions/TIFFStrileQuery
     functions/TIFFstrip
     functions/TIFFswab
     functions/TIFFtile
@@ -49,3 +61,5 @@ TIFF Functions Overview
     functions/TIFFWriteRawTile
     functions/TIFFWriteScanline
     functions/TIFFWriteTile
+    functions/_TIFFauxiliary
+    functions/_TIFFRewriteField
diff --git a/doc/functions/TIFFAccessTagMethods.rst b/doc/functions/TIFFAccessTagMethods.rst
new file mode 100644
index 00000000..c9a53dc0
--- /dev/null
+++ b/doc/functions/TIFFAccessTagMethods.rst
@@ -0,0 +1,30 @@
+TIFFAccessTagMethods
+====================
+
+Synopsis
+--------
+
+.. highlight:: c
+
+::
+
+    #include <tiffio.h>
+
+.. c:function:: TIFFTagMethods *TIFFAccessTagMethods(TIFF* tif)
+
+Description
+-----------
+
+This provides read/write access to the TIFFTagMethods within the TIFF
+structure to application code without giving access to the private TIFF
+structure.
+
+Diagnostics
+-----------
+
+None
+
+See also
+--------
+
+:doc:`libtiff` (3tiff)
diff --git a/doc/functions/TIFFClientInfo.rst b/doc/functions/TIFFClientInfo.rst
new file mode 100644
index 00000000..7576d225
--- /dev/null
+++ b/doc/functions/TIFFClientInfo.rst
@@ -0,0 +1,40 @@
+TIFFClientInfo
+==============
+
+Synopsis
+--------
+
+.. highlight:: c
+
+::
+
+    #include <tiffio.h>
+
+.. c:function:: void *TIFFGetClientInfo(TIFF* tif, const char *name)
+
+.. c:function:: void TIFFSetClientInfo(TIFF* tif, void *data, const char *name)
+
+Description
+-----------
+
+.. TODO: Check explanation of clientinfo linked list intention and usage.
+
+The *clientinfo* linked list provides a method to hand over user defined
+data from one routine to another via the internal ``tif`` storage of the
+``libtiff`` library.
+
+:c:func:`TIFFGetClientInfo` returns a pointer to the data of the named entry
+in the clientinfo-list. If the *name* is not found ``NULL`` is returned.
+
+:c:func:`TIFFSetClientInfo` adds or replaces an entry in the clientinfo-list
+with the *name* and the pointer to the *data* provided by the caller.
+
+Diagnostics
+-----------
+
+None.
+
+See also
+--------
+
+:doc:`libtiff` (3tiff),
diff --git a/doc/functions/TIFFClose.rst b/doc/functions/TIFFClose.rst
index 1eb523a4..df8f0834 100644
--- a/doc/functions/TIFFClose.rst
+++ b/doc/functions/TIFFClose.rst
@@ -10,9 +10,10 @@ Synopsis
 
     #include <tiffio.h>
 
-
 .. c:function:: void TIFFClose(TIFF* tif)
 
+.. c:function:: void TIFFCleanup(TIFF* tif)
+
 Description
 -----------
 
@@ -21,6 +22,11 @@ Description
 the contents of the current directory (if modified); and all resources
 are reclaimed.
 
+:c:func:`TIFFCleanup` is an auxiliary function to free the TIFF structure.
+The given structure will be completely freed, so you should save opened file
+handle and pointer to the close procedure in external variables before
+calling :c:func:`TIFFCleanup`, if you will need these ones to close the file.
+
 Diagnostics
 -----------
 
diff --git a/doc/functions/TIFFCreateDirectory.rst b/doc/functions/TIFFCreateDirectory.rst
new file mode 100644
index 00000000..7ab16b73
--- /dev/null
+++ b/doc/functions/TIFFCreateDirectory.rst
@@ -0,0 +1,75 @@
+TIFFCreateDirectory
+===================
+
+Synopsis
+--------
+
+.. highlight:: c
+
+::
+
+    #include <tiffio.h>
+
+.. c:function:: int TIFFCreateDirectory(TIFF* tif)
+
+.. c:function:: int TIFFFreeDirectory(TIFF* tif)
+
+.. c:function:: int TIFFUnlinkDirectory(TIFF* tif, uint16_t dirn)
+
+Description
+-----------
+
+The following routines create or release a directory.
+
+:c:func:`TIFFCreateDirectory` setup for a directory in a open TIFF file.
+The newly created directory will not exist on the file till
+:c:func:`TIFFWriteDirectory`, :c:func:`TIFFCheckpointDirectory`,
+:c:func:`TIFFFlush` or :c:func:`TIFFClose` is called.
+:c:func:`TIFFWriteDirectory` also creates a new directory,
+frees the ``*tif`` structure and sets up a new one.
+
+:c:func:`TIFFFreeDirectory` releases allocated storage associated with a
+directory, especially custom-fields.
+However, the main part of the directory is not touched. Routine
+:c:func:`TIFFCleanup` calls :c:func:`TIFFFreeDirectory` to release
+the directory part of the `tif` structure.
+
+:c:func:`TIFFUnlinkDirectory` unlink the specified directory from the
+directory chain.
+
+Directory query functions :c:func:`TIFFCurrentDirectory`,
+:c:func:`TIFFCurrentDirOffset`, :c:func:`TIFFLastDirectory` and
+:c:func:`TIFFNumberOfDirectories` retrieve information about directories
+in an open TIFF file. Be aware that until a directory is
+not written to file AND read back, the query functions won't retrieve
+the correct information!
+
+Notes
+-----
+
+Be aware:
+
+- that until a directory is not written to file AND read back, the
+  query functions won't retrieve the correct information!
+- that the newly created directory will not exist on the file till
+  :c:func:`TIFFWriteDirectory`, :c:func:`TIFFCheckpointDirectory`,
+  :c:func:`TIFFFlush` or :c:func:`TIFFClose` has been called.
+- that :c:func:`TIFFCreateDirectory` and :c:func:`TIFFWriteDirectory`
+  create a new directory, free the ``*tif`` structure and set up a new one.
+- that unlike :c:func:`TIFFWriteDirectory`, :c:func:`TIFFCheckpointDirectory`
+  does not free up the directory data structures in memory.
+
+Diagnostics
+-----------
+
+All error messages are directed to the :c:func:`TIFFError` routine.
+Likewise, warning messages are directed to the :c:func:`TIFFWarning` routine.
+
+See also
+--------
+
+:doc:`libtiff` (3tiff),
+:doc:`TIFFCustomDirectory` (3tiff),
+:doc:`TIFFquery` (3tiff),
+:doc:`TIFFSetDirectory` (3tiff),
+:doc:`TIFFWriteDirectory` (3tiff)
diff --git a/doc/functions/TIFFCustomDirectory.rst b/doc/functions/TIFFCustomDirectory.rst
new file mode 100644
index 00000000..d91517e5
--- /dev/null
+++ b/doc/functions/TIFFCustomDirectory.rst
@@ -0,0 +1,203 @@
+TIFFCustomDirectory
+===================
+
+Synopsis
+--------
+
+.. highlight:: c
+
+::
+
+    #include <tiffio.h>
+
+.. c:function:: int TIFFCreateCustomDirectory(TIFF* tif, const TIFFFieldArray* infoarray)
+
+.. c:function:: int TIFFCreateEXIFDirectory(TIFF* tif)
+
+.. c:function:: int TIFFCreateGPSDirectory(TIFF* tif)
+
+.. c:function:: int TIFFWriteCustomDirectory(TIFF* tif,  uint64 *pdiroff)
+
+.. c:function:: int TIFFReadCustomDirectory(TIFF* tif, toff_t diroff, const TIFFFieldArray* infoarray)
+
+.. c:function:: int TIFFReadEXIFDirectory(TIFF* tif, toff_t diroff)
+
+.. c:function:: int TIFFReadGPSDirectory(TIFF* tif, toff_t diroff)
+
+.. c:function:: const TIFFFieldArray* _TIFFGetExifFields(void)
+
+.. c:function:: const TIFFFieldArray* _TIFFGetGpsFields(void)
+
+Description
+-----------
+
+The following routines create a custom directory and retrieve information
+about directories in an open TIFF file.
+
+:c:func:`TIFFCreateCustomDirectory`, :c:func:`TIFFCreateEXIFDirectory`,
+:c:func:`TIFFCreateGPSDirectory` will setup a custom directory or one
+of the predefined EXIF or GPS directories and set the context of the
+TIFF-handle ``tif`` to that custom directory for functions
+like :c:func:`TIFFSetField`.
+
+:c:func:`TIFFWriteCustomDirectory` will write the contents of the
+current custom directory to the file and return the offset to that
+directory in :c:var:`pdiroff`. That offset has to be written to the main-IFD:
+
+.. highlight:: c
+
+::
+
+         /* Go back to the first directory, and add the EXIFIFD pointer. */
+        TIFFSetDirectory(tif, 0);
+        TIFFSetField(tif, TIFFTAG_EXIFIFD, pdiroff);
+
+
+:c:func:`TIFFReadCustomDirectory` will read the custom directory from the
+arbitrary offset into the :c:var:`infoarray` and sets the context of the
+TIFF-handle :c:var:`tif` to that custom directory for functions like
+:c:func:`TIFFReadField`. The :c:type:`TIFFFieldArray` :c:var:`infoarray`
+has to be according the layout of the custom directory. For the predefined
+EXIF and GPS directories, the relevant :c:type:`TIFFFieldArray` definitions
+are hidden within the functions :c:func:`TIFFReadEXIFDirectory` and
+:c:func:`TIFFReadGPSDirectory` The code is very similar to :c:func:`TIFFReadDirectory`.
+The offset to the custom directory diroff has to be read from the
+relative TIFF tag first.
+
+:c:func:`_TIFFGetExifFields` and :c:func:`_TIFFGetGpsFields`  will
+return a pointer to the ``libtiff`` internal definition list of the
+EXIF and GPS tags, respectively.
+
+Notes
+-----
+
+Be aware
+
+- that until a directory is not written to file AND read back, the query
+  functions won't retrieve the correct information!
+- that the newly created directory will not exist on the file till
+  :c:func:`TIFFWriteDirectory`, :c:func:`TIFFCheckpointDirectory`,
+  :c:func:`TIFFFlush` or :c:func:`TIFFClose` has been called.
+- that :c:func:`TIFFCreateDirectory` and :c:func:`TIFFWriteDirectory`
+  create a new directory, free the ``*tif`` structure and set up a new one.
+- that unlike :c:func:`TIFFWriteDirectory`, :c:func:`TIFFCheckpointDirectory`
+  does not free up the directory data structures in memory.
+
+Unfortunately to create or read custom directories with predefined fields
+it is necessary to include the private tif_dir.h. However, for EXIF and
+GPS directories, which have a predefined schema within ``libtiff``, this
+is not necessary. There are some test programmes that briefly demonstrate
+the creation and reading of EXIF, GPS and custom directories.
+See test/custom_dir.c and test/custom_dir_EXIF_231.c
+
+Hints and detailed instructions
+-------------------------------
+
+Writing TIFF files with more than one directory (IFD) is not easy because
+some side effects need to be known.
+
+The main point here is that there can only be one ``tif`` structure in
+the main memory for a file, which can only hold the tags of one directory
+at a time. It is useless to work with two different tiffOut1, tiffOut2
+pointers, because there is only ONE TIFF object (TIFF directory) within
+the ``libtiff``. If you want to address a second directory in the file,
+the tags of the current directory must first be saved in the file,
+otherwise they will be lost (overwritten or mixed). Then the ``tif``
+structure in the main memory must be tidied up, otherwise the old tags
+will beincluded in the new directory.
+This can be done either by creating a new, empty ``tif`` structure or by
+reading in an directory previously saved in the file.
+
+A sequence to handle a second (or third) TIFF directory - in this case
+the GPS IFD - is as follows:
+
+1) Create TIFF file
+2) Complete the "normal" metadata
+3) Set the tag for the custom directory with a “dummy” value in order to
+   get the tag reserved. The final value will be inserted lateron. This
+   prevents the main directory from being written to the file again at an
+   additional area, leaving the first memory area unused:
+
+.. highlight:: c
+
+::
+
+    TIFFSetField(tiffOut, TIFFTAG_GPSIFD, dir_offset);
+
+4) Save current TIFF-directory to file. Otherwise, it will be lost.
+   Remember also the number of the current directory:
+
+.. highlight:: c
+
+::
+
+    TIFFWriteDirectory(tiffOut);
+    dirNum = TIFFCurrentDirectory(tiffOut);
+
+5) Create the second TIFF-directory (e.g. custom directory) and set its
+   fields. The TIFFFieldArray infoarray has to be specified beforehand
+   somewhere in your private include files.
+   An example is given for the EXIF directory in tif_dirinfo.c
+
+.. highlight:: c
+
+::
+
+    TIFFCreateCustomDirectory(tiffOut, infoarray);        /* for a real custom directory */
+    /* or alternatively, use GPS or EXIF with pre-defined TIFFFieldArray IFD field structure */
+    TIFFCreateGPSDirectory(tiffOut);
+    TIFFSetField(tiffOut, GPSTAG_VERSIONID, gpsVersion);  /* set fields of the custom directory */
+
+Be aware that every :c:func:`TIFFCreateDirectory` or :c:func:`TIFFWriteDirectory`
+apparently frees the ``*tif`` structure and sets up a new one!
+
+6) Write custom directory to file. The offset to that directory in the file
+   is returned in :c:var:`dir_offset`.
+
+.. highlight:: c
+
+::
+
+    TIFFWriteCustomDirectory(tiffOut, &dir_offset);
+
+7) Reload the first directory (i.e. the original TIFF directory).
+   Apparently, this reads the data back from file.
+
+.. highlight:: c
+
+::
+
+    TIFFSetDirectory(tiffOut, dirNum);
+
+8) Set the correct offset value of the custom directory IFD tag and save
+   that changes to file.
+
+.. highlight:: c
+
+::
+
+    TIFFSetField(tiffOut, TIFFTAG_GPSIFD, dir_offset);
+    TIFFWriteDirectory(tiffOut);
+
+RETURN VALUES
+-------------
+
+1 is returned when the contents are successfully written to the file.
+Otherwise, 0 is returned if an error was encountered when writing the
+directory contents.
+
+Diagnostics
+-----------
+
+All error messages are directed to the :c:func:`TIFFError` routine.
+Likewise, warning messages are directed to the :c:func:`TIFFWarning` routine.
+
+See also
+--------
+
+:doc:`libtiff` (3tiff),
+:doc:`TIFFCreateDirectory` (3tiff),
+:doc:`TIFFquery` (3tiff),
+:doc:`TIFFSetDirectory` (3tiff),
+:doc:`TIFFWriteDirectory` (3tiff)
+
diff --git a/doc/functions/TIFFCustomTagList.rst b/doc/functions/TIFFCustomTagList.rst
new file mode 100644
index 00000000..4b18c7b0
--- /dev/null
+++ b/doc/functions/TIFFCustomTagList.rst
@@ -0,0 +1,47 @@
+TIFFCustomTagList
+=================
+
+Synopsis
+--------
+
+.. highlight:: c
+
+::
+
+    #include <tiffio.h>
+
+.. c:function:: int TIFFGetTagListCount(TIFF* tif)
+
+.. c:function:: uint32_t TIFFGetTagListEntry(TIFF* tif, int tag_index)
+
+Description
+-----------
+
+:c:func:`TIFFGetTagListCount` returns the number of entries in the
+custom tag list.
+
+:c:func:`TIFFGetTagListEntry` returns the tag number of the (n.th - 1)
+entry within the custom tag list.
+If the :c:var:`tag_index` is larger or equal to the number of entries
+in the tag list 0xFFFFFFFF `(=(uint32_t(-1))` is returned.
+
+Note
+----
+
+The known tags to ``libtiff`` are define as 'named' tags and a lot of them
+as *custom* tags. The custom tag definitions are handled in an internal
+custom tag list. This list can also be extended by adding tag definitions
+to that list, so that ``libtiff`` is aware of those tags.
+See :ref:`Define_Application_Tags`
+
+Diagnostics
+-----------
+
+none
+
+See also
+--------
+
+:doc:`libtiff` (3tiff),
+:doc:`TIFFOpen`  (3tiff),
+:doc:`TIFFError` (3tiff)
diff --git a/doc/functions/TIFFDataWidth.rst b/doc/functions/TIFFDataWidth.rst
index d60f3af7..8adaef6b 100644
--- a/doc/functions/TIFFDataWidth.rst
+++ b/doc/functions/TIFFDataWidth.rst
@@ -15,7 +15,7 @@ Synopsis
 Description
 -----------
 
-:c:func:`TIFFDataWidth` returns the size of *type* in bytes.
+:c:func:`TIFFDataWidth` returns the size of *type* within TIFF file in bytes.
 Currently following data types are supported:
 
 * :c:macro:`TIFF_BYTE`
@@ -31,12 +31,15 @@ Currently following data types are supported:
 * :c:macro:`TIFF_RATIONAL`
 * :c:macro:`TIFF_SRATIONAL`
 * :c:macro:`TIFF_DOUBLE`
+* :c:macro:`TIFF_LONG8`
+* :c:macro:`TIFF_SLONG8`
+* :c:macro:`TIFF_IFD8`
 
 Return values
 -------------
 
 :c:func:`TIFFDataWidth` returns a number of bytes occupied by the item
-of given type. 0 returned when unknown data type supplied.
+of given type within the TIFF file. 0 returned when unknown data type supplied.
 
 See also
 --------
diff --git a/doc/functions/TIFFDeferStrileArrayWriting.rst b/doc/functions/TIFFDeferStrileArrayWriting.rst
new file mod

(Patch may be truncated, please check the link at the top of this post.)