exiftool_vendored 10.04.0 → 10.23.0

data/bin/Image-ExifTool-10.04/lib/Image/ExifTool/README

@@ -1,981 +0,0 @@
---------------------------------------------------------------------------------
-File:         Image/ExifTool/README
-
-Description:  ExifTool support modules documentation
-
-The ExifTool support modules are loaded by ExifTool to allow processing of
-various meta information formats.
-
-The tables in these files are used as lookups based on the tag ID values.  The
-hash keys are the tag IDs (in decimal or hexadecimal if the ID is numerical as
-with EXIF tables, or the tag name if the ID is ASCII as with XMP tables).  In
-the case of a BinaryData table, the IDs are numerical and specify offsets into
-the binary data block (floating point IDs allow multiple tags for the same
-offset, with the integer part being used for the offset).  The corresponding
-hash value provides information about the tag (explained later).
-
-Twenty-five special keys (TABLE_NAME, SHORT_NAME, PROCESS_PROC, WRITE_PROC,
-CHECK_PROC, GROUPS, FORMAT, FIRST_ENTRY, TAG_PREFIX, PRINT_CONV, WRITABLE,
-TABLE_DESC, NOTES, IS_OFFSET, IS_SUBDIR, EXTRACT_UNKNOWN, NAMESPACE, PREFERRED,
-SRC_TABLE, PRIORITY, WRITE_GROUP, LANG_INFO, VARS, DATAMEMBER and SET_GROUP1)
-are used to provide additional information about a table. The special keys have
-names that are all capitalized to avoid possible conflicts with tag keys.  Below
-is an explanation of the meaning of each special key:
-
-  TABLE_NAME : Name of this table (set by GetTagTable()).
-
-  SHORT_NAME : Table name with leading "Image::ExifTool::" removed.
-
-  PROCESS_PROC : Reference to a function used to process the directory for this
-  table.  If PROCESS_PROC is not given, \&Image::ExifTool::Exif::ProcessExif is
-  assumed (except for QuickTime atoms for which
-  \&Image::ExifTool::QuickTime::ProcessMOV is the default).  If PROCESS_PROC is
-  set to 0, the tags are not added to the lookup. The process proc returns 1 on
-  success or 0 on failure, and takes 3 arguments: 0) reference to the ExifTool
-  object, 1) reference to a directory information hash (with the following
-  entries:), 2) reference to the tag table hash.
-
-    Name        - Tag name for this SubDirectory entry (for verbose messages)
-    Base        - Base offset for pointers from start of file
-    DataPt      - Reference to data block containing directory (may be undef)
-    DataPos     - Position of data block within file (relative to Base)
-    DataLen     - Length of data block in bytes
-    DirStart    - Offset to start of directory from start of data block
-    DirLen      - Length of directory data within block
-    DirName     - Name of this directory
-    OutFile     - Output file or scalar reference
-    Parent      - Name of parent directory
-    RAF         - Reference to File::RandomAccess object if available
-    NewDataPos  - File position of new data (write proc only)
-    Fixup       - Reference to hash of offset fixups (used in EXIF writing only)
-    FixBase     - Flag set to attempt to fix base offsets
-    FixOffsets  - Evaluated for each value pointer to patch maker note offsets
-    LastIFD     - Used by WriteExif() to return offset of last IFD written
-    ImageData   - Used by WriteExif() to avoid buffering large image data blocks
-
-  WRITE_PROC : Reference to a function to write all new tags for this directory.
-  The write proc returns the new directory data or undefined on error.  It takes
-  the same arguments as the process proc above except that the second argument
-  (reference to directory information hash) is optional, and if specified gives
-  information about the source directory for tags to be copied to the output.
-
-  CHECK_PROC : Reference to a function which validates Raw values for writing.
-  The function takes three arguments: 0) ExifTool object reference, 1) tagInfo
-  reference, 2) value reference, and returns undefined (and possibly modifies
-  the input value) if successful, or an error message if there was a format
-  problem.  May set ExifTool CHECK_WARN datamember for success with a warning.
-
-  GROUPS : A hash lookup for the default group names for all entries in this
-  table. If not specified, the Group 0 and 1 names will be set automatically
-  according to the name of the module.
-
-  FORMAT : Specifies the default tag Format, and corresponding pointer increment
-  for entries in a BinaryData table.  Defaults to 'int8u' if not specified.  The
-  possible values of FORMAT are:
-
-    int8s       - Signed 8-bit integer                    (EXIF 'SBYTE')
-    int8u       - Unsigned 8-bit integer                  (EXIF 'BYTE')
-    int16s      - Signed 16-bit integer                   (EXIF 'SSHORT')
-    int16u      - Unsigned 16-bit integer                 (EXIF 'SHORT')
-    int16uRev   - Unsigned 16-bit integer, reversed byte order
-    int32s      - Signed 32-bit integer                   (EXIF 'SLONG')
-    int32u      - Unsigned 32-bit integer                 (EXIF 'LONG')
-    int64s      - Signed 64-bit integer                   (BigTIFF 'SLONG8')
-    int64u      - Unsigned 64-bit integer                 (BigTIFF 'LONG8')
-    rational32s - Rational consisting of 2 int16s values
-    rational32u - Rational consisting of 2 int16u values
-    rational64s - Rational consisting of 2 int32s values  (EXIF 'SRATIONAL')
-    rational64u - Rational consisting of 2 int32u values  (EXIF 'RATIONAL')
-    fixed16s    - Signed 16-bit fixed point value
-    fixed16u    - Unsigned 16-bit fixed point value
-    fixed32s    - Signed 32-bit fixed point value
-    fixed32u    - Unsigned 32-bit fixed point value
-    float       - 32-bit IEEE floating point value        (EXIF 'FLOAT')
-    double      - 64-bit IEEE floating point value        (EXIF 'DOUBLE')
-    extended    - 80-bit extended floating float
-    ifd         - Unsigned 32-bit integer sub-IFD pointer (EXIF 'IFD')
-    ifd64       - Unsigned 64-bit integer sub-IFD pointer (BigTIFF 'IFD8')
-    string      - Series of 8-bit ASCII characters        (EXIF 'ASCII')
-    undef       - Undefined-format binary data            (EXIF 'UNDEFINED')
-    binary      - Binary data (same as 'undef')
-
-  Additionally, the following variable-length Format types may be used in
-  individual tag information hashes of a BinaryData table.  The 'var_' formats
-  cause subsequent tag indices to be incremented according to the size of the
-  data, not including the terminator.  See "Format" below for more details.
-
-    pstring     - Pascal string
-    var_string  - variable-length null-terminated ASCII string
-    var_ustring - variable-length null-terminated UCS-2 string
-    var_pstring - variable-length Pascal string
-    var_pstr32  - variable-length Pascal string /w 32-bit len
-    var_int16u  - variable-length undef data with int6u count
-
-  FIRST_ENTRY : Specifies the index for the first tag entry in a binary table.
-  This value is only used if the Unknown option is set to 2 or higher, and
-  allows the binary data to be scanned for unknown tag entries.
-
-  TAG_PREFIX : Prefix for names of unknown tags.
-
-  PRINT_CONV : Default print conversion for tags where PrintConv isn't
-  specified.  PrintConv may be set to undef for individual tags to disable print
-  conversion when PRINT_CONV is defined for a table.
-
-  WRITABLE : Indicates that all tags in this table are writable.  This is the
-  same as setting the Writable flag for each individual tag in the table, except
-  for SubDirectory tags which are not made Writable.
-
-  TABLE_DESC : Short description for this table.  Plain text only.  Used only
-  for XML tag database output.
-
-  NOTES : Notes to introduce the table in the TagNames documentation.  Pod
-  formatting codes B<> and C<> may be used in this text.
-
-  IS_OFFSET : Reference to list of sorted TagID's representing offsets for
-  writable binary data tables only.  Not used for EXIF tables.
-
-  IS_SUBDIR : BinaryData tables only.  A reference to a list of sorted tag ID's
-  representing subdirectories.  Required for writable subdirectories only.
-
-  EXTRACT_UNKNOWN : Used in PDF tables to specify a directory where all unknown
-  tags should be extracted.  Set to 0 to extract only unknown numbered tags for
-  which the unnumbered tag is known.
-
-  NAMESPACE : Namespace prefix for tags in the XMP table.  If this isn't a
-  standard namespace defined in %Image::ExifTool::XMP::nsURI, then the URI must
-  be defined as well (however, this is not recommended for pre-defined
-  namespaces because then non-standard namespace prefixes won't be recognized).
-  To define the URI, the NAMESPACE value is a reference to a hash where the key
-  is the namespace prefix and and the value is the URI (alternatively, a
-  reference to a 2-element array containing the prefix and URI is also allowed
-  for backward compatibility).  The NAMESAPCE value may be undef for XMP tables
-  where tags have variable namespaces (in this case each tag must have a
-  Namespace entry).
-
-  PREFERRED : Set to true if the tags in this table should always be added when
-  writing information.  Overrides the order specified by SetNewGroups().  When
-  this feature is used, it may also be desireable to specify a preferred group
-  when calling InitWriteDirs() to write these tags; this avoids creating other
-  directories for tags which are already being creating in the preferred group.
-
-  SRC_TABLE : Used internally to store the source table name of a user-defined
-  tag table so the appropriate module can be loaded as required.
-
-  PRIORITY : Default Priority for all tags in this table.
-
-  WRITE_GROUP : Default WriteGroup for all tags in the table.
-
-  LANG_INFO : Code reference to a routine which returns a reference to a
-  language-specific tag information hash.  The routine takes two arguments: a
-  reference to the non-specific tagInfo hash, and the language code. Used only
-  in tables with writable tags which support tag name language extensions (eg.
-  MIE and XMP).
-
-  VARS : Hash used to store additional parameters.  Individual modules may use
-  this to store any parameters they want.  The following additional parameters
-  have been defined, and may be used by any module:
-
-    ID_LABEL      Label to use instead of "Tag ID" for column heading in tag
-                  name documentation.  When this is set, numerical TagID's are
-                  not converted to hexadecimal notation. Unless otherwise set,
-                  an ID_LABEL of "Index" is assumed for tables which use
-                  ProcessBinaryData.
-
-    NO_ID         Avoid printing "Tag ID" column in tag name documentation.
-
-    HEX_ID        Print tag ID in hexadecimal (with 4 hex digits or more).
-
-    NO_LOOKUP     Do not add tags to TagLookup.pm lookup tables.
-
-    CAPTURE       Used by PDF module to name dictionaries to capture when
-                  writing.
-
-    MINOR_ERRORS  [EXIF tables only] Flag to make errors in this IFD minor, or
-                  to downgrade already minor errors to warnings while writing.
-                  (Errors in MakerNote IFD's are already classified as minor.)
-                  Note that for certain types errors, the response is to delete
-                  the entire IFD from the image.
-
-    NUMBERS_LAST  Sort numerical tags after character tags in documentation.
-
-    LONG_TAGS     Suppress "Long tags" warning when generating documentation.
-                  Value is the number of long tag names to expect.
-
-    SORT_PROC     Reference to sort procedure for sorting tag ID's in the
-                  documentation.  Takes two arguments and returns -1, 0 or 1
-                  if the first argument is less than, equal to, or greater than
-                  the second argument.
-
-  DATAMEMBER : BinaryData tables only.  A reference to a list of sorted tag ID's
-  which must be extracted as data members when writing.  Must also list "var_"
-  format tags and tags with Hook so offsets are properly calculated if the table
-  is writable.
-
-  SET_GROUP1 : [EXIF tables only] Flag to set group1 name to the directory name
-  for all tags in the table.
-
-The remaining entries in a tag table are the tag IDs with their associated
-information.  The information may exist in one of three forms:  1) A simple
-scalar which is the name of the tag, 2) A reference to a hash of information
-describing this tag, or 3) a reference to a list of hashes which contain
-Condition expressions allowing the appropriate hash to be selected to suit the
-conditions.  The following is a description of possible hash entries.  All
-entries are optional, except for the tag Name which is required if the tag ID is
-numerical.
-
-  Name          : The tag name.  Tag names need not be unique.  If they aren't
-                  unique, then duplicate tags will hide the values of previous
-                  tags when extracting information unless the Duplicates option
-                  is set or the new tag has lower Priority.  With Duplicates
-                  set, to allow multiple tags with the same name to exist in the
-                  tag information hash, the key of the previous tag is changed
-                  to the form "TagName (N)", where N starts at 1 and increments
-                  for subsequent duplicate tags.  A tag name should start with
-                  an uppercase letter, and contain only the characters in the
-                  set [A-Za-z0-9_-].  If not given, the Name is taken from the
-                  tag ID with the first character changed to upper case.
-
-  Description   : A more readable description of tag name.  If a tag doesn't
-                  specify a Description, then the tag Name is used instead, with
-                  spaces inserted between the words.
-
-  Notes         : Notes for this tag in the HTML TagNames documentation.
-
-  Groups        : Hash lookup for group names for this tag.
-
-  Format        : Only valid for BinaryData, EXIF and IPTC tables. For a Binary
-                  or EXIF table, this gives the format that is used to convert
-                  the binary data, and is one of the FORMAT types specified
-                  above.  If not specified, the Format of an EXIF entry is taken
-                  from the EXIF information, and the Format of a BinaryData
-                  entry is taken from the FORMAT specified for the table (or
-                  int8u if FORMAT is not specified).  Must be specified for
-                  Writable tags where the value must be converted for a
-                  Condition.  For BinaryData tables, the format may have a size
-                  in trailing brackets which is a Perl expression to be
-                  evaluated.  The expression may access any of the previous
-                  table entries through a %val hash (read-only tags), the data
-                  size via $size, or the ExifTool object via $self.  For
-                  example, 'string[$val{3}]' defines a string with length given
-                  by the table entry with tag index '3'.  An initial "var_" may
-                  be added to the Format name of any BinaryData tag with a size
-                  in brackets.  In this case, subsequent offsets are adjusted by
-                  the value length minus the size of the default table FORMAT
-                  (eg. "var_int16u[10]" causes subsequent offsets to be
-                  incremented by sizeof(int16u) * 10 - sizeof(int8u) if the
-                  default table FORMAT is "int8u").  Note that all "var_" Format
-                  tags (as well as tags with values used within "var_" Format
-                  expressions) must have corresponding DATAMEMBER entries.
-
-  Count         : Used when writing EXIF information to specify the number
-                  values to write, or the number of characters in a fixed-length
-                  string.  A value of -1 indicates that the count is variable
-                  and should be determined by the number of values provided.
-                  Defaults to 1 if not specified for non-string formats.  Note
-                  that this count corresponds to the specified Format, so if a
-                  different-sized Writable format is defined, the actual count
-                  written to the file will be different.
-
-  FixCount      : Flag set to determine correct count from offsets in IFD.  This
-                  is necessary for some Kodak tags which write an incorrect
-                  Count value.
-
-  Flags         : Flags to specify characteristics for this tag.  May be a
-                  simple scalar flag name, a reference to a list of flag names,
-                  or a reference to a hash of flag/value pairs.  If not a hash
-                  reference, the flag value is set to 1.  Flags are expanded for
-                  faster access at run time into members of the tagInfo hash,
-                  and may be written directly as members if desired.  The
-                  available flag names are:
-
-                  'AutoSplit' - [List tags only] Similar to ListSplit option,
-                  but applied automatically to individual tags.  Value specifies
-                  pattern for split, or 1 for default pattern ',?\\s+'.
-
-                  'Avoid' - avoid creating this tag if possible.  This is only
-                  effective if another tag exists with the same name.  Setting
-                  this flag also sets the default Priority to 0 for this tag.
-
-                  'Binary' - set to 1 for binary data.  This has the same effect
-                  as setting ValueConv to '\$val', but it it a bit cleaner and
-                  avoids dummy ValueConvInv entries for writable tags.  Has no
-                  effect if ValueConv is defined for the tag.  Some values may
-                  be treated as binary data even if this flag is not set.
-
-                  'BlockExtract' - set for writable directories in EXIF
-                  information which are extracted by default.  Otherwise
-                  writable directories are only extracted as a block if
-                  specified explicitly.  Also used for Jpeg2000 and QuickTime
-                  XMP-like tags to extract as a block with a name other than
-                  'XMP'.
-
-                  'ConvertBinary' - true to apply ValueConv and/or PrintConv to
-                  Binary values (ie. SCALAR references).  (By default, these
-                  conversions are not done for Binary values.)
-
-                  'DataMember' - name of exiftool data member associated with
-                  this tag if it should be stored as a special data member when
-                  writing information.  Necessary only if the value of the tag
-                  affects other written information.  Currently only used for
-                  tags in EXIF tables where it triggers the execution of the
-                  RawConv to convert and store the value as an ExifTool data
-                  member when writing.
-
-                  'DataTag' - associated tag name containing data for offset or
-                  byte count tags.
-
-                  'Drop' - set to 1 for tags that should be excluded when
-                  rebuilding maker notes when copying all tags.  Set to a number
-                  larger than 1 to drop only if data is larger than this size.
-                  Works for SubDirectory tags too.
-
-                  'EntryBased' - set to 1 if the offset for this value is based
-                  on the IFD entry position.  This allows individual values to
-                  be entry-based even though some others aren't (as with the
-                  Casio PrintIM information).
-
-                  'Flat' - [flattened XMP structure tags only] must be set for
-                  all pre-defined flattened tags (including user-defined
-                  flattened tags).  This flag is reset to 0 internally after all
-                  associated flattened tags in the structure have been
-                  generated.
-
-                  'Flattened' - [reserved] used internally to mark Struct tags
-                  which have been processed to generate flattened equivalents.
-
-                  'GotGroups' - [reserved] flag used internally to indicate that
-                  the Groups hash has been initialized for this tag.
-
-                  'Hidden' - set to hide tag from the TagName documentation.
-                  Also suppresses verbose output of a BinaryData tag.
-
-                  'IsOffset' - flag set if the tag represents an offset to some
-                  data, and causes value will be adjusted to an absolute file
-                  offset.  If set to 2, the offset base of the parent directory
-                  is used even if the base changes for the current directory
-                  (only some maker notes are this messed up).  Set to 3 if
-                  absolute file offsets are used.  May be set to an expression
-                  to be evaluated.  Expression may access $val and $et,
-                  and is evaluated only when reading.
-
-                  'List' - flag indicating that duplicate entries of this tag
-                  are allowed, and will be accumulated in a list.  Note that for
-                  XMP information, 3 different types of lists are supported and
-                  the List value specifies the type: 'Bag', 'Seq' or 'Alt'.  As
-                  well, a value of '1' is used internally in XMP to allow list
-                  behaviour for a flattened tag which is itself not a list
-                  element (eg. a member of list of structures).  Note that in
-                  ExifTool an XMP lang-alt tag (Writable="lang-alt") is NOT a
-                  list-type tag (unless it is a list of lang-alt lists, which is
-                  uncommon).
-
-                  'MakerNotes' - set if this tag is maker note data.
-
-                  'MakerPreview' - set in the PreviewImageStart tag information
-                  if the preview must be stored inside the maker notes.
-
-                  'Mandatory' - set for mandatory tags.  Used only by TagInfoXML
-                  and documentation purposes.  Mandatory tags may be added
-                  automatically by ExifTool.
-
-                  'NestedHtmlDump' - flag set if value for this tag is also
-                  dumped when processing the SubDirectory.  This flag is implied
-                  if the MakerNotes flag is set.  Set to 2 if the dump should
-                  only be underlined if nested inside other maker notes.
-
-                  'NotIFD' - set for 'MakerNotes' SubDirectory tags only if the
-                  SubDirectory is not EXIF IFD format.  (Note: All SubDirectory
-                  tags in the MakerNotes table are 'MakerNotes' type by
-                  default.)
-
-                  'OffsetPair' - set if the tag represents half of an offset/
-                  byte count pair.  Data for these tags must be handled
-                  separately.  Value is the tagID for the paired tag.
-
-                  'Permanent' - flag indicates that a tag is permanent, and
-                  can't be added or deleted from the file, although a new value
-                  may be written if the tag already exists.  By default, all
-                  MakerNotes tags are permanent unless otherwise specified.
-
-                  'PrintHex' - specifies that unknown PrintConv values should
-                  be printed in hex (eg. 'Unknown (0x01)').  Also causes
-                  numerical tag values to be printed in hex in the HTML tag name
-                  documentation.
-
-                  'PrintString' - flag set to force PrintConv values to be
-                  printed as strings in the documentation.
-
-                  'Priority' - gives the priority of this tag while reading.  If
-                  set to zero, this tag will not override the value of previous
-                  tags with the same name.  If the priority is greater than
-                  zero, this tag won't be overridden by subsequent tags unless
-                  their priority is equal to or greater than this priority.  A
-                  special feature is that Priority 0 tags are automatically
-                  incremented to Priority 1 if they exist in the IFD of the full
-                  resolution image (as determined by SubfileType).  If not
-                  defined, the priority defaults to 1 for all tags except except
-                  tags in IFD1 of JPEG images which default to priority 0.
-
-                  'Protected' - bit mask to protect tags from writing:
-                  Bit 0x01 indicates an 'unsafe' tag, which is not set via
-                  SetNewValuesFromFile() unless specified explicitly.
-                  Bit 0x02 indicates a 'protected' tag, which should not be set
-                  directly by the user.
-
-                  'PutFirst' - [EXIF only] flag to place this value before IFD0
-                  when writing (ie. immediately after TIFF header).  Only used
-                  for main IFD's (IFD0, IFD1, etc) and IFD's where SubIFD flag
-                  is set to 2 (currently only ExifIFD).
-
-                  'RawJoin' - [List tags only] Joins raw List-type tag values
-                  into a single string with a space separator, allowing
-                  ValueConv and PrintConv to act on the concatenated string so
-                  the tag does not exhibit list-type behaviour.  When writing,
-                  the inverse is performed and the value is split at whitespace.
-
-                  'Resource' - [XMP only] flag to write value as an rdf:resource
-                  in an empty element instead of as a normal string.
-
-                  'SeparateTable' - set to list PrintConv values in a separate
-                  table in the HTML documentation.  Value is 1 for a table name
-                  of 'Module TagName', or 'TAG' for 'Module TAG', or 'MODULE
-                  TAG' to fully specify the table name.  The table may have a
-                  'Notes' entry for a description of the table.
-
-                  'SetResourceName' - [Photoshop tags only] set to 1 to append
-                  resource name to the extracted value (eg. 'VALUE/#NAME#/').
-                  Also allows resource name to be appended when writing new
-                  values.  May be set to any value other than 1 for a default
-                  resource name to use when writing if an appended name is not
-                  provided.
-
-                  'StructType' - [reserved] used internally by XMP writer for
-                  flattened structure tags as a flag to indicate that one or
-                  more enclosing structures has a TYPE field.
-
-                  'SubDoc' - [Composite tags only] set to cause this Composite
-                  tag to also be generated for each sub-document.  To achieve
-                  this, 'Main:' and 'Doc#:' prefixes are added to all Require'd
-                  and Desire'd tag names which don't already start with 'Main:'
-                  or 'Doc#:', and the Composite tag is built once for each of
-                  the main document and all sub-documents.
-
-                  'SubIFD' - used in writing to determine that the tag specifies
-                  an offset to a sub-IFD.  When this flag is set, the Group1
-                  name gives the name of the IFD.  Must be set if and only if
-                  the tag has a SubDirectory Start that references '$val' (this
-                  is validated by BuildTagLookup).  Set to 2 for standard EXIF
-                  SubIFD's where the PutFirst flag is valid.
-
-                  'Unknown' - this is an unknown tag (only extracted when the
-                  Unknown option is set).
-
-                  'WrongBase' - ['IsOffset' tags only] An expression using $self
-                  that is evaluated to generate a base shift for 'IsOffset' tags
-                  which use a different base than the rest of the tags.
-
-  RawConv       : Used to convert the Raw value at extraction time (while the
-                  image file is still open, unlike ValueConv and PrintConv below
-                  which are done later only if the value is requested).  May be
-                  a scalar expression using $val (the Raw tag value), $self (the
-                  current ExifTool object), $tag (the tag key), $tagInfo
-                  (reference to the tag information hash), and $priority (to
-                  dyanmically set the priority of a tag), or a code reference
-                  with $val and $self as arguments.  For Composite tags, $val is
-                  a reference to a hash of source ("derived from") tag names,
-                  and @val may be used to access the Raw values of these tags.
-                  The returned value may be a scalar which is used as the new
-                  Raw value, a scalar reference to a binary data value, a hash
-                  reference for Composite tags, an ARRAY reference for a list of
-                  values, or undefined to indicate that the tag should be
-                  ignored.  If RawConv is specified for a Composite tag, then
-                  ValueConv and PrintConv evals will no longer have access to
-                  the source @val and @prt values unless the input $val is
-                  returned.  RawConv may generate Warning or Error tags, while
-                  ValueConv and PrintConv should not (see ValueConv note below).
-                   Note: RawConv should only be used if necessary (in general,
-                  only if the conversion may return undef to ignore the tag, or
-                  if a Warning may be issued) because ValueConv is more
-                  efficient since it is only executed if the tag value is
-                  requested, while RawConv is executed for all extracted tags.
-
-  ValueConv     : Used to convert the Raw value to a useable form. May be a hash
-                  reference to act as a lookup table, a scalar which is
-                  evaluated as a Perl expression, a code reference to a
-                  subroutine, or an ARRAY reference (in which case the value is
-                  split at whitespace into a list of items and each item is
-                  converted by the associated entry in the ValueConv list).  If
-                  a hash reference is used and the Raw value doesn't appear as
-                  one of the keys, then the converted value is set to "Unknown
-                  (X)", where X is the Raw value (unless either of the special
-                  keys exist: 'BITMASK', a reference to a hash used to decode
-                  individual value bits; or 'OTHER', a reference to a subroutine
-                  used to convert unknown values.  The OTHER subroutine takes 3
-                  arguments: the value, a flag which is set for the inverse
-                  conversion, and a reference to the PrintConv hash, and returns
-                  the converted value or undef on error.  The lookup hash may
-                  also contain a 'Notes' entry which is used for documentation
-                  if the SeparateTable flag is set).  In an expression, $self is
-                  a reference to the current ExifTool object, $val is the Raw
-                  value, and $tag is the tag key.  The subroutine takes 2
-                  arguments: the Raw value and a reference to the current
-                  ExifTool object.  The expression or subroutine is evaluated
-                  when and if the tag value is requested (ie. only after all
-                  extraction is complete), so if necessary at this time the
-                  values of all other tags are available via calls to
-                  $self->GetValue("Tag","Raw"). (Note: In theory, types other
-                  than "Raw" may be accessed, but they are slower and may lead
-                  to cyclical dependencies so they should be avoided). When
-                  evaluated, the expression or subroutine returns a scalar for
-                  the converted value, a SCALAR reference to a binary data value
-                  (see the 'Binary' flag), or an ARRAY reference for a list of
-                  values.  The return value should always be defined -- use
-                  RawConv instead to return undef if it is necessary to test the
-                  value for validity, otherwise an undef tag may hide a
-                  previously defined value when the Duplicates option is not
-                  enabled.  If this isn't possible (as with Composite tags where
-                  the converted values of the source tags are needed), set the
-                  Priority to 0 to avoid taking priority over a valid tag.  If
-                  ValueConv is not specified, the Raw value is not converted.
-                  Composite tags which Require or Desire
-                  other tags may access the ValueConv, PrintConv and Raw values
-                  of these tags through the elements of the @val, @prt and @raw
-                  lists respectively (only if there was no RawConv or it
-                  returned a hash reference).  For these tags, $val may be used
-                  in an expression to represent $val[0], and the first argument
-                  passed for a code reference is a reference to @val.
-                  Note:  Warnings issued by these conversions are intercepted by
-                  ExifTool and saved as Warning tags, but since ValueConv and
-                  PrintConv conversions are done on demand, the warnings may be
-                  generated after the list of extracted tags is returned, so may
-                  easily be missed.
-
-  PrintConv     : This entry is similar to ValueConv above, except that it is
-                  used to further convert the tag value to a human readable
-                  form.  It can be either a hash lookup, a scalar Perl
-                  expression, a code reference or a list reference.  In this
-                  expression, $self, $val and $tag may be used as with
-                  ValueConv, but if ValueConv was defined then $val is the
-                  ValueConv value instead of the Raw value.  The returned value
-                  should always be defined.  Note that the print conversion is
-                  only done if the PrintConv option is enabled (which it is by
-                  default), and if the result of the ValueConv is not a scalar
-                  reference.  If it is a list reference, then the converted
-                  values are joined by '; ' in the output string.
-
-  RawConvInv    : The inverse of RawConv.  This should only be used in very rare
-                  situations when the raw value can not be predetermined.
-                  Unlike the other inverse conversions which are applied in
-                  SetNewValue(), this conversion is applied in WriteInfo() as
-                  the file is being written.  This is important because it means
-                  that FILE_TYPE and any DataMember tags ocurring before this
-                  tag in the file are available.  Beware that if the return
-                  value is not defined, the tag will be deleted unless there is
-                  specific logic to avoid this (currently, only EXIF and Binary
-                  data directories handle this case).
-
-  ValueConvInv  : The inverse of ValueConv.  Only necessary for Writable tags
-                  when ValueConv is specified (except WriteAlso tags).  Note
-                  that DataMember tags may NOT be used in the inverse
-                  conversions because these conversions are done before the
-                  input file is parsed.  Instead, a Condition or RawConvInv must
-                  be used.  May return undef on conversion error and call warn()
-                  to issue a warning.  If warn() is not called, a generic
-                  warning is generated when undef is returned.  An empty warning
-                  ("\n") may be issued to suppress warning messages when undef
-                  is returned.  If a scalar, the expression may use the
-                  variables $val, $self and $wantGroup.  If a code ref, the
-                  routine is passed 2 arguments: $val and $self.  Note that this
-                  conversion is not applied for deleted tags (ie. $val is
-                  undef).
-
-  PrintConvInv  : The inverse of PrintConv.  Only necessary if for Writable tags
-                  when PrintConv is specified (unless WriteAlso is used).  See
-                  ValueConvInv above for more details.
-
-  PrintConvColumns : Number of columns for PrintConv lookup in HTML docs. If not
-                  set, the number of columns is determined automatically
-                  according to the maximum width of the entries.
-
-  DelValue      : Raw value to be used when deleting a permanent tag.  (Note all
-                  MakerNotes tags are permanent.)  If not specified, an attempt
-                  is made to convert an empty string for the raw value.
-
-  Relist        : [Only if ValueConv or PrintConv is a list ref] Reference to a
-                  list of original value indices used to reorganize values. Each
-                  entry in the list may be a scalar index, or a reference to a
-                  list of indices to join values.  (Currently values may be
-                  joined, but the order of writable values must not be changed
-                  until this ability is added to the writer.)
-
-  Mask          : [BinaryData tags only] Bitmask for this value.  (Multiple tags
-                  may have the same index by using floating point indices.  An
-                  unknown tag will only be generated for a certain TagID if
-                  there is no integral TagID for that tag.)  The Mask is applied
-                  before evaluating RawConv.  When Mask is used, PrintHex=1 is
-                  implied unless otherwise defined.
-
-  Condition     : If given, specifies scalar which is evaluated as a Perl
-                  expression at extraction time to decide whether the tag is
-                  valid.  If used in a list of alternate tag definitions, the
-                  first list entry with a true condition is taken.  If no
-                  condition exists, then a 'true' condition is assumed.  The
-                  expression may use $self to access the ExifTool object.  The
-                  first 128 bytes of the raw data value are accessible through
-                  the reference $valPt for EXIF, Jpeg2000 and BinaryData tags
-                  only (note that for BinaryData tags, the raw data of $$valPt
-                  is always 'undef' type, and may not be used when writing
-                  except for SubDirectory tags).  EXIF tags (and maybe some
-                  other types) may also reference the format string and value
-                  count through $format and $count. Note that if the value is
-                  writable and $valPt is used, the tag must have a Format
-                  (unless 'undef' or 'string'), and a Count (unless 1 or length
-                  of the 'undef' or 'string'), so the raw data may be generated
-                  for evaluating the Condition.  When writing, $valPt, $format
-                  and $count refer to the new value, except for MakerNotes tags
-                  where $format and $count refer to the old tag if it existed.
-
-  Require       : [Composite tags only] A hash reference specifying the tags
-                  required to calculate the Composite tag value.  The hash
-                  values are the names of the required tags, and the keys
-                  specify the indices where the tag values are stored in the
-                  @val list used in the ValueConv and/or PrintConv expression.
-                  The Composite value is only calculated if the values for all
-                  Require'd tags are defined.  Require, Desire and Inhibit tag
-                  names may be prefixed by an optional group family 0 or 1 name
-                  followed by a colon.  Case IS significant.  The keys used by
-                  the Require, Desire and Inhibit hashes must not overlap (since
-                  they are used as indices into the common @val, @prt and @raw
-                  lists), and together the keys must be sequential starting from
-                  0.  A special feature allows a scalar tag name to be used
-                  instead of the hash reference when only the 0th tag is
-                  defined.  For example, the following two definitions are
-                  equivalent:
-
-                        Require => { 0 => 'XMP:Title' },
-                        Require => 'XMP:Title',
-
-  Desire        : [Composite tags only] This is the same as Require except that
-                  the Composite value is calculated even if the specified tags
-                  don't exist.  Beware that the elements of @val, @prt and @raw
-                  may be undefined for Desire'd tags.  If no tags are Require'd,
-                  at least one of the Desire'd tags must exist for the Composite
-                  tag to be generated.  If there are no Require'd or Desire'd
-                  tags, then then Composite tag is always generated.
-
-  Inhibit       : [Composite tags only] Similar to the Require and Desire
-                  hashes, except that the Composite tag is NOT built if any of
-                  the Inhibit tags exist.
-
-  Shift         : [Writable tags only] Specifies type of shift to apply if this
-                  value may be shifted.  Set to 'Time' for shifting date/time
-                  tags.
-
-  Writable      : Indicates this tag can be written (or not written if Writable
-                  is set to zero), and for EXIF-type tables gives format for
-                  writing.  Writable may be set to 1 for MakerNotes information
-                  because the existing format is always used, however providing
-                  a format is desireable because it is used in validating the
-                  value.  For EXIF tables, the Writable flag may be different
-                  than the Format flag, in which case Format is used for
-                  converting the binary value and Writable specifies the format
-                  code written to the EXIF IFD.  For SubDirectories in EXIF
-                  information, this flag is only defined if the SubDirectory is
-                  writable as a block, or if the SubDirectory can not be edited
-                  (in which case Writable is set to 0).  If non-zero, the
-                  SubDirectory is also extracted as a block, so the Binary and
-                  Protected flags should usually set as well.  There is
-                  currently no way to specify a write format for a SubDirectory
-                  that is not writable as a block (the default is 'int32u' for
-                  IFD-type SubDirectories, and 'undef' for all others).
-
-  WriteAlso     : Used for writable tag to specify other tags to write when this
-                  tag is written.  The value is a hash reference.  The hash keys
-                  are the names of the tags to write, and the values are
-                  evaluated to obtain the ValueConv values of each tag (or undef
-                  to delete the tag).  In the eval, $val is the Raw value of the
-                  parent tag (which may be undef if the tag is being deleted),
-                  and the %opts hash may be accessed to modify SetNewValue
-                  options for each tag.  By default, Type is set to "ValueConv"
-                  and the Protected option has bit 0x02 set to allow writing of
-                  Protected tags that aren't directly writable.  The AddValue
-                  and DelValue options from the parent tag are also defined, but
-                  no other options are set by default.  Previous new values of
-                  WriteAlso tags have already been removed prior to the eval if
-                  the Replace option was used for the parent tag.  If an empty
-                  warning is issued ("\n"), the target tag is not written and no
-                  error is reported.
-
-  WriteCheck    : If given, specifies a scalar which is evaluated as a Perl
-                  expression for a one-time validatation the Raw value being
-                  written.  The expression has access to 3 variables: $val is
-                  the value to be written, $self is the ExifTool object, and
-                  $tagInfo is the tag information hash reference.  It returns an
-                  error string, or undef if the value is good.  If the error
-                  string is empty, the tag is not written and no warnings are
-                  issued, but WriteAlso is still evaluated if it exists.
-
-  WriteOnly     : Flag set if tag is write-only.  Used for documentation only.
-
-  DelCheck      : Similar to WriteCheck, but called when the tag is deleted. The
-                  expression may access $self, $tagInfo and $wantGroup.  Returns
-                  error string, or undef on success, and may set $val to
-                  something other than undef.  May return empty string ('') to
-                  suppress warning messages but not delete tag (eg. when
-                  deleting only associated tags).
-
-  WriteCondition: [Writable EXIF tags only] Specifies a condition to be
-                  evaluated before the tag can be written to a specific file.
-                  The condition may use $self to reference the ExifTool object,
-                  and returns true if it is OK for writing.  Unlike WriteCheck
-                  which is done only once when the new value is set, this
-                  condition is evaluated just before the tags of the specific
-                  SubDirectory are written.
-
-  WriteGroup    : [Writable EXIF tags only] Specifies the IFD where the
-                  information gets written by default.  Must be defined for
-                  writable EXIF tags if WRITE_GROUP is not specified in table.
-
-  IsOverwriting : [Writable EXIF tags only] Specifies reference to subroutine
-                  which determines if tag should be overwritten.  Arguments are:
-                  0) ExifTool object ref, 1) new value hash ref, 2) old value,
-                  3) new value reference.
-
-  AllowGroup    : [Writable tags only] Regular expression string (case
-                  insensitive) to match group names which are allowed when
-                  writing this tag.  Only needed if tag can be written to
-                  groups other than the normal groups for this tag (very rare).
-
-  OffsetPair    : Used in EXIF table to specify the tagID for the corresponding
-                  offset or length tag.
-
-  DataTag       : Used in EXIF table to specify the tag name of the data
-                  associated with offset/length tags.
-
-  FixFormat     : [Writable EXIF SubIFD SubDirectory's only] Used to specify a
-                  format for writing an IFD pointer other than 'int32u'.
-
-  ChangeBase    : [EXIF tags in JPEG images only] Eval used to return new base
-                  for the offset for this tag only.  Eval may use $dirStart and
-                  $dataPos.  Note this is geared to the quirky Leica preview
-                  image offset, and is only used if the preview is outside the
-                  APP1 EXIF segment.
-
-  BitsPerWord   : [BITMASK tags only] Number of bits per decoded word.  Defaults
-                  to 32 if not specified.
-
-  BitsTotal     : [Writable BITMASK tags only] Total number of bits in bit mask.
-                  Defaults to BitsPerWord if not specified.
-
-  Struct        : [XMP tags only] Reference to structure hash for structured XMP
-                  tags.  See "STRUCTURES" section below for more details.  (For
-                  backward compatibility, this may be a name to an entry in
-                  %Image::ExifTool::UserDefined::xmpStruct, but this use is
-                  deprecated.)  Flattened tags are automatically generated for
-                  each field in the structure.  Note that Struct tags can NOT
-                  have ValueConv/PrintConv entries, because values that are HASH
-                  references are are also used by Composite tags, which use the
-                  the Conv entries to generate the Composite value.
-
-  NoSubStruct   : [XMP tags only] Flag set in flattened tag to break cyclical
-                  recursion in nested structures.
-
-  Namespace     : [XMP tags only] Gives standard XMP namespace prefix to use for
-                  this tag.  If not defined, the tag table NAMESPACE is used.
-
-  FlatName      : [Struct tags and structure fields only] Name used for
-                  automatically-generated flattened tag names, defaults to Name
-                  if not specified.  In general, this is used to remove the
-                  redundant names found in some specifications.  May be empty
-                  ('') for a Struct tag but not for a structure field.
-
-  Units         : [MIE tags only] Reference to a list of valid units strings.
-                  The default units are the first item in the list.
-
-  Hook          : [BinaryData tags only] Expression to be evaluated when
-                  extracting tag to allow dynamic Format, etc for BinaryData
-                  tags.  May access $self, and $size (the full size of the
-                  binary data block), and assign a new value to $format to
-                  dynamically set the tag format, and/or increment $varSize to
-                  add a byte offset to subsequent tags.  $varSize may be set to
-                  a large number to effectively abort processing of the
-                  directory after this tag.  Must have corresponding DATAMEMBER
-                  entry in writable tables.  Must not have Unknown set.
-
-  LargeTag      : [BinaryData tags only] Flag to indicate that the data for this
-                  tag is large, and that it shouldn't be stored in the %val
-                  hash, even if the tag exists as a DATAMEMBER.
-
-  SetBase       : [QuickTime and BinaryData tags only] Sets ExifTool BASE offset
-                  for use when ExtractInfo is called with the ReEntry flag from
-                  inside the RawConv of a tag.
-
-  TagID         : [reserved] Used internally to save the table key for this tag.
-                  Note: For XMP tables this corresponds to the XMP property
-                  name, but the table key may have a full XMP namespace prefix
-                  added.
-
-  NewTagID      : [reserved] Used internally to save new ID of tag in Composite
-                  table if it is different that the original TagID (happens if
-                  there was a conflict with an existing entry in the table)
-
-  Index         : [reserved] Used internally to save the index of tagInfo items
-                  which are in a conditional list.
-
-  Table         : [reserved] Reference to parent tag table.
-
-  PropertyPath  : [reserved] Used internally by XMP writer to save property path
-                  name.  Also used in structure field information hashes, but
-                  for these the full property path is not stored.
-
-  SrcTagInfo    : [reserved] Used internally to store reference to default
-                  language tagInfo hash for alternate-language tags.
-
-  OtherLang     : [reserved] Used internally by QuickTime module to store a list
-                  of tag ID's for alternate-language tags based on this one.
-
-  RootTagInfo   : [reserved] Used internally to store a reference to the tag
-                  information hash of the top-level structure for flattened
-                  structure tags.
-
-  Module        : [reserved] Used internally to store module name for writable
-                  Composite tags.
-
-  LangCode      : [reserved] Used internally to indicate language code for
-                  alternate language tags (eg. 'fr').  Only used with formats
-                  which support alternate languages (eg. XMP, MIE, etc).
-
-  SubDirectory {  If it exists, this specifies the start of a new subdirectory.
-                  It contains a collection of variables which specify the type
-                  and location of the subdirectory.  These variables are
-                  described below:
-
-     TagTable   : Specifies the name of the tag table lookup for the new
-                  subdirectory.  If not specified, the parent tag table is used.
-
-     Start      : The offset to the start of the subdirectory relative to the
-                  current Base.  This is a Perl expression which may use
-                  $valuePtr to represent the location of the tag value in the
-                  file, or $val for the value itself.  If not specified, a Start
-                  of '$valuePtr' is assumed.
-
-     OffsetPt   : [EXIF directories only] If specified, this is a Perl
-                  expression that gives the position of a 32-bit word in the
-                  current directory that is added to the Start position to get
-                  the position of the new subdirectory.  The expression
-                  should use the position of the current tag ($valuePtr).
-
-     Base       : This expression specifies the base offset for all pointers in
-                  the subdirectory.  This need not be specified if the offset is
-                  the same as the current directory, which is normally the case.
-                  May use $start to represent the subdirectory start location
-                  relative to the current base, and $base for the value of the
-                  current base.  If this is defined, the automatic validation of
-                  base offsets is disabled for maker notes directories.  The IFD
-                  is flagged as using relative offsets when writing if '$start'
-                  is used in this expression.
-
-     EntryBased : [EXIF directories only] Flag indicating that the offsets are
-                  based on the individual directory entry position, so offsets
-                  are incremented by 12 times the corresponding entry index.
-
-     MaxSubdirs : Maximum number of subdirectories specified by the current tag
-                  (if the tag specifies multiple values).  If not specified, the
-                  tag value ($val) is used as-is.  If MaxSubdirs is specified,
-                  then one subdirectory is parsed for each value found up to the
-                  maximum number specified.  Ignored when writing.
-
-     ByteOrder  : Specifies byte ordering if different than than the rest of the
-                  file.  Must be either BigEndian, LittleEndian or Unknown.  If
-                  Unknown is specified, the byte order will be determined from
-                  the directory count (however, this can not be done if OffsetPt
-                  is specified).
-
-     Validate   : If given, specifies Perl expression which is used to validate
-                  the subdirectory data.  The following variables may be used in
-                  the expression: $val (value of the tag), $dirData (reference
-                  to directory data), $subdirStart (offset to subdirectory
-                  start) and $size (size of subdirectory).  Returns true if
-                  subirectory is valid.
-
-     ProcessProc: If given, specifies processing procedure used to decode this
-                  subdirectory data.  This overrides the default procedure
-                  specified by PROCESS_PROC in the tag table.
-
-     WriteProc  : If given, specifies processing procedure used to write this
-                  subdirectory data.  This overrides the default procedure
-                  specified by WRITE_PROC in the tag table.
-
-     DirName    : Name of this subdirectory.  If not specified, the name is
-                  taken from the tag name.  DirName is important because it is
-                  used when writing to compare against names in the directory
-                  map to determine which directories need to be edited.
-
-     FixBase    : Flag set if base offsets should be fixed.  Used to add a
-                  constant to maker notes offsets to fix damage done by some
-                  image editing utilities. (maker notes only)  Set to 2 for
-                  unknown maker notes to be a bit more flexible in adjusting
-                  the base offset.
-
-     AutoFix    : Flag set to patch GE makernote offset quirks and apply FixBase
-                  without warnings when writing.
-
-     FixOffsets : Expression to evaluate for each value pointer to patch
-                  problems with some EXIF maker note offsets.  May access the
-                  following variables: $valuePtr, $valEnd, $size, $tagID and
-                  $wFlag.  May return undef when writing to ignore the entry.
-
-     RelativeBase:[EXIF directories only] Flag to adjust all offsets relative
-                  to the start of the IFD when writing.
-
-     Multi      : [EXIF directories only] Flag to allow multiple linked IFD's.
-                  1 is assumed if DirName is IFD0 or SubIFD unless otherwise
-                  defined.
-
-     Magic      : [TiffIFD directories only] Magic number used in TIFF-like
-                  header.
-  }
-
-STRUCTURES
-
-Structure hashes are very similar to tag tables in that their keys are structure
-field ID's and their values are structure field information hashes.  The special
-keys in structure hashes are:
-
-  NAMESPACE   : Same as in tag tables, but may be set to undef for a
-                variable-namespace structure which holds any top-level tag. This
-                is mandatory for built-in tags, but optional for user-defined
-                tags (where it defaults to the NAMESPACE of the tag table).
-
-  STRUCT_NAME : Name of structure (used in warning messages and documentation).
-                May contain leading module name separated by a space to avoid
-                name conflicts with same-named structures in other modules.
-                Default module is "XMP" unless otherwise specified.
-
-  TYPE        : rdf:type resource for structure.
-
-  NOTES       : Notes for documentation.
-
-  GROUPS      : Same as in tag table, but only the family 2 group name is used,
-                as the default for the flattened tags.
-
-The contained structure field information hashes are similar to tag information
-hashes, except that only the following elements are used:
-
-  Raw/Value/PrintConv (and their inverses), TagID (optional), Groups, List,
-  Writable, Struct, Namespace, LangCode, PropertyPath.
-
-But note that for PropertyPath, only the element of the path corresponding to
-the specific field is stored (including any necessary list properties).  The
-full property path is obtained by walking the structure tree.
-
-Flattened tags corresponding to each field in a structure are automatically
-generated (using an on-demand approach to reduce startup overhead).  Pre-defined
-flattened tags are allowed, and are used when it is necessary to change the Name
-or Description of a flattened tag.  The flattened tag information hash entries
-are copied from the corresponding structure field definitions, even for
-pre-defined flattened tags.  The exception is that the List property is
-generated automatically unless explicity set to 0 in a pre-defined flattened
-tag.
-
---------------------------------------------------------------------------------