From fc733c6a26847697351535275c5ef1e9959afc71 Mon Sep 17 00:00:00 2001
From: Su_Laus <[EMAIL REDACTED]>
Date: Sun, 28 May 2023 22:40:04 +0200
Subject: [PATCH] manpages: TiffField functions documentation updated with
return behaviour for not defined tags and determination of write-/read-count
size.
---
doc/functions/TIFFFieldDataType.rst | 6 ++++++
doc/functions/TIFFFieldName.rst | 6 ++++++
doc/functions/TIFFFieldPassCount.rst | 12 +++++++++++-
doc/functions/TIFFFieldQuery.rst | 20 +++++++++++++++-----
doc/functions/TIFFFieldReadCount.rst | 6 ++++++
doc/functions/TIFFFieldTag.rst | 6 ++++++
doc/functions/TIFFFieldWriteCount.rst | 6 ++++++
7 files changed, 56 insertions(+), 6 deletions(-)
diff --git a/doc/functions/TIFFFieldDataType.rst b/doc/functions/TIFFFieldDataType.rst
index a758fcb5..837004e6 100644
--- a/doc/functions/TIFFFieldDataType.rst
+++ b/doc/functions/TIFFFieldDataType.rst
@@ -29,4 +29,10 @@ Return values
See also
--------
+:doc:`TIFFFieldName` (3tiff),
+:doc:`TIFFFieldPassCount` (3tiff),
+:doc:`TIFFFieldQuery` (3tiff),
+:doc:`TIFFFieldReadCount` (3tiff),
+:doc:`TIFFFieldTag` (3tiff),
+:doc:`TIFFFieldWriteCount` (3tiff),
:doc:`libtiff` (3tiff)
diff --git a/doc/functions/TIFFFieldName.rst b/doc/functions/TIFFFieldName.rst
index 85d580ae..67bedf75 100644
--- a/doc/functions/TIFFFieldName.rst
+++ b/doc/functions/TIFFFieldName.rst
@@ -28,4 +28,10 @@ Return values
See also
--------
+:doc:`TIFFFieldDataType` (3tiff),
+:doc:`TIFFFieldPassCount` (3tiff),
+:doc:`TIFFFieldQuery` (3tiff),
+:doc:`TIFFFieldReadCount` (3tiff),
+:doc:`TIFFFieldTag` (3tiff),
+:doc:`TIFFFieldWriteCount` (3tiff),
:doc:`libtiff` (3tiff)
diff --git a/doc/functions/TIFFFieldPassCount.rst b/doc/functions/TIFFFieldPassCount.rst
index 1278e110..a630b99f 100644
--- a/doc/functions/TIFFFieldPassCount.rst
+++ b/doc/functions/TIFFFieldPassCount.rst
@@ -26,10 +26,14 @@ expect a :c:var:`count` value to be passed before the actual data pointer.
When a :c:var:`count` is required, it will be of type :c:type:`uint32_t`
if :c:func:`TIFFFieldReadCount` reports :c:macro:`TIFF_VARIABLE2`,
-and of type :c:type:`uint16_t` otherwise. (This distinction is
+and of type :c:type:`uint16_t` otherwise. Use :c:func:`TIFFFieldWriteCount`
+for :c:func:`TIFFSetField`, respectively. (This distinction is
critical for use of :c:func:`TIFFGetField`, but normally not so for
use of :c:func:`TIFFSetField`.)
+An alternative function for the :c:var:`count` value determination
+is :c:func:`TIFFFieldSetGetCountSize`.
+
Return values
-------------
@@ -39,4 +43,10 @@ or 0 (false).
See also
--------
+:doc:`TIFFFieldDataType` (3tiff),
+:doc:`TIFFFieldName` (3tiff),
+:doc:`TIFFFieldQuery` (3tiff),
+:doc:`TIFFFieldReadCount` (3tiff),
+:doc:`TIFFFieldTag` (3tiff),
+:doc:`TIFFFieldWriteCount` (3tiff),
:doc:`libtiff`
diff --git a/doc/functions/TIFFFieldQuery.rst b/doc/functions/TIFFFieldQuery.rst
index 644299cb..4e7a8188 100644
--- a/doc/functions/TIFFFieldQuery.rst
+++ b/doc/functions/TIFFFieldQuery.rst
@@ -36,8 +36,11 @@ return a pointer to TIFF field information structure `fip` by the tag's
With dt== :c:macro:`TIFF_ANY` the behaviour is the same than for
*TIFFFieldWithTag()*.
+All three functions return :c:var:`NULL`, when the tag is not
+registered within ``libtiff`` (see also :ref:`Tag_Auto_registration` ).
+
.. TODO: Check if ``libtiff`` is able to handle tag definitions with two different
- definitions. From the code point of view, I don't believe that.
+ definitions. From the code point of view, I don't believe that.
Such a `TIFFDataType` dependent search could be useful when the same
tag is defined twice but with different data types, which is true for
@@ -47,11 +50,11 @@ With dt== :c:macro:`TIFF_ANY` the behaviour is the same than for
The following routines return status information about TIFF fields.
- :c:var:`fip` is a field information pointer previously returned by
- `TIFFFindField()`, `TIFFFieldWithTag()`, `TIFFFieldWithName()`.
+:c:var:`fip` is a field information pointer previously returned by
+`TIFFFindField()`, `TIFFFieldWithTag()`, `TIFFFieldWithName()`.
:c:func:`TIFFFieldIsAnonymous` returns true (nonzero) if the field,
-read from file, is unknown to ``libtiff`` and a anonymous field has
+read from file, is unknown to ``libtiff`` and an anonymous field has
been auto-registered. Return is zero "0" if field is known to ``libtiff``.
See :ref:`Tag_Auto_registration` for more information.
@@ -65,7 +68,8 @@ then return "4" or "8", respectively.
:c:func:`TIFFFieldSetGetCountSize` returns size of ``count`` parameter
of :c:func:`TIFFSetField` and :c:func:`TIFFGetField` and also if it is
-required: 0=none, 2= :c:type:`uint16_t`, 4= :c:type:`uint32_t`
+required: 0=none, 2= :c:type:`uint16_t`, 4= :c:type:`uint32_t`.
+See also description of :c:func:`TIFFFieldReadCount`.
Diagnostics
-----------
@@ -75,4 +79,10 @@ None.
See also
--------
+:doc:`TIFFFieldDataType` (3tiff),
+:doc:`TIFFFieldName` (3tiff),
+:doc:`TIFFFieldPassCount` (3tiff),
+:doc:`TIFFFieldReadCount` (3tiff),
+:doc:`TIFFFieldTag` (3tiff),
+:doc:`TIFFFieldWriteCount` (3tiff),
:doc:`libtiff` (3tiff)
diff --git a/doc/functions/TIFFFieldReadCount.rst b/doc/functions/TIFFFieldReadCount.rst
index 90390808..9cd46dd9 100644
--- a/doc/functions/TIFFFieldReadCount.rst
+++ b/doc/functions/TIFFFieldReadCount.rst
@@ -40,4 +40,10 @@ Return values
See also
--------
+:doc:`TIFFFieldDataType` (3tiff),
+:doc:`TIFFFieldName` (3tiff),
+:doc:`TIFFFieldPassCount` (3tiff),
+:doc:`TIFFFieldQuery` (3tiff),
+:doc:`TIFFFieldTag` (3tiff),
+:doc:`TIFFFieldWriteCount` (3tiff),
:doc:`libtiff` (3tiff)
diff --git a/doc/functions/TIFFFieldTag.rst b/doc/functions/TIFFFieldTag.rst
index dbff7460..9d76a702 100644
--- a/doc/functions/TIFFFieldTag.rst
+++ b/doc/functions/TIFFFieldTag.rst
@@ -31,4 +31,10 @@ Return values
See also
--------
+:doc:`TIFFFieldDataType` (3tiff),
+:doc:`TIFFFieldName` (3tiff),
+:doc:`TIFFFieldPassCount` (3tiff),
+:doc:`TIFFFieldQuery` (3tiff),
+:doc:`TIFFFieldReadCount` (3tiff),
+:doc:`TIFFFieldWriteCount` (3tiff),
:doc:`libtiff` (3tiff)
diff --git a/doc/functions/TIFFFieldWriteCount.rst b/doc/functions/TIFFFieldWriteCount.rst
index 1a14e7ba..4459f8f7 100644
--- a/doc/functions/TIFFFieldWriteCount.rst
+++ b/doc/functions/TIFFFieldWriteCount.rst
@@ -45,4 +45,10 @@ Return values
See also
--------
+:doc:`TIFFFieldDataType` (3tiff),
+:doc:`TIFFFieldName` (3tiff),
+:doc:`TIFFFieldPassCount` (3tiff),
+:doc:`TIFFFieldQuery` (3tiff),
+:doc:`TIFFFieldReadCount` (3tiff),
+:doc:`TIFFFieldTag` (3tiff),
:doc:`libtiff` (3tiff)