Bug#1122848: Image::ExifTool.3pm: Some remarks and a patch with editorial changes for this man page
Bjarni Ingi Gislason
bjarniig at simnet.is
Sat Dec 13 07:12:47 GMT 2025
Package: libimage-exiftool-perl
Version: 13.36+dfsg-1
Severity: minor
Tags: patch
Dear Maintainer,
>From "/usr/share/doc/debian/bug-reporting.txt.gz":
Don't file bugs upstream
If you file a bug in Debian, don't send a copy to the upstream software
maintainers yourself, as it is possible that the bug exists only in
Debian. If necessary, the maintainer of the package will forward the
bug upstream.
-.-
I do not send reports upstream if I have to get an account there.
The Debian maintainers have one already.
If I get a negative (or no) response from upstream, I send henceforth
bugs to Debian.
-.-
* What led up to the situation?
Checking for defects with a new version
test-[g|n]roff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=0 -ww -z < "man page"
[Use
grep -n -e ' $' -e '\\~$' -e ' \\f.$' -e ' \\"' <file>
to find (most) trailing spaces.]
["test-groff" is a script in the repository for "groff"; is not shipped]
(local copy and "troff" slightly changed by me).
[The fate of "test-nroff" was decided in groff bug #55941.]
* What was the outcome of this action?
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=0 -ww -z ":
troff:<stdin>:193: warning: trailing space in the line
troff:<stdin>:303: warning: trailing space in the line
troff:<stdin>:313: warning: trailing space in the line
troff:<stdin>:347: warning: trailing space in the line
troff:<stdin>:359: warning: trailing space in the line
troff:<stdin>:502: warning: trailing space in the line
troff:<stdin>:563: warning: trailing space in the line
troff:<stdin>:794: warning: trailing space in the line
troff:<stdin>:902: warning: trailing space in the line
troff:<stdin>:907: warning: trailing space in the line
troff:<stdin>:979: warning: trailing space in the line
troff:<stdin>:1049: warning: trailing space in the line
troff:<stdin>:1670: warning: trailing space in the line
troff:<stdin>:2041: warning: trailing space in the line
troff:<stdin>:2183: warning: trailing space in the line
troff:<stdin>:2436: warning: trailing space in the line
troff:<stdin>:2669: warning: trailing space in the line
* What outcome did you expect instead?
No output (no warnings).
-.-
General remarks and further material, if a diff-file exist, are in the
attachments.
-- System Information:
Debian Release: forky/sid
APT prefers testing
APT policy: (500, 'testing')
Architecture: amd64 (x86_64)
Kernel: Linux 6.17.9+deb14-amd64 (SMP w/2 CPU threads; PREEMPT)
Locale: LANG=is_IS.iso88591, LC_CTYPE=is_IS.iso88591 (charmap=ISO-8859-1), LANGUAGE not set
Shell: /bin/sh linked to /usr/bin/dash
Init: sysvinit (via /sbin/init)
Versions of packages libimage-exiftool-perl depends on:
ii perl 5.40.1-7
Versions of packages libimage-exiftool-perl recommends:
ii libarchive-zip-perl 1.68-1
pn libcompress-raw-lzma-perl <none>
pn libio-compress-brotli-perl <none>
ii libunicode-linebreak-perl 0.0.20190101-1+b9
Versions of packages libimage-exiftool-perl suggests:
pn libposix-strptime-perl <none>
-- no debconf information
-------------- next part --------------
Input file is Image::ExifTool.3pm
Output from "mandoc -T lint Image::ExifTool.3pm": (shortened list)
12 STYLE: input text line longer than 80 bytes:
17 STYLE: whitespace at end of input line
3 WARNING: empty block: RS
Find most trailing spaces with:
grep -n -e ' $' -e ' \\f.$' -e ' \\"' <man page>
-.-.
Output from
test-nroff -mandoc -t -ww -z Image::ExifTool.3pm: (shortened list)
17 line(s) with a trailing space
Find most trailing spaces with:
grep -n -e ' $' -e ' \\f.$' -e ' \\"' <man page>
-.-.
Input file is Image::ExifTool.3pm
Show if Pod::Man generated this.
2:.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
Latest version in Debian testing:
This is perl 5, version 40, subversion 1 (v5.40.1) built for x86_64-linux-gnu-thread-multi
(with 48 registered patches, see perl -V for more detail)
-.-.
Remove space characters (whitespace) at the end of lines.
Use "git apply ... --whitespace=fix" to fix extra space issues, or use
global configuration "core.whitespace".
Number of lines affected is
17
-.-.
Change '-' (\-) to '\(en' (en-dash) for a (numeric) range.
GNU gnulib has recently (2023-06-18) updated its
"build_aux/update-copyright" to recognize "\(en" in man pages.
Image::ExifTool.3pm:870:Dump information in hex to dynamic HTML web page. The value may be 0\-3 for
Image::ExifTool.3pm:1984:\& $exifTool\->SetNewValue(FileModifyDate => \*(Aq2000:01:02 03:04:05\-05:00\*(Aq,
Image::ExifTool.3pm:2207:[\-_A\-Za\-z0\-9] converted to hex. Numerical tag ID's are returned in hex if
Image::ExifTool.3pm:2210:non-numerical ID's may or may not have characters other than [\-_A\-Za\-z0\-9]
Image::ExifTool.3pm:2323:insensitive, and any group in families 0\-2 may be used except for EXIF
Image::ExifTool.3pm:2340:insensitive, and any group in families 0\-2 may be used except for EXIF
Image::ExifTool.3pm:2351:0) Group family number (0\-7)
Image::ExifTool.3pm:2789:Copyright 2003\-2025, Phil Harvey
-.-.
Find a repeated word
! 1849 --> to
-.-.
Strings longer than 3/4 of a standard line length (80).
Use "\:" to split the string at the end of an output line, for example a
long URL (web address).
This is a groff extension.
117 \& \-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-
165 \& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
527 \& \-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
1216 by calling \f(CW\*(C`Options(\*(AqUserParam\*(Aq,\*(AqPARAM\*(Aq)\*(C'\fR. Appending a hash tag (\f(CW\*(C`#\*(C'\fR) to
1621 \& $exifTool\->SetNewValue(\*(AqXMP:Flash\*(Aq=>\*(Aq{mode=on,fired=true,return=not}\*(Aq);
2055 \& $exifTool\->SetNewGroups(\*(AqXMP\*(Aq,\*(AqEXIF\*(Aq,\*(AqIPTC\*(Aq);
-.-.
Wrong distance (not two spaces) between sentences in the input file.
Separate the sentences and subordinate clauses; each begins on a new
line. See man-pages(7) ("Conventions for source file layout") and
"info groff" ("Input Conventions").
The best procedure is to always start a new sentence on a new line,
at least, if you are typing on a computer.
Remember coding: Only one command ("sentence") on each (logical) line.
E-mail: Easier to quote exactly the relevant lines.
Generally: Easier to edit the sentence.
Patches: Less unaffected text.
Search for two adjacent words is easier, when they belong to the same line,
and the same phrase.
The amount of space between sentences in the output can then be
controlled with the ".ss" request.
Mark a final abbreviation point as such by suffixing it with "\&".
Some sentences (etc.) do not begin on a new line.
Split (sometimes) lines after a punctuation mark; before a conjunction.
Lines with only one (or two) space(s) between sentences could be split,
so latter sentences begin on a new line.
Use
#!/usr/bin/sh
sed -e '/^\./n' \
-e 's/\([[:alpha:]]\)\. */\1.\n/g' $1
to split lines after a sentence period.
Check result with the difference between the formatted outputs.
See also the attachment "general.bugs"
[List of affected lines removed.]
-.-.
Split lines longer than 80 characters (fill completely
an A4 sized page line on a terminal)
into two or more lines.
Appropriate break points are the end of a sentence and a subordinate
clause; after punctuation marks.
Add "\:" to split the string for the output, "\<newline>" in the source.
[List of affected lines removed.]
Longest line is number 165 with 136 characters
\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
-.-.
Add a zero (0) in front of a decimal fraction that begins with a period
(.)
7:.if t .sp .5v
-.-.
Put a parenthetical sentence, phrase on a separate line,
if not part of a code.
See man-pages(7), item "semantic newline".
[List of affected lines removed.]
-.-.
Use a character "\(->" instead of plain "->" or "\->", if not typeset with
a constant width font.
[Affected lines are removed from the list]
-.-.
Only one space character is after a possible end of sentence
(after a punctuation, that can end a sentence).
[List of affected lines removed.]
-.-.
Add lines to use the CR font for groff instead of CW.
11:.ft CW
-.-.
.\" Define a fallback for the CE font CW
.
.if \n(.g \{\
. ie t .ftr CW CR
. el .ftr CW R
.\}
[List of affected lines removed.]
-.-.
Put a (long) web address on a new output line to reduce the posibility of
splitting the address between two output lines.
Or inhibit hyphenation with "\%" in front of the name.
649:package and <https://exiftool.org/filename.html#codes> for details about
653:<https://exiftool.org/filename.html#codes> for more details. The inverse
767:<https://exiftool.org/geolocation.html> for more details. Default is
780:alternate database is used. See <http://www.geonames.org/export/codes.html#P>
1624:(See <https://exiftool.org/struct.html#Serialize> for a description of the
2673:if an ISO 2022 shift code is encountered. See <http://www.iptc.org/IIM/>
-.-.
Add "\&" after an ellipsis, when it does not end a sentence.
2171:namespaces may be present in some XMP data. Also note that the 'XMP\-xmp...'
2172:group names may appear in the older form 'XMP\-xap...' since these names
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=0 -ww -z ":
troff:<stdin>:193: warning: trailing space in the line
troff:<stdin>:303: warning: trailing space in the line
troff:<stdin>:313: warning: trailing space in the line
troff:<stdin>:347: warning: trailing space in the line
troff:<stdin>:359: warning: trailing space in the line
troff:<stdin>:502: warning: trailing space in the line
troff:<stdin>:563: warning: trailing space in the line
troff:<stdin>:794: warning: trailing space in the line
troff:<stdin>:902: warning: trailing space in the line
troff:<stdin>:907: warning: trailing space in the line
troff:<stdin>:979: warning: trailing space in the line
troff:<stdin>:1049: warning: trailing space in the line
troff:<stdin>:1670: warning: trailing space in the line
troff:<stdin>:2041: warning: trailing space in the line
troff:<stdin>:2183: warning: trailing space in the line
troff:<stdin>:2436: warning: trailing space in the line
troff:<stdin>:2669: warning: trailing space in the line
-.-
Additionally:
Change 'eg.' to 'e.g.\&'.
-.-
Generally:
Split (sometimes) lines after a punctuation mark; before a conjunction.
-------------- next part --------------
--- Image::ExifTool.3pm 2025-12-13 06:27:47.554501940 +0000
+++ Image::ExifTool.3pm.new 2025-12-13 06:59:45.005102361 +0000
@@ -4,11 +4,14 @@
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
-.if t .sp .5v
+.if t .sp 0.5v
.if n .sp
..
.de Vb \" Begin verbatim text
-.ft CW
+.if t \{\
+. ie \\n(.g .ft CR
+. el .ft CW
+.\}
.nf
.ne \\$1
..
@@ -16,6 +19,13 @@
.ft R
.fi
..
+.\" Define a fallback for the CE font CW
+.
+.if \n(.g \{\
+. ie t .ftr CW CR
+. el .ftr CW R
+.\}
+.
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
. ds C` ""
@@ -190,7 +200,7 @@ By default ExifTool looks for a configur
first in your home directory, then in the directory of the application
script, but a different directory may be specified by setting the
EXIFTOOL_HOME environment variable, or a different file may be specified by
-setting the ExifTool \f(CW\*(C`configFile\*(C'\fR variable before using Image::ExifTool.
+setting the ExifTool \f(CW\*(C`configFile\*(C'\fR variable before using Image::ExifTool.
For example:
.PP
.Vb 2
@@ -238,7 +248,7 @@ ExifTool objects usually is not necessar
.PP
Note that ExifTool uses AUTOLOAD to load non-member methods, so any class
using Image::ExifTool as a base class must define an AUTOLOAD which calls
-\&\fBImage::ExifTool::DoAutoLoad()\fR. eg)
+\&\fBImage::ExifTool::DoAutoLoad()\fR. e.g.)
.PP
.Vb 4
\& sub AUTOLOAD
@@ -297,20 +307,20 @@ reference (SCALAR ref). The remaining s
for requested information. All tags are returned if no tags are specified.
.Sp
Tag names are case-insensitive and may be prefixed by optional group names
-separated by colons. A group name may begin with a family number (eg.
+separated by colons. A group name may begin with a family number (e.g.\&
\&'1IPTC:Keywords'), to restrict matches to a specific family. In the tag
name, a '?' matches any single character and a '*' matches zero or more
-characters. Thus 'GROUP:*' represents all tags in a specific group.
+characters. Thus 'GROUP:*' represents all tags in a specific group.
Wildcards may not be used in group names, with the exception that a group
name of '*' may be used to extract all available instances of a tag
-regardless of the "Duplicates" setting (eg. '*:WhiteBalance'). Multiple
-groups may be specified (eg. 'EXIF:Time:*' extracts all EXIF Time tags). And
-finally, a leading '\-' indicates a tag to be excluded (eg. '\-IFD1:*'), or a
+regardless of the "Duplicates" setting (e.g.\& '*:WhiteBalance'). Multiple
+groups may be specified (e.g.\& 'EXIF:Time:*' extracts all EXIF Time tags). And
+finally, a leading '\-' indicates a tag to be excluded (e.g.\& '\-IFD1:*'), or a
trailing '#' causes the ValueConv value to be returned for this tag.
.Sp
Note that keys in the returned information hash and elements of the returned
tag list are not necessarily the same as these tag names because group names
-are removed, the case may be changed, and an instance number may be added.
+are removed, the case may be changed, and an instance number may be added.
For this reason it is best to use either the keys of the returned hash or
the elements of the returned tag list when accessing the tag values.
.Sp
@@ -327,7 +337,7 @@ be either a standard filehandle, or a re
File::RandomAccess object. Note that the file remains
open and must be closed by the caller after "ImageInfo" returns.
.Sp
-[Advanced: To allow a non-rewindable stream (eg. a network socket) to be
+[Advanced: To allow a non-rewindable stream (e.g.\& a network socket) to be
re-read after processing with ExifTool, first wrap the file reference in a
File::RandomAccess object, then pass this object to
"ImageInfo". The File::RandomAccess object will
@@ -344,7 +354,7 @@ excluded. On return, this list is updat
keys for the returned information.
.Sp
There will be 1:1 correspondence between the requested tags and the returned
-tag keys only if the "Duplicates" option is 0 and "Sort" is 'Input'.
+tag keys only if the "Duplicates" option is 0 and "Sort" is 'Input'.
(With "Duplicates" enabled, there may be more entries in the returned list
of tag keys, and with other "Sort" settings the entries may not be in the
same order as requested.) If a requested tag doesn't exist, a tag key is
@@ -356,12 +366,10 @@ resulting in increasingly slower perform
.IP "HASH ref" 4
.IX Item "HASH ref"
Reference to a hash containing the options settings valid for this call
-only. See "Options" documentation below for a list of available options.
+only. See "Options" documentation below for a list of available options.
Options specified as arguments to "ImageInfo" take precedence over
"Options" settings.
.RE
-.RS 4
-.RE
.IP "Return Values:" 4
.IX Item "Return Values:"
"ImageInfo" returns a reference to a hash of tag\-key/value pairs. The tag
@@ -493,13 +501,13 @@ the command-line \fB\-api\fR option.
.IP Binary 4
.IX Item "Binary"
Flag to extract the value data for all binary tags. Tag values representing
-large binary data blocks (eg. ThumbnailImage) are not necessarily extracted
+large binary data blocks (e.g.\& ThumbnailImage) are not necessarily extracted
unless this option is set or the tag is specifically requested by name.
Default is undef.
.IP BlockExtract 4
.IX Item "BlockExtract"
Flag to extract some directories (mentioned in the
-ExifTool tag name documentation) as a block.
+ExifTool tag name documentation) as a block.
Setting this to a value of 2 also prevents parsing the block to extract tags
contained within.
.IP ByteOrder 4
@@ -514,7 +522,7 @@ option takes precedence if both are set.
.IP ByteUnit 4
.IX Item "ByteUnit"
Units for print conversion of FileSize and other byte values. Either 'SI'
-(eg. kB for 1000 bytes) or 'Binary' (eg. KiB for 1024 bytes). Default is
+(e.g.\& kB for 1000 bytes) or 'Binary' (e.g.\& KiB for 1024 bytes). Default is
\&'SI'.
.IP Charset 4
.IX Item "Charset"
@@ -560,7 +568,7 @@ set to undef to pass through EXIF "ASCII
"UTF8" to conform with the MWG recommendation. Default is undef.
.IP CharsetFileName 4
.IX Item "CharsetFileName"
-External character set used for file names passed to ExifTool functions.
+External character set used for file names passed to ExifTool functions.
Default is undef but "UTF8" is assumed in Windows if the file name contains
special characters and is valid UTF8. May also be set to an empty string to
avoid "encoding must be specified" warnings on Windows.
@@ -588,7 +596,7 @@ Internal encoding to assume for QuickTim
encoding. Default is 'MacRoman'.
.IP CharsetRIFF 4
.IX Item "CharsetRIFF"
-Internal encoding to assume for strings in RIFF metadata (eg. AVI and WAV
+Internal encoding to assume for strings in RIFF metadata (e.g.\& AVI and WAV
files). The default value of 0 assumes "Latin" encoding unless otherwise
specified by the RIFF CSET chunk. Set to undef to pass through strings
without recoding. Default is 0.
@@ -627,7 +635,7 @@ Format for printing GPS coordinates. Th
specifiers for degrees, minutes and seconds in that order, however minutes
and seconds may be omitted. If the hemisphere is known, a reference
direction (N, S, E or W) is appended to each printed coordinate, but adding
-a \f(CW\*(C`+\*(C'\fR or \f(CW\*(C`\-\*(C'\fR to the first format specifier (eg. \f(CW\*(C`%+.6f\*(C'\fR or \f(CW\*(C`%\-.6f\*(C'\fR)
+a \f(CW\*(C`+\*(C'\fR or \f(CW\*(C`\-\*(C'\fR to the first format specifier (e.g.\& \f(CW\*(C`%+.6f\*(C'\fR or \f(CW\*(C`%\-.6f\*(C'\fR)
prints a signed coordinate instead (\f(CW\*(C`+\*(C'\fR also adds a leading plus sign to
positive coordinates, while \f(CW\*(C`\-\*(C'\fR does not). For example, the following
table gives the output for the same coordinate using various formats:
@@ -707,7 +715,7 @@ types of metadata. With this option set
end of a JPEG image to check for an AFCP, CanonVRD, FotoStation,
PhotoMechanic, MIE or PreviewImage trailer. This also stops the parsing
after the first comment in GIF images, and at the audio/video data of
-RIFF-format files (AVI, WAV, etc), so any trailing metadata (eg. XMP written
+RIFF-format files (AVI, WAV, etc), so any trailing metadata (e.g.\& XMP written
by some utilities) may be missed. Also disables input buffering for some
types of files to reduce memory usage when reading from a non-seekable
stream, and bypasses CRC validation for speed when writing PNG files. When
@@ -756,8 +764,8 @@ databases are loaded.
Flag to generate geolocation tags based on the GPSLatitude/GPSLongitude or
City/State/Province/Country read from a file. This feature uses an included
database with cities over a population of 2000 from geonames.org. May be set
-to a string of the form "Lat,Lon" (eg. "44.56,\-72.33") or city with optional
-state/province, country and/or country code (eg. "Paris,France") to act as a
+to a string of the form "Lat,Lon" (e.g.\& "44.56,\-72.33") or city with optional
+state/province, country and/or country code (e.g.\& "Paris,France") to act as a
default for files not containing GPS or geolocation information, or include
tag names with leading dollar signs separated by commas to specify the tags
to use for the geolocation input. When "Lat,Lon" is specified, "num=##" may
@@ -791,7 +799,7 @@ ignored. Default is undef.
.IX Item "GeoMaxIntSecs"
Maximum interpolation time in seconds for geotagging. Geotagging is treated
as an extrapolation if the Geotime value lies between two fixes in the same
-track which are separated by a number of seconds greater than this.
+track which are separated by a number of seconds greater than this.
Otherwise, the coordinates are calculated as a linear interpolation between
the nearest fixes on either side of the Geotime value. Set to 0 to disable
interpolation and use the coordinates of the nearest fix instead (provided
@@ -867,7 +875,7 @@ Return hexadecimal instead of decimal fo
with numerical ID's.
.IP HtmlDump 4
.IX Item "HtmlDump"
-Dump information in hex to dynamic HTML web page. The value may be 0\-3 for
+Dump information in hex to dynamic HTML web page. The value may be 0\(en3 for
increasingly larger limits on the maximum block size. Default is 0. Output
goes to the file specified by the TextOut option (\e*STDOUT by default).
.IP HtmlDumpBase 4
@@ -899,17 +907,17 @@ ignore all tags except those specified b
to undef to clear the previous IgnoreTags list. Default is undef.
.IP ImageHashType 4
.IX Item "ImageHashType"
-Sets type of hash algorithm used for the ImageDataHash tag calculation.
+Sets type of hash algorithm used for the ImageDataHash tag calculation.
Supported options are 'MD5', 'SHA256', and 'SHA512'. Default is 'MD5'.
.IP KeepUTCTime 4
.IX Item "KeepUTCTime"
Flag to keep UTC times in Zulu time zone instead of converting to local
-time. Affects only times which are stored as seconds since the UTC epoch.
+time. Affects only times which are stored as seconds since the UTC epoch.
Default is undef.
.IP Lang 4
.IX Item "Lang"
Localized language for exiftool tag descriptions, etc. Available languages
-are given by the Image::ExifTool::Lang module names (eg. 'fr', 'zh_cn'). If
+are given by the Image::ExifTool::Lang module names (e.g.\& 'fr', 'zh_cn'). If
the specified language isn't available, the option is not changed. May be
set to undef to select the built-in default language. Default is 'en'.
.IP LargeFileSupport 4
@@ -940,7 +948,7 @@ reference. Does not affect ValueConv va
.IP ListSplit 4
.IX Item "ListSplit"
Regular expression used to split values of list-type tags into individual
-items when writing. (eg. use ',\e\es*' to split a comma-separated list.)
+items when writing. (e.g.\& use ',\e\es*' to split a comma-separated list.)
Split when writing either PrintConv or ValueConv values. Default is undef.
.IP MakerNotes 4
.IX Item "MakerNotes"
@@ -976,7 +984,7 @@ is undef.
Flag to bypass writing of mandatory EXIF tags. Default is undef.
.IP NoMultiExif 4
.IX Item "NoMultiExif"
-Raise error when attempting to write multi-segment EXIF in a JPEG image.
+Raise error when attempting to write multi-segment EXIF in a JPEG image.
Default is undef.
.IP NoPDFList 4
.IX Item "NoPDFList"
@@ -1046,7 +1054,7 @@ Apple QuickTime Player and Photos.apps w
missing. Default is 1.
.IP QuickTimePad 4
.IX Item "QuickTimePad"
-Flag to preserve the padding of some QuickTime atoms when writing.
+Flag to preserve the padding of some QuickTime atoms when writing.
QuickTime-based Canon CR3 files pad the values of container atoms with null
bytes. This padding is removed by default when the file is rewritten, but
setting this option to 1 adds padding to preserve the original atom size if
@@ -1076,7 +1084,7 @@ List of additional tag and/or group name
extracted unless specifically requested. Value may be a list reference, a
delimited string of names (any delimiter is allowed), or undef to clear the
current RequestTags list. Groups are requested by adding a colon after the
-name (eg. "MacOS:"). Names are converted to lower case as they are added to
+name (e.g.\& "MacOS:"). Names are converted to lower case as they are added to
the list. Default is undef.
.IP SaveBin 4
.IX Item "SaveBin"
@@ -1267,8 +1275,6 @@ and "MacOS XAttr Tags" in Image::ExifToo
Flag to enable automatic conversion for unknown XMP tags with values that
look like rational numbers or dates. Default is 1.
.RE
-.RS 4
-.RE
.IP "Return Values:" 4
.IX Item "Return Values:"
The original value of the last specified parameter.
@@ -1629,9 +1635,9 @@ structure serialization technique.)
.Sp
1) [optional] Tag key or tag name, or undef to clear all new values. The
tag name may be prefixed by one or more family 0, 1 or 2 group names with
-optional leading family numbers, separated by colons (eg. 'EXIF:Artist',
+optional leading family numbers, separated by colons (e.g.\& 'EXIF:Artist',
\&'XMP:Time:*'), which is equivalent to using a Group option argument. Also,
-a '#' may be appended to the tag name (eg. 'EXIF:Orientation#'), with the
+a '#' may be appended to the tag name (e.g.\& 'EXIF:Orientation#'), with the
same effect as setting Type to 'ValueConv'. Wildcards ('*' and '?') may be
used in the tag name to assign or delete multiple tags simultaneously. A
tag name of '*' is special when deleting information, and will delete an
@@ -1645,7 +1651,7 @@ for a complete list of tag names.
a scalar, scalar reference, list reference to set a list of values, or hash
reference for a structure. Integer values may be specified as a hexadecimal
string (with a leading '0x'), and simple rational values may be specified in
-fractional form (eg. '4/10'). Structure tags may be specified either as a
+fractional form (e.g.\& '4/10'). Structure tags may be specified either as a
hash reference or a serialized string (see the last two examples above).
.Sp
3\-N) [optional] SetNewValue option/value pairs (see below).
@@ -1667,7 +1673,7 @@ list-type tags this deletes a specified
tags this may be used to conditionally replace a tag by providing a new
value in a separate call to SetNewValue (see examples above). For
structured tags, the entire structure is deleted/replaced only if all of the
-specified fields match the existing structure. Option values are 0 or 1.
+specified fields match the existing structure. Option values are 0 or 1.
Default is 0.
.IP EditGroup 4
.IX Item "EditGroup"
@@ -1729,8 +1735,6 @@ The type of value being set. Valid valu
Default is PrintConv if the "PrintConv" Option is set, otherwise
ValueConv.
.RE
-.RS 4
-.RE
.IP "Return Values:" 4
.IX Item "Return Values:"
In scalar context, returns the number of tags set and error messages are
@@ -1826,27 +1830,27 @@ in a specified file.
2\-N) [optional] List of tag names to set or options hash references. All
writable tags are set if none are specified. The tag names are not case
sensitive, and may be prefixed by one or more family 0, 1, 2 or 7 group
-names with optional leading family numbers, separated by colons (eg.
-\&'exif:iso'). A leading '\-' indicates tags to be excluded (eg. '\-comment'),
+names with optional leading family numbers, separated by colons (e.g.\&
+\&'exif:iso'). A leading '\-' indicates tags to be excluded (e.g.\& '\-comment'),
or a trailing '#' causes the ValueConv value to be copied (same as setting
the Type option to 'ValueConv' for this tag only). A leading '+' sets the
Replace option to 0 on a per-tag basis (see Options below). Wildcards ('*'
and '?') may be used in the tag name. A tag name of '*' is commonly used
-when a group is specified to copy all tags in the group (eg. 'XMP:*').
+when a group is specified to copy all tags in the group (e.g.\& 'XMP:*').
.Sp
A special feature allows tag names of the form 'DSTTAG<SRCTAG' (or
\&'SRCTAG>DSTTAG') to be specified to copy information to a tag with a
different name or a specified group. Both 'SRCTAG' and 'DSTTAG' may contain
-wildcards and/or be prefixed by a group name (eg.
+wildcards and/or be prefixed by a group name (e.g.\&
\&'fileModifyDate<modifyDate' or 'xmp:*<*'), and/or suffixed by a '#'
to disable print conversion. Copied tags may also be added or deleted from
a list with arguments of the form 'DSTTAG+<SRCTAG' or
\&'DSTTAG\-<SRCTAG'. Tags are evaluated in order, so exclusions apply only
to tags included earlier in the list. An extension of this feature allows
the tag value to be set from a string containing tag names with leading '$'
-symbols (eg. 'Comment<the file is \f(CW$filename\fR'). Braces '{}' may be used
+symbols (e.g.\& 'Comment<the file is \f(CW$filename\fR'). Braces '{}' may be used
around a tag name to separate it from subsequent text, and a '$$' is used to
-to represent a '$' symbol. The behaviour for missing tags in expressions is
+represent a '$' symbol. The behaviour for missing tags in expressions is
defined by the "MissingTagValue" option. The tag value may be modified
via changes to the default input variable ($_) in a Perl expression placed
inside the braces and after a semicolon following the tag name (see the last
@@ -1959,7 +1963,7 @@ None.
.IX Subsection "SetAlternateFile"
Specify alternate file from which to read metadata. Tags from the alternate
file are available after "ExtractInfo" is called or during a call to
-"SetNewValuesFromFile" by using a family 8 group name (eg. 'File1' in the
+"SetNewValuesFromFile" by using a family 8 group name (e.g.\& 'File1' in the
example below).
.PP
.Vb 1
@@ -1969,7 +1973,7 @@ example below).
.IX Item "Inputs:"
0) ExifTool object reference
.Sp
-1) Family 8 group name, case insensitive (eg. 'File1', 'File2'...)
+1) Family 8 group name, case insensitive (e.g.\& 'File1', 'File2'...)
.Sp
2) Name of alternate input file, or undef to reset
.IP "Return Values:" 4
@@ -1981,7 +1985,7 @@ Write the filesystem modification or cre
FileModifyDate or FileCreateDate tag.
.PP
.Vb 3
-\& $exifTool\->SetNewValue(FileModifyDate => \*(Aq2000:01:02 03:04:05\-05:00\*(Aq,
+\& $exifTool\->SetNewValue(FileModifyDate => \*(Aq2000:01:02 03:04:05\(en05:00\*(Aq,
\& Protected => 1);
\& $result = $exifTool\->SetFileModifyDate($file);
.Ve
@@ -2038,7 +2042,7 @@ the old and new names instead of changin
file or creating the link.
.IP Notes: 4
.IX Item "Notes:"
-Will not overwrite existing files. New directories are created as necessary.
+Will not overwrite existing files. New directories are created as necessary.
If the file is successfully renamed, the new file name may be accessed via
\&\f(CW$$exifTool{NewName}\fR.
.SS SetNewGroups
@@ -2082,7 +2086,7 @@ Get the ID for the specified tag. The I
information, the property name in XMP information, or the data offset in a
binary data block. For some tags, such as Composite tags where there is no
ID, an empty string is returned. In list context, also returns a language
-code for the tag if available and different from the default language (eg.
+code for the tag if available and different from the default language (e.g.\&
with alternate language entries for XMP "lang-alt" tags).
.PP
.Vb 2
@@ -2117,16 +2121,16 @@ A description for the specified tag.
Get group name(s) for a specified tag.
.PP
.Vb 2
-\& # return family 0 group name (eg. \*(AqEXIF\*(Aq);
+\& # return family 0 group name (e.g.\& \*(AqEXIF\*(Aq);
\& $group = $exifTool\->GetGroup($tag, 0);
\&
-\& # return all groups (eg. qw{EXIF IFD0 Author Main})
+\& # return all groups (e.g.\& qw{EXIF IFD0 Author Main})
\& @groups = $exifTool\->GetGroup($tag);
\&
-\& # return groups as a string (eg. \*(AqMain:IFD0:Author\*(Aq)
+\& # return groups as a string (e.g.\& \*(AqMain:IFD0:Author\*(Aq)
\& $group = $exifTool\->GetGroup($tag, \*(Aq:3:1:2\*(Aq);
\&
-\& # return groups as a simplified string (eg. \*(AqIFD0:Author\*(Aq)
+\& # return groups as a simplified string (e.g.\& \*(AqIFD0:Author\*(Aq)
\& $group = $exifTool\->GetGroup($tag, \*(Aq3:1:2\*(Aq);
.Ve
.IP Inputs: 4
@@ -2149,15 +2153,15 @@ identical group names unless the family
The group family numbers are currently available:
.Sp
.Vb 9
-\& 0) Information Type (eg. EXIF, XMP, IPTC)
-\& 1) Specific Location (eg. IFD0, XMP\-dc)
-\& 2) Category (eg. Author, Time)
-\& 3) Document Number (eg. Main, Doc1, Doc3\-2)
-\& 4) Instance Number (eg. Copy1, Copy2, Copy3...)
-\& 5) Metadata Path (eg. JPEG\-APP1\-IFD0\-ExifIFD)
-\& 6) EXIF/TIFF Format (eg. int8u, int32u, undef, string)
-\& 7) Tag ID (eg. ID\-271, ID\-rights, ID\-a9aut)
-\& 8) Alternate File Number (eg. File1, File2, File3...)
+\& 0) Information Type (e.g.\& EXIF, XMP, IPTC)
+\& 1) Specific Location (e.g.\& IFD0, XMP\-dc)
+\& 2) Category (e.g.\& Author, Time)
+\& 3) Document Number (e.g.\& Main, Doc1, Doc3\-2)
+\& 4) Instance Number (e.g.\& Copy1, Copy2, Copy3...)
+\& 5) Metadata Path (e.g.\& JPEG\-APP1\-IFD0\-ExifIFD)
+\& 6) EXIF/TIFF Format (e.g.\& int8u, int32u, undef, string)
+\& 7) Tag ID (e.g.\& ID\-271, ID\-rights, ID\-a9aut)
+\& 8) Alternate File Number (e.g.\& File1, File2, File3...)
.Ve
.Sp
Families 0 and 1 are based on the file structure, and are similar except
@@ -2168,8 +2172,8 @@ Directory), the MakerNotes group is divi
manufacturer, and the XMP group is separated based on the XMP namespace
prefix. Note that only common XMP namespaces are listed in the
GetAllGroups documentation, but additional
-namespaces may be present in some XMP data. Also note that the 'XMP\-xmp...'
-group names may appear in the older form 'XMP\-xap...' since these names
+namespaces may be present in some XMP data. Also note that the 'XMP\-xmp...\&'
+group names may appear in the older form 'XMP\-xap...\&' since these names
evolved as the XMP standard was developed. The ICC_Profile group is broken
down to give information about the specific ICC_Profile tag from which
multiple values were extracted. As well, information extracted from the
@@ -2180,9 +2184,9 @@ information refers.
.Sp
Family 3 gives the document number for tags extracted from embedded
documents, or 'Main' for tags from the main document. (See the
-"ExtractEmbedded" option for extracting tags from embedded documents.)
+"ExtractEmbedded" option for extracting tags from embedded documents.)
Nested sub-documents (if they exist) are indicated by numbers separated with
-dashes in the group name, to an arbitrary depth. (eg. 'Doc2\-3\-1' is the 1st
+dashes in the group name, to an arbitrary depth. (e.g.\& 'Doc2\-3\-1' is the 1st
sub-sub-document of the 3rd sub-document of the 2nd embedded document of the
main file.) Document numbers are also used to differentiate samples for
timed metadata in videos.
@@ -2204,10 +2208,10 @@ used when extracting.
.Sp
Family 7 is used for tag ID's. The group names are the actual tag ID's,
with a leading "ID\-" string. Non-numerical ID's have characters other than
-[\-_A\-Za\-z0\-9] converted to hex. Numerical tag ID's are returned in hex if
+[\-_A\(enZa\(enz0\(en9] converted to hex. Numerical tag ID's are returned in hex if
the "HexTagIDs" option is set, otherwise decimal is used. When specifying
a family 7 group name, numerical ID's may be in hex or decimal, and
-non-numerical ID's may or may not have characters other than [\-_A\-Za\-z0\-9]
+non-numerical ID's may or may not have characters other than [\-_A\(enZa\(enz0\(en9]
converted to hex. Note that unlike other group names, the tag ID's of
family 7 group names are case sensitive (but the leading "ID\-" is not).
.Sp
@@ -2320,7 +2324,7 @@ Get list of all available tag names.
.IX Item "Return Values:"
A list of all available tags in alphabetical order, or all tags in a
specified group or intersection of groups. The group name is case
-insensitive, and any group in families 0\-2 may be used except for EXIF
+insensitive, and any group in families 0\(en2 may be used except for EXIF
family 1 groups (ie. the specific IFD).
.SS "GetWritableTags [static]"
.IX Subsection "GetWritableTags [static]"
@@ -2337,7 +2341,7 @@ Get list of all writable tag names.
A list of all writable tags in alphabetical order. These are the tags for
which values may be set through "SetNewValue". If a group name is given,
returns only writable tags in specified group(s). The group name is case
-insensitive, and any group in families 0\-2 may be used except for EXIF
+insensitive, and any group in families 0\(en2 may be used except for EXIF
family 1 groups (ie. the specific IFD).
.SS "GetAllGroups [static]"
.IX Subsection "GetAllGroups [static]"
@@ -2348,7 +2352,7 @@ Get list of all group names in specified
.Ve
.IP Inputs: 4
.IX Item "Inputs:"
-0) Group family number (0\-7)
+0) Group family number (0\(en7)
.IP "Return Values:" 4
.IX Item "Return Values:"
A list of all groups in the specified family in alphabetical order.
@@ -2425,7 +2429,7 @@ Doc#, Main
Copy#
.IP "Family 5 (Metadata Path):" 4
.IX Item "Family 5 (Metadata Path):"
-eg. JPEG\-APP1\-IFD0\-ExifIFD
+e.g.\& JPEG\-APP1\-IFD0\-ExifIFD
.IP "Family 6 (EXIF/TIFF Format):" 4
.IX Item "Family 6 (EXIF/TIFF Format):"
int8u, string, int16u, int32u, rational64u, int8s, undef, int16s, int32s,
@@ -2433,7 +2437,7 @@ rational64s, float, double, ifd, unicode
.IP "Family 7 (Tag ID):" 4
.IX Item "Family 7 (Tag ID):"
ID-xxx (Where xxx is the tag ID. Numerical ID's are returned in hex with a
-leading "0x" if the HexTagIDs option is set, or decimal otherwise.
+leading "0x" if the HexTagIDs option is set, or decimal otherwise.
Characters in non-numerical ID's which are not valid in a group name are
returned as 2 hex digits.)
.IP "Family 8 (Alternate File):" 4
@@ -2470,7 +2474,7 @@ To schedule a group for deletion, call "
\&'EXIF:*' and an undefined tag value.
.Sp
Deleting a family 0 or 1 group will delete the entire corresponding block of
-metadata, but deleting a family 2 group (eg. Audio, Author, Camera, etc.)
+metadata, but deleting a family 2 group (e.g.\& Audio, Author, Camera, etc.)
deletes the individual tags belonging to that category.
.Sp
The 'Trailer' group allows all trailers in JPEG and TIFF-format images to be
@@ -2666,7 +2670,7 @@ of 'UTF8' (or 'ESC % G') then string val
UTF\-8, otherwise Windows Latin1 (cp1252, 'Latin') coding is assumed by
default, but this can be changed with the "CharsetIPTC" option. When
reading, these strings are converted to the character set specified by the
-"Charset" option. When writing, the inverse conversions are performed.
+"Charset" option. When writing, the inverse conversions are performed.
No conversion is done if the internal (IPTC) and external (ExifTool)
character sets are the same. Note that ISO 2022 character set shifting is
not supported. Instead, a warning is issued and the string is not converted
@@ -2769,7 +2773,7 @@ AIFF strings are assumed to be stored in
according to the "Charset" option when reading.
.SS RIFF
.IX Subsection "RIFF"
-The internal encoding of RIFF strings (eg. in AVI and WAV files) is assumed
+The internal encoding of RIFF strings (e.g.\& in AVI and WAV files) is assumed
to be Latin unless otherwise specified by the RIFF CSET chunk or the
"CharsetRIFF" option.
.SS MIE
@@ -2786,7 +2790,7 @@ Vorbis comments are stored as UTF\-8, an
specified by the "Charset" option.
.SH AUTHOR
.IX Header "AUTHOR"
-Copyright 2003\-2025, Phil Harvey
+Copyright 2003\(en2025, Phil Harvey
.PP
This library is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
-------------- next part --------------
Any program (person), that produces man pages, should check the output
for defects by using (both groff and nroff)
[gn]roff -mandoc -t -ww -b -z -K utf8 <man page>
To find trailing space use
grep -n -e ' $' -e ' \\f.$' -e ' \\"' <man page>
The same goes for man pages that are used as an input.
-.-
For a style guide use
mandoc -T lint
-.-
For general input conventions consult the man page "nroff(7)" (item
"Input conventions") or the Texinfo manual about the same item.
-.-
Any "autogenerator" should check its products with the above mentioned
'groff', 'mandoc', and additionally with 'nroff ...'.
It should also check its input files for too long (> 80) lines.
This is just a simple quality control measure.
The "autogenerator" may have to be corrected to get a better man page,
the source file may, and any additional file may.
-.-
Common defects:
Not removing trailing spaces (in in- and output).
The reason for these trailing spaces should be found and eliminated.
"git" has a "tool" to point out whitespace,
see for example "git-apply(1)" and git-config(1)")
-.-
Not beginning each input sentence on a new line.
Line length and patch size should thus be reduced when that has been fixed.
The script "reportbug" uses 'quoted-printable' encoding when a line is
longer than 1024 characters in an 'ascii' file.
See man-pages(7), item "semantic newline".
-.-
The difference between the formatted output of the original
and patched file can be seen with:
nroff -mandoc <file1> > <out1>
nroff -mandoc <file2> > <out2>
diff -d -u <out1> <out2>
and for groff, using
\"printf '%s\n%s\n' '.kern 0' '.ss 12 0' | groff -mandoc -Z - \"
instead of 'nroff -mandoc'
Add the option '-t', if the file contains a table.
Read the output from 'diff -d -u ...' with 'less -R' or similar.
-.-.
If 'man' (man-db) is used to check the manual for warnings,
the following must be set:
The option "-warnings=w"
The environmental variable:
export MAN_KEEP_STDERR=yes (or any non-empty value)
or
(produce only warnings):
export MANROFFOPT="-ww -b -z"
export MAN_KEEP_STDERR=yes (or any non-empty value)
-.-
More information about the pkg-perl-maintainers
mailing list