libtiff: manpage: fix28, fix440, update TIFFOpen and SubIFD

From eee54b38ec37b723fdcf904035cbd3d692ffa308 Mon Sep 17 00:00:00 2001
From: Su Laus <[EMAIL REDACTED]>
Date: Sun, 20 Nov 2022 19:39:22 +0000
Subject: [PATCH] manpage: fix28, fix440, update TIFFOpen and SubIFD

 doc/functions/TIFFClose.rst           |  3 ++-
 doc/functions/TIFFCreateDirectory.rst |  4 ++++
 doc/functions/TIFFCustomDirectory.rst |  4 ++++
 doc/functions/TIFFGetField.rst        |  2 +-
 doc/functions/TIFFOpen.rst            | 11 ++++++++++-
 doc/functions/TIFFSetDirectory.rst    | 16 ++++++++++++++++
 doc/functions/TIFFquery.rst           |  6 ++++--
 doc/tools/tiffcrop.rst                |  2 +-
 8 files changed, 42 insertions(+), 6 deletions(-)

diff --git a/doc/functions/TIFFClose.rst b/doc/functions/TIFFClose.rst
index df8f0834..9e84b9eb 100644
--- a/doc/functions/TIFFClose.rst
+++ b/doc/functions/TIFFClose.rst
@@ -20,7 +20,8 @@ Description
 :c:func:`TIFFClose` closes a file that was previously opened with
 :c:func:`TIFFOpen`.  Any buffered data are flushed to the file, including
 the contents of the current directory (if modified); and all resources
-are reclaimed.
+are reclaimed. :c:func:`TIFFClose` calls :c:func:`TIFFCleanup` and then
+the associated function to close the file handle.
 :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
diff --git a/doc/functions/TIFFCreateDirectory.rst b/doc/functions/TIFFCreateDirectory.rst
index 7ab16b73..5a427656 100644
--- a/doc/functions/TIFFCreateDirectory.rst
+++ b/doc/functions/TIFFCreateDirectory.rst
@@ -36,6 +36,10 @@ the directory part of the `tif` structure.
 :c:func:`TIFFUnlinkDirectory` unlink the specified directory from the
 directory chain.
+The parameter *dirn* specifies the subfile/directory
+as an integer number, with the first directory numbered one (1).
+This is different to :c:func:`TIFFSetDirectory` or :c:func:`TIFFCurrentDirectory` where the first
+directory starts with zero (0).
 Directory query functions :c:func:`TIFFCurrentDirectory`,
 :c:func:`TIFFCurrentDirOffset`, :c:func:`TIFFLastDirectory` and
diff --git a/doc/functions/TIFFCustomDirectory.rst b/doc/functions/TIFFCustomDirectory.rst
index d91517e5..d26679d2 100644
--- a/doc/functions/TIFFCustomDirectory.rst
+++ b/doc/functions/TIFFCustomDirectory.rst
@@ -82,6 +82,10 @@ Be aware
   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.
+- that LibTiff does not support custom directory chains
+  (NextIFD pointing to another IFD).
+  NextIFD of custom directories is always set to zero
+  and should be zero when reading.
 Unfortunately to create or read custom directories with predefined fields
 it is necessary to include the private tif_dir.h. However, for EXIF and
diff --git a/doc/functions/TIFFGetField.rst b/doc/functions/TIFFGetField.rst
index 59bcb970..b62c7892 100644
--- a/doc/functions/TIFFGetField.rst
+++ b/doc/functions/TIFFGetField.rst
@@ -327,7 +327,7 @@ information on the meaning of each tag and their possible values.
     * - :c:macro:`TIFFTAG_STONITS`
       - 1
-      - :c:expr:`const double**`
+      - :c:expr:`double*`
diff --git a/doc/functions/TIFFOpen.rst b/doc/functions/TIFFOpen.rst
index 91d4ee27..42b93c78 100644
--- a/doc/functions/TIFFOpen.rst
+++ b/doc/functions/TIFFOpen.rst
@@ -52,7 +52,7 @@ overwritten.
 If a file is opened for reading, the first TIFF directory in the file
 is automatically read (also see :c:func:`TIFFSetDirectory` for reading
-directories other than the first).
+directories other than the first). 
 If a file is opened for writing or appending, a default directory
 is automatically created for writing subsequent data.
 This directory has all the default values specified in TIFF Revision 6.0:
@@ -70,12 +70,21 @@ This directory has all the default values specified in TIFF Revision 6.0:
 To alter these values, or to define values for additional fields,
 :c:func:`TIFFSetField` must be used.
+A file can also be opened for reading and writing with *mode* (``r+``).
+In this case, the first TIFF directory in the file is automatically read,
+but calls to :c:func:`TIFFSetField` are put into a fresh directory, which
+will be appended when the file is closed.
 :c:func:`TIFFOpenW` opens a TIFF file with a Unicode filename, for read/writing.
 :c:func:`TIFFFdOpen` is like :c:func:`TIFFOpen` except that it opens a
 TIFF file given an open file descriptor *fd*.
 The file's name and mode must reflect that of the open descriptor.
 The object associated with the file descriptor **must support random access**.
+In order to close a TIFF file opened with :c:func:`TIFFFdOpen`
+first :c:func:`TIFFCleanup` should be called to free the internal
+TIFF structure without closing the file handle and afterwards the
+file should be closed using its file descriptor *fd*.
 :c:func:`TIFFSetFileName` sets the file name in the tif-structure
 and returns the old file name.
diff --git a/doc/functions/TIFFSetDirectory.rst b/doc/functions/TIFFSetDirectory.rst
index 1e8d77a7..cda54939 100644
--- a/doc/functions/TIFFSetDirectory.rst
+++ b/doc/functions/TIFFSetDirectory.rst
@@ -27,6 +27,22 @@ except the directory is specified as a file offset instead of an index;
 this is required for accessing subdirectories linked through a
 ``SubIFD`` tag.
+In the case of several SubIFDs of a main image, there are two possibilities
+that are not even mutually exclusive.
+a. The ``SubIFD`` tag contains an array with all offsets of the SubIFDs.
+b. The ``SubIFDs`` are concatenated with their ``NextIFD`` parameters
+   to a SubIFD chain.
+LibTiff does support SubIFD chains partially. When a ``SubIFD`` tag is
+activated with :c:func:`TIFFSetSubDirectory()`, :c:func:`TIFFReadDirectory()`
+is able to parse through the SubIFD chain. The *tif_curdir* is just
+incremented from its current value and thus gets arbitrary values
+when parsing through SubIFD chains.
+:c:func:`TIFFSetDirectory()` only works with main-IFD chains because
+allways starts with the first main-IFD and thus is able to reset
+the SubIFD reading chain to the main-IFD chain.
 Directory query functions :c:func:`TIFFCurrentDirectory`,
 :c:func:`TIFFCurrentDirOffset`, :c:func:`TIFFLastDirectory` and
 :c:func:`TIFFNumberOfDirectories` retrieve information about directories
diff --git a/doc/functions/TIFFquery.rst b/doc/functions/TIFFquery.rst
index 58b092ad..6a03c626 100644
--- a/doc/functions/TIFFquery.rst
+++ b/doc/functions/TIFFquery.rst
@@ -51,8 +51,10 @@ The following query routines return status information about the directory
 structure of an open TIFF file.
 :c:func:`TIFFCurrentDirectory` returns the index of the current directory
-(directories are numbered starting at 0). This number is suitable for use
-with the :c:func:`TIFFSetDirectory` routine.
+(directories are numbered starting at 0). This number is suitable for
+use with the :c:func:`TIFFSetDirectory` routine.
+A value of 65535 (non-existing directory) is returned if the directory
+has not yet been written to the file after opening it. 
 :c:func:`TIFFCurrentDirOffset` returns the file offset of the current
 directory (instead of an index).
diff --git a/doc/tools/tiffcrop.rst b/doc/tools/tiffcrop.rst
index b5e8e744..d7d89ca1 100644
--- a/doc/tools/tiffcrop.rst
+++ b/doc/tools/tiffcrop.rst
@@ -422,7 +422,7 @@ However, not all option combinations are permitted.
   Note 2: Any of the -X, -Y, -Z and -z options together with other PAGE_MODE_x options
   such as -H, -V, -P, -J or -K are not supported and may cause buffer overflows.