exiftool_vendored 9.78.0 → 9.99.0

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

@@ -0,0 +1,981 @@
+--------------------------------------------------------------------------------
+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.
+
+--------------------------------------------------------------------------------