mini_exiftool_vendored 8.9.7.v2 → 9.2.7.v1

data/vendor/Image-ExifTool-8.97/lib/Image/ExifTool.pod

@@ -1,2276 +0,0 @@
-#------------------------------------------------------------------------------
-# File:         ExifTool.pod - Documentation for File::ExifTool
-#
-# Description:  Read and write meta information
-#
-# URL:          http://owl.phy.queensu.ca/~phil/exiftool/
-#
-# Legal:        Copyright (c) 2003-2012, Phil Harvey (phil at owl.phy.queensu.ca)
-#               This library is free software; you can redistribute it and/or
-#               modify it under the same terms as Perl itself.
-#------------------------------------------------------------------------------
-
-=head1 NAME
-
-Image::ExifTool - Read and write meta information
-
-=head1 SYNOPSIS
-
-  use Image::ExifTool qw(:Public);
-
-  # ---- Simple procedural usage ----
-
-  # Get hash of meta information tag names/values from an image
-  $info = ImageInfo('a.jpg');
-
-  # ---- Object-oriented usage ----
-
-  # Create a new Image::ExifTool object
-  $exifTool = new Image::ExifTool;
-
-  # Extract meta information from an image
-  $exifTool->ExtractInfo($file, \%options);
-
-  # Get list of tags in the order they were found in the file
-  @tagList = $exifTool->GetFoundTags('File');
-
-  # Get the value of a specified tag
-  $value = $exifTool->GetValue($tag, $type);
-
-  # Get a tag description
-  $description = $exifTool->GetDescription($tag);
-
-  # Get the group name associated with this tag
-  $group = $exifTool->GetGroup($tag, $family);
-
-  # Set a new value for a tag
-  $exifTool->SetNewValue($tag, $newValue);
-
-  # Write new meta information to a file
-  $success = $exifTool->WriteInfo($srcfile, $dstfile);
-
-  # ...plus a host of other useful methods...
-
-=head1 DESCRIPTION
-
-ExifTool provides an extensible set of perl modules to read and write meta
-information in a wide variety of files, including the maker note information
-of many digital cameras by various manufacturers such as Canon, Casio,
-FujiFilm, GE, HP, JVC/Victor, Kodak, Leaf, Minolta/Konica-Minolta, Nikon,
-Olympus/Epson, Panasonic/Leica, Pentax/Asahi, Reconyx, Ricoh, Samsung,
-Sanyo, Sigma/Foveon and Sony.
-
-Below is a list of file types and meta information formats currently
-supported by ExifTool (r = read, w = write, c = create):
-
-  File Types
-  ------------+-------------+-------------+-------------+------------
-  3FR   r     | EIP   r     | LNK   r     | PAC   r     | RWL   r/w
-  3G2   r     | EPS   r/w   | M2TS  r     | PAGES r     | RWZ   r
-  3GP   r     | ERF   r/w   | M4A/V r     | PBM   r/w   | RM    r
-  ACR   r     | EXE   r     | MEF   r/w   | PCD   r     | SO    r
-  AFM   r     | EXIF  r/w/c | MIE   r/w/c | PDF   r/w   | SR2   r/w
-  AI    r/w   | EXR   r     | MIFF  r     | PEF   r/w   | SRF   r
-  AIFF  r     | F4A/V r     | MKA   r     | PFA   r     | SRW   r/w
-  APE   r     | FFF   r/w   | MKS   r     | PFB   r     | SVG   r
-  ARW   r/w   | FLA   r     | MKV   r     | PFM   r     | SWF   r
-  ASF   r     | FLAC  r     | MNG   r/w   | PGF   r     | THM   r/w
-  AVI   r     | FLV   r     | MOS   r/w   | PGM   r/w   | TIFF  r/w
-  BMP   r     | FPX   r     | MOV   r     | PICT  r     | TTC   r
-  BTF   r     | GIF   r/w   | MP3   r     | PMP   r     | TTF   r
-  CHM   r     | GZ    r     | MP4   r     | PNG   r/w   | VRD   r/w/c
-  COS   r     | HDP   r/w   | MPC   r     | PPM   r/w   | VSD   r
-  CR2   r/w   | HDR   r     | MPG   r     | PPT   r     | WAV   r
-  CRW   r/w   | HTML  r     | MPO   r/w   | PPTX  r     | WDP   r/w
-  CS1   r/w   | ICC   r/w/c | MQV   r     | PS    r/w   | WEBP  r
-  DCM   r     | IDML  r     | MRW   r/w   | PSB   r/w   | WEBM  r
-  DCP   r/w   | IIQ   r/w   | MXF   r     | PSD   r/w   | WMA   r
-  DCR   r     | IND   r/w   | NEF   r/w   | PSP   r     | WMV   r
-  DFONT r     | INX   r     | NRW   r/w   | QTIF  r     | WV    r
-  DIVX  r     | ITC   r     | NUMBERS r   | RA    r     | X3F   r/w
-  DJVU  r     | J2C   r     | ODP   r     | RAF   r/w   | XCF   r
-  DLL   r     | JNG   r/w   | ODS   r     | RAM   r     | XLS   r
-  DNG   r/w   | JP2   r/w   | ODT   r     | RAR   r     | XLSX  r
-  DOC   r     | JPEG  r/w   | OFR   r     | RAW   r/w   | XMP   r/w/c
-  DOCX  r     | K25   r     | OGG   r     | RIFF  r     | ZIP   r
-  DV    r     | KDC   r     | OGV   r     | RSRC  r     |
-  DVB   r     | KEY   r     | ORF   r/w   | RTF   r     |
-  DYLIB r     | LA    r     | OTF   r     | RW2   r/w   |
-
-  Meta Information
-  ----------------------+----------------------+---------------------
-  EXIF           r/w/c  |  CIFF           r/w  |  Ricoh RMETA    r
-  GPS            r/w/c  |  AFCP           r/w  |  Picture Info   r
-  IPTC           r/w/c  |  Kodak Meta     r/w  |  Adobe APP14    r
-  XMP            r/w/c  |  FotoStation    r/w  |  MPF            r
-  MakerNotes     r/w/c  |  PhotoMechanic  r/w  |  Stim           r
-  Photoshop IRB  r/w/c  |  JPEG 2000      r    |  APE            r
-  ICC Profile    r/w/c  |  DICOM          r    |  Vorbis         r
-  MIE            r/w/c  |  Flash          r    |  SPIFF          r
-  JFIF           r/w/c  |  FlashPix       r    |  DjVu           r
-  Ducky APP12    r/w/c  |  QuickTime      r    |  M2TS           r
-  PDF            r/w/c  |  Matroska       r    |  PE/COFF        r
-  PNG            r/w/c  |  GeoTIFF        r    |  AVCHD          r
-  Canon VRD      r/w/c  |  PrintIM        r    |  ZIP            r
-  Nikon Capture  r/w/c  |  ID3            r    |  (and more)
-
-=head1 CONFIGURATION
-
-User-defined tags can be added via the ExifTool configuration file, or by
-defining the %Image::ExifTool::UserDefined hash before calling any ExifTool
-methods.  See "ExifTool_config" in the ExifTool distribution for more
-details.
-
-By default ExifTool looks for a configuration file named ".ExifTool_config"
-first in your home directory, then in the directory of the application
-script, but a different file may be specified by setting the ExifTool
-C<configFile> variable before using Image::ExifTool.  For example:
-
-    BEGIN { $Image::ExifTool::configFile = '/Users/phil/myconfig.cfg' }
-    use Image::ExifTool;
-
-or the configuration feature may be disabled by setting C<configFile> to an
-empty string:
-
-    BEGIN { $Image::ExifTool::configFile = '' }
-    use Image::ExifTool;
-
-=head1 EXPORTS
-
-Exports nothing by default, but L</ImageInfo> and all static methods may be
-exported with the C<:Public> export list.
-
-=head1 METHODS
-
-All ExifTool features are accessed through the methods of the public
-interface listed below.  Other Image::ExifTool methods and modules should
-not be accessed directly because their interface may change with future
-versions.
-
-None of these methods should ever die or issue warnings to STDERR if called
-with the proper arguments (with the exception of L</SetNewValue> which may
-send an error message to STDERR, but only when called in scalar context). 
-Error and warning messages that occur during processing are stored in the
-values of the Error and Warning tags, and are accessible via the
-L</GetValue> method.
-
-=head2 new
-
-Creates a new ExifTool object.
-
-    $exifTool = new Image::ExifTool;
-
-Note that ExifTool uses AUTOLOAD to load non-member methods, so any class
-using Image::ExifTool as a base class must define an AUTOLOAD which calls
-Image::ExifTool::DoAutoLoad().  ie)
-
-    sub AUTOLOAD
-    {
-        Image::ExifTool::DoAutoLoad($AUTOLOAD, @_);
-    }
-
-=head2 ImageInfo
-
-Read image file and return meta information.  This is the one step function
-for retrieving meta information from an image.  Internally, L</ImageInfo>
-calls L</ExtractInfo> to extract the information, L</GetInfo> to generate
-the information hash, and L</GetTagList> for the returned tag list.
-
-    # return meta information for 2 tags only (procedural)
-    $info = ImageInfo($filename, $tag1, $tag2);
-
-    # return information about an open image file (object-oriented)
-    $info = $exifTool->ImageInfo(\*FILE);
-
-    # return information from image data in memory for specified tags
-    %options = (PrintConv => 0);
-    @tagList = qw(filename imagesize xmp:creator exif:* -ifd1:*);
-    $info = ImageInfo(\$imageData, \@tagList, \%options);
-
-    # extract information from an embedded thumbnail image
-    $info = ImageInfo('image.jpg', 'thumbnailimage');
-    $thumbInfo = ImageInfo($$info{ThumbnailImage});
-
-=over 4
-
-=item Inputs:
-
-L</ImageInfo> is very flexible about the input arguments, and interprets
-them based on their type.  It may be called with one or more arguments.
-The one required argument is either a SCALAR (the image file name), a file
-reference (a reference to the image file) or a SCALAR reference (a
-reference to the image in memory).  Other arguments are optional.  The
-order of the arguments is not significant, except that the first SCALAR is
-taken to be the file name unless a file reference or scalar reference comes
-earlier in the argument list.
-
-Below is an explanation of how the L</ImageInfo> function arguments are
-interpreted:
-
-=over 4
-
-=item ExifTool ref
-
-L</ImageInfo> may be called with an ExifTool object if desired.  Advantages
-of using the object-oriented form are that options may be set before calling
-L</ImageInfo>, and the object may be used afterward to access member
-functions.  Must be the first argument if used.
-
-=item SCALAR
-
-The first scalar argument is taken to be the file name unless an earlier
-argument specified the image data via a file reference (file ref) or data
-reference (SCALAR ref).  The remaining scalar arguments are names of tags
-for requested information.  All tags are returned if no tags are specified.
-
-Tag names are case-insensitive and may be prefixed by optional group names
-separated by colons.  A group name may begin with a family number (ie.
-'1IPTC:Keywords'), to restrict matches to a specific family.  In the tag
-name, a '?' matches any single character and a '*' matches zero or more
-characters.  Thus 'GROUP:*' represents all tags in a specific group. 
-Wildcards may not be used in group names, with the exception that a group
-name of '*' may be used to extract all available instances of a tag
-regardless of the L</Duplicates> setting (ie. '*:WhiteBalance').  Multiple
-groups may be specified (ie. 'EXIF:Time:*' extracts all EXIF Time tags). And
-finally, a leading '-' indicates a tag to be excluded (ie. '-IFD1:*'), or a
-trailing '#' causes the ValueConv value to be returned for this tag.
-
-Note that keys in the returned information hash and elements of the returned
-tag list are not necessarily the same as these tag names because group names
-are removed, the case may be changed, and an instance number may be added. 
-For this reason it is best to use either the keys of the returned hash or
-the elements of the tag array when accessing the tag values.
-
-See L<Image::ExifTool::TagNames|Image::ExifTool::TagNames> for a complete
-list of ExifTool tag names.
-
-=item File ref
-
-A reference to an open image file.  If you use this method (or a SCALAR
-reference) to access information in an image, the FileName and Directory
-tags will not be returned.  (Also, the FileSize, FileModifyDate and
-FilePermissions tags will not be returned unless it is a plain file.)  Image
-processing begins at the current file position, and on return the file
-position is unspecified.  May be either a standard filehandle, or a
-reference to a L<File::RandomAccess|File::RandomAccess> object.  Note that
-the file remains open and must be closed by the caller after L</ImageInfo>
-returns.
-
-[Advanced:  To allow a non-rewindable stream (ie. a network socket) to be
-re-read after processing with ExifTool, first wrap the file reference in a
-L<File::RandomAccess|File::RandomAccess> object, then pass this object to
-L</ImageInfo>.  The L<File::RandomAccess|File::RandomAccess> object will
-buffer the file if necessary, and may be used to re-read the file after
-L</ImageInfo> returns.]
-
-=item SCALAR ref
-
-A reference to image data in memory.
-
-=item ARRAY ref
-
-Reference to a list of tag names.  On entry, any elements in the list are
-added to the list of requested tags.  Tags with names beginning with '-' are
-excluded.  On return, this list is updated to contain an ordered list of tag
-keys for the returned information.
-
-There will be 1:1 correspondence between the requested tags and the returned
-tag keys only if the L</Duplicates> option is 0 and L</Sort> is 'Input'. 
-(With L</Duplicates> enabled, there may be more entries in the returned list
-of tag keys, and with other L</Sort> settings the entries may not be in the
-same order as requested.)
-
-=item HASH ref
-
-Reference to a hash containing the options settings.  See L</Options>
-documentation below for a list of available options.  Options specified
-as arguments to L</ImageInfo> take precedence over L</Options> settings.
-
-=back
-
-=item Return Values:
-
-L</ImageInfo> returns a reference to a hash of tag key/value pairs.  The tag
-keys are identifiers, which are similar to the tag names but may have an
-embedded instance number if multiple tags with the same name were extracted
-from the image.  Many of the ExifTool functions require a tag key as an
-argument. Use L</GetTagName [static]> to get the tag name for a given tag
-key.  Note that the case of the tag names may not be the same as requested.
-Here is a simple example to print out the information returned by
-L</ImageInfo>:
-
-    foreach (sort keys %$info) {
-        print "$_ => $$info{$_}\n";
-    }
-
-Values of the returned hash are usually simple scalars, but a scalar
-reference is used to indicate binary data and an array reference may be used
-to indicate a list.  Also, a hash reference may be returned if the L</Struct>
-option is used.  Lists of values are joined by commas into a single
-string only if the PrintConv option is enabled and the List option is
-disabled (which are the defaults).  Note that binary values are not
-necessarily extracted unless specifically requested, or the Binary option is
-enabled and the tag is not specifically excluded.  If not extracted the
-value is a reference to a string of the form "Binary data ##### bytes".
-
-The code below gives an example of how to handle these return values, as
-well as illustrating the use of other ExifTool functions:
-
-    use Image::ExifTool;
-    my $exifTool = new Image::ExifTool;
-    $exifTool->Options(Unknown => 1);
-    my $info = $exifTool->ImageInfo('a.jpg');
-    my $group = '';
-    my $tag;
-    foreach $tag ($exifTool->GetFoundTags('Group0')) {
-        if ($group ne $exifTool->GetGroup($tag)) {
-            $group = $exifTool->GetGroup($tag);
-            print "---- $group ----\n";
-        }
-        my $val = $info->{$tag};
-        if (ref $val eq 'SCALAR') {
-            if ($$val =~ /^Binary data/) {
-                $val = "($$val)";
-            } else {
-                my $len = length($$val);
-                $val = "(Binary data $len bytes)";
-            }
-        }
-        printf("%-32s : %s\n", $exifTool->GetDescription($tag), $val);
-    }
-
-=item Notes:
-
-ExifTool returns all values as byte strings of encoded characters.  Perl
-wide characters are not used.  See L</CHARACTER ENCODINGS> for details about
-the encodings.  By default, most returned strings are encoded in UTF-8.  For
-these, Encode::decode_utf8() may be used to convert to a sequence of logical
-Perl characters.
-
-As well as tags representing information extracted from the image,
-the following tags generated by ExifTool may be returned:
-
-    ExifToolVersion - The ExifTool version number.
-
-    Error - An error message if the image could not be processed.
-
-    Warning - A warning message if problems were encountered while
-              processing the image.
-
-=back
-
-=head2 Options
-
-Get/set ExifTool options.  This function can be called to set the default
-options for an ExifTool object.  Options set this way are in effect for
-all function calls but may be overridden by options passed as arguments
-to some functions.
-
-The default option values may be changed by defining a
-%Image::ExifTool::UserDefined::Options hash.  See the ExifTool_config file
-in the full ExifTool distribution for examples.
-
-    # exclude the 'OwnerName' tag from returned information
-    $exifTool->Options(Exclude => 'OwnerName');
-
-    # only get information in EXIF or MakerNotes groups
-    $exifTool->Options(Group0 => ['EXIF', 'MakerNotes']);
-
-    # ignore information from IFD1
-    $exifTool->Options(Group1 => '-IFD1');
-
-    # sort by groups in family 2, and extract unknown tags
-    $exifTool->Options(Sort => 'Group2', Unknown => 1);
-
-    # reset DateFormat option
-    $exifTool->Options(DateFormat => undef);
-
-    # do not extract duplicate tag names
-    $oldSetting = $exifTool->Options(Duplicates => 0);
-
-    # get current Verbose setting
-    $isVerbose = $exifTool->Options('Verbose');
-
-=over 4
-
-=item Inputs:
-
-0) ExifTool object reference.
-
-1) Option parameter name.
-
-2) [optional] Option parameter value (may be undef to clear option).
-
-3-N) [optional] Additional parameter/value pairs.
-
-=item Option Parameters:
-
-=over 4
-
-=item Binary
-
-Flag to extract the value data for all binary tags.  Tag values representing
-large binary data blocks (ie. ThumbnailImage) are not necessarily extracted
-unless this option is set or the tag is specifically requested by name.
-Default is 0.
-
-=item ByteOrder
-
-The byte order for newly created EXIF segments when writing.  Note that if
-EXIF information already exists, the existing order is maintained.  Valid
-values are 'MM', 'II' and undef.  If ByteOrder is not defined (the default),
-then the maker note byte order is used (if they are being copied), otherwise
-big-endian ('MM') order is assumed.  This can also be set via the
-ExifByteOrder tag, but the ByteOrder option takes precedence if both are
-set.
-
-=item Charset
-
-Character set for encoding character strings passed to/from ExifTool with
-code points above U+007F.  Default is 'UTF8'.  Valid values are listed
-below, case is not significant:
-
-  Value        Alias(es)        Description
-  -----------  ---------------  ----------------------------------
-  UTF8         cp65001, UTF-8   UTF-8 characters
-  Latin        cp1252, Latin1   Windows Latin1 (West European)
-  Latin2       cp1250           Windows Latin2 (Central European)
-  Cyrillic     cp1251, Russian  Windows Cyrillic
-  Greek        cp1253           Windows Greek
-  Turkish      cp1254           Windows Turkish
-  Hebrew       cp1255           Windows Hebrew
-  Arabic       cp1256           Windows Arabic
-  Baltic       cp1257           Windows Baltic
-  Vietnam      cp1258           Windows Vietnamese
-  Thai         cp874            Windows Thai
-  MacRoman     cp10000, Roman   Macintosh Roman
-  MacLatin2    cp10029          Macintosh Latin2 (Central Europe)
-  MacCyrillic  cp10007          Macintosh Cyrillic
-  MacGreek     cp10006          Macintosh Greek
-  MacTurkish   cp10081          Macintosh Turkish
-  MacRomanian  cp10010          Macintosh Romanian
-  MacIceland   cp10079          Macintosh Icelandic
-  MacCroatian  cp10082          Macintosh Croatian
-
-Note that this option affects some types of information when reading/writing
-the file and other types when getting/setting tag values, so it must be
-defined for both types of access.
-
-=item CharsetEXIF
-
-Internal encoding to use for stored EXIF "ASCII" string values.  Unlike
-other Charset options, CharsetEXIF may also be set to undef to pass through
-all string values without recoding.  Default is undef.
-
-=item CharsetID3
-
-Internal encoding to assume for ID3v1 strings.  By the specification ID3v1
-strings should be encoded in ISO 8859-1 (essentially Latin), but some
-applications may use local encoding instead.  Default is 'Latin'.
-
-=item CharsetIPTC
-
-Fallback internal IPTC character set to assume if IPTC information contains
-no CodedCharacterSet tag.  Possible values are the same as the L</Charset>
-option. Default is 'Latin'.
-
-Note that this option affects some types of information when reading/writing
-the file and other types when getting/setting tag values, so it must be
-defined for both types of access.
-
-=item CharsetPhotoshop
-
-Internal encoding to assume for Photoshop IRB resource names.  Default is
-'Latin'.
-
-=item CharsetQuickTime
-
-Internal encoding to assume for QuickTime strings stored with an unspecified
-encoding.  Default is 'MacRoman'.
-
-=item Compact
-
-Flag to write compact output.  Default is 0.  The XMP specification suggests
-that the data be padded with blanks to allow in-place editing.  With this
-flag set the 2kB of padding is not written.  Note that this only effects
-embedded XMP since padding is never written for stand-alone XMP files.
-
-=item Composite
-
-Flag to generate Composite tags when extracting information.  Default is 1.
-
-=item Compress
-
-Flag to write new values in compressed format if possible.  Has no effect
-unless Compress::Zlib is installed.  Default is 0.
-
-=item CoordFormat
-
-Format for printing GPS coordinates.  This is a printf format string with
-specifiers for degrees, minutes and seconds in that order, however minutes
-and seconds may be omitted.  If the hemisphere is known, a reference
-direction (N, S, E or W) is appended to each printed coordinate, but adding
-a C<+> to the format specifier (ie. C<%+.6f>) prints a signed coordinate
-instead.  For example, the following table gives the output for the same
-coordinate using various formats:
-
-      CoordFormat        Example Output
-  -------------------  ------------------
-  q{%d deg %d' %.2f"}  54 deg 59' 22.80"  (default for reading)
-  q{%d %d %.8f}        54 59 22.80000000  (default for copying)
-  q{%d deg %.4f min}   54 deg 59.3800 min
-  q{%.6f degrees}      54.989667 degrees
-
-Note:  To avoid loss of precision, the default coordinate format is
-different when copying tags with L</SetNewValuesFromFile>.
-
-=item DateFormat
-
-Format for printing date/time values.  See C<strftime> in the L<POSIX>
-package for details about the format string.  The default is similar to a
-format of "%Y:%m:%d %H:%M:%S".  If date can not be converted, value is left
-unchanged unless the StrictDate option is set.  Timezones are ignored.
-
-=item Duplicates
-
-Flag to return values from tags with duplicate names when extracting
-information.  Default is 1.
-
-=item Escape
-
-Escape special characters in extracted values for HTML or XML.  Also
-unescapes HTML or XML character entities in input values passed to
-L</SetNewValue>.  Valid settings are 'HTML', 'XML' or undef.  Default is
-undef.
-
-=item Exclude
-
-Exclude specified tags from tags extracted from an image.  The option value
-is either a tag name or reference to a list of tag names to exclude.  The
-case of tag names is not significant.  This option is ignored for
-specifically requested tags.  Tags may also be excluded by preceeding their
-name with a '-' in the arguments to L</ImageInfo>.
-
-=item ExtractEmbedded
-
-Flag to extract information from embedded documents in EPS and PDF files,
-embedded MPF images in JPEG and MPO files, streaming metadata in AVCHD
-videos, and the resource fork of Mac OS files.  Default is 0.
-
-=item FastScan
-
-Flag to increase speed of extracting information from JPEG images.  With
-this option set to 1, ExifTool will not scan to the end of a JPEG image to
-check for an AFCP, CanonVRD, FotoStation, PhotoMechanic, MIE or PreviewImage
-trailer.  This also stops the parsing after the first comment in GIF images,
-and at the audio/video data with RIFF-format files (AVI, WAV, etc), so any
-trailing metadata (ie. XMP written by some utilities) may be missed.  When
-combined with the ScanForXMP option, prevents scanning for XMP in recognized
-file types.  With a value of 2, ExifTool will also avoid extracting any EXIF
-MakerNote information.  Default is 0.
-
-=item FixBase
-
-Fix maker notes base offset.  A common problem with image editing software
-is that offsets in the maker notes are not adjusted properly when the file
-is modified.  This may cause the wrong values to be extracted for some maker
-note entries when reading the edited file.  FixBase specifies an integer
-value to be added to the maker notes base offset.  It may also be set to the
-empty string ('') for ExifTool will take its best guess at the correct base,
-or undef (the default) for no base adjustment.
-
-=item GeoMaxIntSecs
-
-Maximum interpolation time in seconds for geotagging.  Geotagging is treated
-as an extrapolation if the Geotime value lies between two fixes in the same
-track which are separated by a number of seconds greater than this. 
-Otherwise, the coordinates are calculated as a linear interpolation between
-the two nearest fixes.  Default is 1800.
-
-=item GeoMaxExtSecs
-
-Maximum extrapolation time in seconds for geotagging.  Geotagging fails if
-the Geotime value lies outside a GPS track by a number of seconds greater
-than this.  Otherwise, the coordinates of the nearest fix are taken. 
-Default is 1800.
-
-=item GeoMaxHDOP
-
-Maximum Horizontal (2D) Dilution Of Precision for geotagging.  GPS fixes are
-ignored if the HDOP is greater than this.  Default is undef.
-
-=item GeoMaxPDOP
-
-Maximum Position (3D) Dilution Of Precision for geotagging.  GPS fixes are
-ignored if the PDOP is greater than this.  Default is undef.
-
-=item GeoMinSats
-
-Minimum number of satellites for geotagging.  GPS fixes are ignored if the
-number of acquired satellites is less than this.  Default is undef.
-
-=item GlobalTimeShift
-
-Time shift to apply to all extracted date/time PrintConv values.  Does not
-affect ValueConv values.  Value is a date/time shift string (see
-L<Image::ExifTool::Shift.pl|Image::ExifTool::Shift.pl>), with a leading '-'
-for negative shifts.  Default is undef.
-
-=item Group#
-
-Extract tags only for specified groups in family # (Group0 assumed if #
-not given).  The option value may be a single group name or a reference
-to a list of groups.  Case is significant in group names.  Specify a group
-to be excluded by preceding group name with a '-'.  See L</GetGroup> for a
-description of group families, and L</GetAllGroups [static]> for lists of
-group names.
-
-=item HtmlDump
-
-Dump information in hex to dynamic HTML web page.  The value may be 0-3 for
-increasingly larger limits on the maximum block size.  Default is 0.  Output
-goes to the file specified by the TextOut option (\*STDOUT by default).
-
-=item HtmlDumpBase
-
-Base for HTML dump offsets.  If not defined, the EXIF/TIFF base offset is
-used.  Set to 0 for absolute offsets.  Default is undef.
-
-=item IgnoreMinorErrors
-
-Flag to ignore minor errors.  Causes minor errors to be downgraded to
-warnings, and minor warnings to be ignored.  This option is provided mainly
-to allow writing of files when minor errors occur, but by ignoring some
-minor warnings the behaviour of ExifTool may be changed to allow some
-questionable operations to proceed (such as extracting thumbnail and preview
-images even if they don't have a recognizable header).  Minor
-errors/warnings are denoted by '[minor]' at the start of the message.
-
-=item Lang
-
-Localized language for exiftool tag descriptions, etc.  Available languages
-are given by the Image::ExifTool::Lang module names (ie. 'fr', 'zh_cn').  If
-the specified language isn't available, the option is not changed.  May be
-set to undef to select the built-in default language.  Default is 'en'.
-
-=item LargeFileSupport
-
-Flag to indicate that 64-bit file offsets are supported on this system.
-Default is 0.
-
-=item List
-
-Flag to extract lists of PrintConv values into arrays instead of joining
-them into a string of values.  The L</ListSep> option specifies the
-separator used when combining values.  Default is 0.
-
-=item ListSep
-
-Separator string used to join lists of PrintConv values when L</List> option
-is not set.  Default is ', '.
-
-=item ListSplit
-
-Regular expression used to split values of list-type tags into individual
-items when writing.  (ie. use ',\\s*' to split a comma-separated list.) 
-Default is undef.
-
-=item MakerNotes
-
-Option to extract MakerNotes and other writable subdirectories (such as
-PrintIM) as a data block.  Normally when the MakerNotes are extracted they
-are rebuilt to include data outside the boundaries of the original maker
-note data block, but a value of 2 disables this feature.  Possible values
-are:
-
-  0 - Do not extract writable subdirectories (default)
-  1 - Extract and rebuild maker notes into self-contained block
-  2 - Extract without rebuilding maker notes
-
-=item MissingTagValue
-
-Value for missing tags in expressions evaluated by L</SetNewValuesFromFile>.
-If not set, a minor error is issued for missing values, or the value is set
-to '' if L</IgnoreMinorErrors> is set.  Default is undef.
-
-=item Password
-
-Password for reading/writing password-protected PDF documents.  Ignored if a
-password is not required.  Character encoding of the password is determined
-by the value of the Charset option at processing time.  Default is undef.
-
-=item PrintConv
-
-Flag to enable automatic print conversion.  Also enables inverse
-print conversion for writing.  Default is 1.
-
-=item QuickTimeUTC
-
-Flag set to assume that QuickTime date/time values are stored as UTC,
-causing conversion to local time when they are extracted.  According to the
-QuickTime specification date/time values should be UTC, but many digital
-cameras store local time instead (presumably because they don't know the
-time zone), so the default is 0.
-
-=item ScanForXMP
-
-Flag for scan all files (even unrecognized formats) for XMP information
-unless XMP was already found in the file.  When combined with the FastScan
-option, only unrecognized file types are scanned for XMP.  Default is 0.
-
-=item Sort
-
-Specifies order to sort tags in returned list:
-
-  Input  - Sort in same order as input tag arguments (default)
-  File   - Sort in order that tags were found in the file
-  Tag    - Sort alphabetically by tag name
-  Descr  - Sort by tag description (for current Lang setting)
-  Group# - Sort by tag group, where # is zero or more family
-           numbers separated by colons. If # is not specified,
-           Group0 is assumed.  See GetGroup for a description
-           of group families.
-
-=item Sort2
-
-Secondary sort order used for tags within each group when Sort is 'Group':
-
-  File   - Sort in order tags were found in the file (default)
-  Tag    - Sort alphabetically by tag name
-  Descr  - Sort by tag description (for current Lang setting)
-
-=item StrictDate
-
-Flag to return undefined value for any date which can't be converted when
-the DateFormat option is used.  Default is undef.
-
-=item Struct
-
-Flag to return XMP structures as hash references instead of flattening into
-individual tags.  Has no effect when writing since both flattened and
-structured tags may always be written.  Possible values are:
-
-  undef - Same as 0 for reading, 2 for copying
-    0   - Read/copy flattened tags
-    1   - Read/copy structured tags
-    2   - Read/copy both flattened and structured tags, but flag
-          flattened tags as "unsafe" for copying
-
-=item TextOut
-
-Output file reference for Verbose and HtmlDump options.  Default is
-\*STDOUT.
-
-=item Unknown
-
-Flag to get the values of unknown tags.  If set to 1, unknown tags are
-extracted from EXIF (or other tagged-format) directories.  If set to 2,
-unknown tags are also extracted from binary data blocks.  Default is 0.
-
-=item Verbose
-
-Print verbose messages to file specified by TextOut option.  Value may be
-from 0 to 5 for increasingly verbose messages.  Default is 0.  With the
-verbose option set, messages are printed to the console as the file is
-parsed.  Level 1 prints the tag names and raw values.  Level 2 adds more
-details about the tags.  Level 3 adds a hex dump of the tag data, but with
-limits on the number of bytes dumped.  Levels 4 and 5 remove the dump limit
-on tag values and JPEG segment data respectively.
-
-=item XMPAutoConv
-
-Flag to enable automatic conversion for unknown XMP tags with values that
-look like rational numbers or dates.  Default is 1.
-
-=back
-
-=item Return Values:
-
-The original value of the last specified parameter.
-
-=back
-
-=head2 ClearOptions
-
-Reset all options to their default values.  Loads user-defined default
-option values from the %Image::ExifTool::UserDefined::Options hash in the
-.ExifTool_config file if it exists.
-
-    $exifTool->ClearOptions();
-
-=over 4
-
-=item Inputs:
-
-0) ExifTool object reference
-
-=item Return Values:
-
-(none)
-
-=back
-
-=head2 ExtractInfo
-
-Extract all meta information from an image.
-
-    $success = $exifTool->ExtractInfo('image.jpg', \%options);
-
-=over 4
-
-=item Inputs:
-
-L</ExtractInfo> takes exactly the same arguments as L</ImageInfo>.  The only
-difference is that a list of tag keys is not returned if an ARRAY reference
-is given.  The following options are effective in the call to
-L</ExtractInfo>:
-
-Binary, Charset, CharsetEXIF, CharsetID3, CharsetIPTC, CharsetPhotoshop,
-CharsetQuickTime, Composite, ExtractEmbedded, FastScan, FixBase, HtmlDump,
-HtmlDumpBase, IgnoreMinorErrors, Lang, LargeFileSupport, MakerNotes,
-ScanForXMP, Struct, TextOut, Unknown and Verbose.
-
-=item Return Value:
-
-1 if this was a recognized file format, 0 otherwise (and 'Error' tag set).
-
-=back
-
-=head2 GetInfo
-
-L</GetInfo> is called to return meta information after it has been extracted
-from the image by a previous call to L</ExtractInfo> or L</ImageInfo>. This
-function may be called repeatedly after a single call to L</ExtractInfo> or
-L</ImageInfo>.
-
-    # get image width and height only
-    $info = $exifTool->GetInfo('ImageWidth', 'ImageHeight');
-
-    # get information for all tags in list (list updated with tags found)
-    $info = $exifTool->GetInfo(\@ioTagList);
-
-    # get all information in Author or Location groups
-    $info = $exifTool->GetInfo({Group2 => ['Author', 'Location']});
-
-=over 4
-
-=item Inputs:
-
-Inputs are the same as L</ExtractInfo> and L</ImageInfo> except that an
-image can not be specified.  Options in effect are:
-
-Charset, CoordFormat, DateFormat, Duplicates, Escape, Exclude, Group#,
-GlobalTimeShift, Lang, List, ListSep, PrintConv, Sort (if a tag list
-reference is given) and StrictDate.
-
-=item Return Value:
-
-Reference to information hash, the same as with L</ImageInfo>.
-
-=back
-
-=head2 WriteInfo
-
-Write meta information to a file.  The specified source file is rewritten to
-the same-type destination file with new information as specified by previous
-calls to L</SetNewValue>.  The necessary segments and/or directories are
-created in the destination file as required to store the specified
-information.  May be called repeatedly to write the same information to
-additional files without the need to call L</SetNewValue> again.
-
-    # add information to a source file, writing output to new file
-    $exifTool->WriteInfo($srcfile, $dstfile);
-
-    # create XMP data file from scratch
-    $exifTool->WriteInfo(undef, $dstfile, 'XMP');
-
-    # overwrite file (you do have backups, right?)
-    $exifTool->WriteInfo($srcfile);
-
-=over 4
-
-=item Inputs:
-
-0) ExifTool object reference
-
-1) Source file name, file reference, scalar reference, or undef to create a
-file from scratch
-
-2) [optional] Destination file name, file reference, scalar reference, or
-undef to overwrite the original file
-
-3) [optional] Destination file type
-
-=item Return Value:
-
-1 if file was written OK, 2 if file was written but no changes made, 0 on
-file write error.
-
-If an error code is returned, an Error tag is set and GetValue('Error') can
-be called to obtain the error description.  A Warning tag may be set even if
-this routine is successful.  Calling WriteInfo clears any pre-existing Error
-and Warning tags.
-
-    $errorMessage = $exifTool->GetValue('Error');
-    $warningMessage = $exifTool->GetValue('Warning');
-
-=item Notes:
-
-The source file name may be undefined to create a file from scratch
-(currently only XMP, MIE, ICC, VRD and EXIF files can be created in this way
--- see L</CanCreate> for details).  If undefined, the destination file type
-is required unless the type can be determined from the destination file
-name.
-
-If a destination file name is given, the specified file must not exist
-because an existing destination file will not be overwritten.  The
-destination file name may be undefined to overwrite the original file (make
-sure you have backups!).  In this case, if a source file name is provided, a
-temporary file is created and renamed to replace the source file if no
-errors occurred while writing.  Otherwise, if a source file reference or
-scalar reference is used, the image is first written to memory then copied
-back to replace the original if there were no errors.
-
-The destination file type is only used if the source file is undefined.
-
-On Mac OS systems, the file resource fork is preserved if this routine is
-called with a source file name.
-
-=back
-
-The following ExifTool options are effective in the call to L</WriteInfo>:
-
-ByteOrder, Charset, CharsetEXIF, CharsetIPTC, Compact, Compress, FixBase,
-IgnoreMinorErrors and Verbose.
-
-=head2 CombineInfo
-
-Combine information from more than one information hash into a single hash.
-
-    $info = $exifTool->CombineInfo($info1, $info2, $info3);
-
-=over 4
-
-=item Inputs:
-
-0) ExifTool object reference
-
-1-N) Information hash references
-
-=back
-
-If the Duplicates option is disabled and duplicate tags exist, the order of
-the hashes is significant.  In this case, the value used is the first value
-found as the hashes are scanned in order of input.  The Duplicates option
-is the only option that is in effect for this function.
-
-=head2 GetTagList
-
-Get a sorted list of tags from the specified information hash or tag list.
-
-    @tags = $exifTool->GetTagList($info, 'Group0');
-
-=over 4
-
-=item Inputs:
-
-0) ExifTool object reference,
-
-1) [optional] Information hash reference or tag list reference,
-
-2) [optional] Sort order ('Input', 'File', 'Tag', 'Descr' or 'Group#').
-
-3) [optional] Secondary sort order ('File', 'Tag' or 'Descr').
-
-If the information hash or tag list reference is not provided, then the list
-of found tags from the last call to L</ImageInfo>, L</ExtractInfo> or
-L</GetInfo> is used instead, and the result is the same as if
-L</GetFoundTags> was called.  If sort order is not specified, the sort order
-is taken from the current options settings.
-
-=item Return Values:
-
-A list of tag keys in the specified order.
-
-=back
-
-=head2 GetFoundTags
-
-Get list of found tags in specified sort order.  The found tags are the tags
-for the information obtained from the most recent call to L</ImageInfo>,
-L</ExtractInfo> or L</GetInfo> for this object.
-
-    @tags = $exifTool->GetFoundTags('File');
-
-=over 4
-
-=item Inputs:
-
-0) ExifTool object reference
-
-1) [optional] Sort order ('Input', 'File', 'Tag', 'Descr' or 'Group#')
-
-2) [optional] Secondary sort order ('File', 'Tag' or 'Descr')
-
-If sort order is not specified, the sort order from the ExifTool options is
-used.
-
-=item Return Values:
-
-A list of tag keys in the specified order.
-
-=back
-
-=head2 GetRequestedTags
-
-Get list of requested tags.  These are the tags that were specified in the
-arguments of the most recent call to L</ImageInfo>, L</ExtractInfo> or
-L</GetInfo>, including tags specified via a tag list reference. Shortcut
-tags are expanded in the list.
-
-    @tags = $exifTool->GetRequestedTags();
-
-=over 4
-
-=item Inputs:
-
-(none)
-
-=item Return Values:
-
-List of requested tag keys in the same order that the tags were specified.
-Note that this list will be empty if tags were not specifically requested
-(ie. If extracting all tags).
-
-=back
-
-=head2 GetValue
-
-Get the value of a specified tag.  The returned value is either the
-human-readable (PrintConv) value, the converted machine-readable (ValueConv)
-value, or the original raw (Raw) value.  If the value type is not specified,
-the PrintConv value is returned if the PrintConv option is set, otherwise
-the ValueConv value is returned.  The PrintConv values are same as the
-values returned by L</ImageInfo> and L</GetInfo> in the tag/value hash
-unless the PrintConv option is disabled.
-
-Tags which represent lists of multiple values (as may happen with 'Keywords'
-for example) are handled specially.  In scalar context, the returned
-PrintConv value for these tags is either a string of values or a list
-reference (depending on the List option setting), and the ValueConv value is
-always a list reference.  But in list context, L</GetValue> always returns
-the list itself.
-
-Note that L</GetValue> requires a case-sensitive tag key as an argument.  To
-retrieve tag information based on a case-insensitive tag name (with an
-optional group specifier), use L</GetInfo> instead.
-
-    # PrintConv example
-    my $val = $exifTool->GetValue($tag);
-    if (ref $val eq 'SCALAR') {
-        print "$tag = (unprintable value)\n";
-    } else {
-        print "$tag = $val\n";
-    }
-
-    # ValueConv examples
-    my $val = $exifTool->GetValue($tag, 'ValueConv');
-    if (ref $val eq 'ARRAY') {
-        print "$tag is a list of values\n";
-    } elsif (ref $val eq 'SCALAR') {
-        print "$tag represents binary data\n";
-    } else {
-        print "$tag is a simple scalar\n";
-    }
-
-    my @keywords = $exifTool->GetValue('Keywords', 'ValueConv');
-
-The following options are in effect when L</GetValue> is called:
-
-Charset, CoordFormat, DateFormat, Escape, GlobalTimeShift, Lang, List,
-ListSep, PrintConv and StrictDate.
-
-=over 4
-
-=item Inputs:
-
-0) ExifTool object reference
-
-1) Tag key
-
-2) [optional] Value type, 'PrintConv', 'ValueConv', 'Both' or 'Raw'
-
-The default value type is 'PrintConv' if the PrintConv option is set,
-otherwise the default is 'ValueConv'.  A value type of 'Both' returns both
-ValueConv and PrintConv values as a list.
-
-=item Return Values:
-
-The value of the specified tag.  If the tag represents a list of values and
-the List option is disabled then PrintConv returns a string of values,
-otherwise a reference to the list is returned in scalar context.  The list
-itself is returned in list context.  Values may also be scalar references to
-binary data, or hash references if the L</Struct> option is set.
-
-Note: It is possible for L</GetValue> to return an undefined ValueConv or
-PrintConv value (or an empty list in list context) even if the tag exists,
-since it is possible for these conversions to yield undefined values.
-
-=back
-
-=head2 SetNewValue
-
-Set the new value for a tag.  The routine may be called multiple times to
-set the values of many tags before using L</WriteInfo> to write the new
-values to an image.
-
-For list-type tags (like Keywords), either call repeatedly with the same tag
-name for each value, or call with a reference to the list of values.
-
-    # set a new value for a tag (errors go to STDERR)
-    $success = $exifTool->SetNewValue($tag, $value);
-
-    # set a new value and capture any error message
-    ($success, $errStr) = $exifTool->SetNewValue($tag, $value);
-
-    # delete information for specified tag if it exists in image
-    # (also resets AddValue and DelValue options for this tag)
-    $exifTool->SetNewValue($tag);
-
-    # reset all values from previous calls to SetNewValue()
-    $exifTool->SetNewValue();
-
-    # delete a specific keyword
-    $exifTool->SetNewValue('Keywords', $word, DelValue => 1);
-
-    # set keywords (a list-type tag) with two new values
-    $exifTool->SetNewValue(Keywords => 'word1');
-    $exifTool->SetNewValue(Keywords => 'word2');
-    # equivalent, but set both in one call using an array reference
-    $exifTool->SetNewValue(Keywords => ['word1','word2']);
-
-    # add a keyword without replacing existing keywords in the file
-    $exifTool->SetNewValue(Keywords => $word, AddValue => 1);
-
-    # set a tag in a specific group
-    $exifTool->SetNewValue(Headline => $val, Group => 'XMP');
-    $exifTool->SetNewValue('XMP:Headline' => $val);  # (equivalent)
-
-    # shift original date/time back by 2.5 hours
-    $exifTool->SetNewValue(DateTimeOriginal => '2:30', Shift => -1);
-
-    # write a tag only if it had a specific value
-    # (the order of the following calls is not significant)
-    $exifTool->SetNewValue(Title => $oldVal, DelValue => 1);
-    $exifTool->SetNewValue(Title => $newVal);
-
-    # write tag by numerical value
-    $exifTool->SetNewValue(Orientation => 6, Type => 'ValueConv');
-    $exifTool->SetNewValue('Orientation#' => 6);  # (equivalent)
-
-    # delete all but EXIF tags
-    $exifTool->SetNewValue('*');  # delete all...
-    $exifTool->SetNewValue('EXIF:*', undef, Replace => 2); # ...but EXIF
-
-    # write structured information as a HASH reference
-    $exifTool->SetNewValue('XMP:Flash' => {
-        mode   => 'on',
-        fired  => 'true',
-        return => 'not'
-    });
-
-    # write structured information as a serialized string
-    $exifTool->SetNewValue('XMP:Flash'=>'{mode=on,fired=true,return=not}');
-
-(See L<http://owl.phy.queensu.ca/~phil/exiftool/struct.html#Serialize> for
-a description of the structure serialization technique.)
-
-=over 4
-
-=item Inputs:
-
-0) ExifTool object reference
-
-1) [optional] Tag key or tag name, or undef to clear all new values.  A tag
-name of '*' can be used when deleting tags to delete all tags, or all tags
-in a specified group.  The tag name may be prefixed by group name, separated
-by a colon (ie. 'EXIF:Artist'), which is equivalent to using a Group option
-argument.  Also, a '#' may be appended to the tag name (ie.
-'EXIF:Orientation#'), with the same effect as setting Type to 'ValueConv'.
-
-2) [optional] New value for tag.  Undefined to delete tag from file.  May be
-a scalar, scalar reference, list reference to set a list of values, or hash
-reference for a structure.  Integer values may be specified as a hexadecimal
-string (with a leading '0x'), and simple rational values may be specified in
-fractional form (ie. '4/10').  Structure tags may be specified either as a
-hash reference or a serialized string (see the last two examples above).
-
-3-N) [optional] SetNewValue option/value pairs (see below).
-
-=item SetNewValue Options:
-
-=over 4
-
-=item AddValue
-
-Specifies that the value be added to an existing list rather than
-overwriting.  Valid settings are 0 (overwrite any existing tag value), 1
-(add to an existing list and warn for non-list tags) or 2 (add to existing
-list and overwrite non-list tags).  Default is 0.
-
-=item DelValue
-
-Delete the existing tag if it has the specified value.  Valid values are
-0 or 1.  Default is 0.
-
-=item EditGroup
-
-Create tags in existing groups only.  Don't create new group.  Valid values
-are 0 and 1.  Default is 0.
-
-=item EditOnly
-
-Edit tag only if it already exists.  Don't create new tag.  Valid values are
-0 and 1.  Default is 0.
-
-=item Group
-
-Specifies group name where tag should be written.  If not specified, tag is
-written to highest priority group as specified by L</SetNewGroups>.  Any
-family 0 or 1 group name may be used.  Case is not significant.
-
-=item NoFlat
-
-Treat flattened tags as 'unsafe'.
-
-=item NoShortcut
-
-Disables default behaviour of looking up tag in shortcuts if not found
-otherwise.
-
-=item Protected
-
-Bit mask for tag protection levels to write.  Bit 0x01 allows writing of
-'unsafe' tags (ie. tags not copied automatically via
-L</SetNewValuesFromFile>).  Bit 0x02 allows writing of 'protected' tags, and
-should only be used internally by ExifTool.  See
-L<Image::ExifTool::TagNames|Image::ExifTool::TagNames>, for a list of tag
-names indicating 'unsafe' and 'protected' tags.  Default is 0.
-
-=item ProtectSaved
-
-Avoid setting new values which were saved after the Nth call to
-L</SaveNewValues>.  Has no effect on unsaved values, or values saved before
-Nth call.  Option value is N.  Default is undef.
-
-=item Replace
-
-Flag to replace the previous new values for this tag (ie. replace the values
-set in previous calls to L</SetNewValue>).  This option is most commonly
-used to replace previously-set new values for list-type tags.  Valid values
-are 0 (set new value normally -- adds to new values for list-type tags), 1
-(reset previous new values for this tag and replace with the specified new
-value) or 2 (reset previous new values only).
-
-=item Shift
-
-Shift the tag by the specified value.  Currently only date/time tags and
-tags with numerical values may be shifted.  Undefined for no shift, 1 for a
-positive shift, or -1 for a negative shift.  A value of 0 causes a positive
-shift to be applied if the tag is shiftable and AddValue is set, or a
-negative shift for date/time tags only if DelValue is set. Default is undef.
-See L<Image::ExifTool::Shift.pl|Image::ExifTool::Shift.pl> for more
-information.
-
-=item Type
-
-The type of value being set.  Valid values are PrintConv, ValueConv or Raw.
-Default is PrintConv if the L</PrintConv> Option is set, otherwise
-ValueConv.
-
-=back
-
-=item Return Values:
-
-In scalar context, returns the number of tags set and error messages are
-printed to STDERR.  In list context, returns the number of tags set, and the
-error string (which is undefined if there was no error).
-
-=item Notes:
-
-When deleting groups of tags, the Replace option may be used as in the last
-example above to exclude specific groups from a mass delete.  However, this
-technique may not be used to exclude individual tags.  Instead, use
-L</SetNewValuesFromFile> to recover the values of individual tags after
-deleting a group.
-
-When deleting all tags from a JPEG image, the APP14 "Adobe" information is
-not deleted by default because doing so may affect the appearance of the
-image.  However, this information may be deleted by specifying it
-explicitly, either by group (with 'Adobe:*') or as a block (with 'Adobe').
-
-=back
-
-The following ExifTool options are effective in the call to L</SetNewValue>:
-
-Charset, Escape, IgnoreMinorErrors, Lang, ListSep, ListSplit, PrintConv and
-Verbose.
-
-=head2 SetNewValuesFromFile
-
-A very powerful routine that sets new values for tags from information found
-in a specified file.
-
-    # set new values from all information in a file...
-    my $info = $exifTool->SetNewValuesFromFile($srcFile);
-    # ...then write these values to another image
-    my $result = $exifTool->WriteInfo($file2, $outFile);
-
-    # set all new values, preserving original groups
-    $exifTool->SetNewValuesFromFile($srcFile, '*:*');
-
-    # set specific information
-    $exifTool->SetNewValuesFromFile($srcFile, @tags);
-
-    # set new value from a different tag in specific group
-    $exifTool->SetNewValuesFromFile($fp, 'IPTC:Keywords>XMP-dc:Subject');
-
-    # add all IPTC keywords to XMP subject list
-    $exifTool->SetNewValuesFromFile($fp, 'IPTC:Keywords+>XMP-dc:Subject');
-
-    # set new value from an expression involving other tags
-    $exifTool->SetNewValuesFromFile($file,
-        'Comment<ISO=$ISO Aperture=$aperture Exposure=$shutterSpeed');
-
-    # set keywords list from the values of multiple tags
-    $exifTool->SetNewValuesFromFile($file, { Replace => 0 },
-        'keywords<xmp:subject', 'keywords<filename');
-
-    # copy all EXIF information, preserving the original IFD
-    # (without '>*.*' tags would be copied to the preferred EXIF IFD)
-    $exifTool->SetNewValuesFromFile($file, 'EXIF:*>*:*');
-
-=over 4
-
-=item Inputs:
-
-0) ExifTool object reference
-
-1) File name, file reference, or scalar reference
-
-2-N) [optional] List of tag names to set or options hash references.  All
-writable tags are set if none are specified.  The tag names are not case
-sensitive, and may be prefixed by an optional family 0 or 1 group name,
-separated by a colon (ie. 'exif:iso').  A leading '-' indicates tags to be
-excluded (ie. '-comment'), or a trailing '#' causes the ValueConv value to
-be copied (same as setting the Type option to 'ValueConv' for this tag
-only).  An asterisk ('*') may be used for the tag name, and is useful when a
-group is specified to set all tags from a group (ie. 'XMP:*').  A special
-feature allows tag names of the form 'SRCTAG>DSTTAG' (or
-'DSTTAGE<lt>SRCTAG') to be specified to copy information to a tag with a
-different name or a specified group. Both 'SRCTAG' and 'DSTTAG' may use '*'
-and/or be prefixed by a group name (ie. 'modifyDate>fileModifyDate' or
-'*>xmp:*'), and/or suffixed by a '#' to disable print conversion.  Copied
-tags may also be added or deleted from a list with arguments of the form
-'SRCTAG+>DSTTAG' or 'SRCTAG->DSTTAG'.  Tags are evaluated in order, so
-exclusions apply only to tags included earlier in the list.  An extension of
-this feature allows the tag value to be set from an expression containing
-tag names with leading '$' symbols (ie. 'CommentE<lt>the file is
-$filename'). Braces '{}' may be used around the tag name to separate it from
-subsequent text, and a '$$' is used to to represent a '$' symbol.  (The
-behaviour for missing tags in expressions is defined by the
-L</MissingTagValue> option.)  Multiple options hash references may be passed
-to set different options for different tags. Options apply to subsequent
-tags in the argument list.
-
-By default, this routine will commute information between same-named tags in
-different groups, allowing information to be translated between images with
-different formats.  This behaviour may be modified by specifying a group
-name for extracted tags (even if '*' is used as a group name), in which case
-the information is written to the original group, unless redirected to a
-different group.  When '*' is used for a group name, the family 1 group of
-the original tag is preserved.  (For example, specifying '*:*' copies all
-information while preserving the original family 1 groups.)
-
-=item SetNewValuesFromFile Options:
-
-The options are the same was for L</SetNewValue>, and are passed directly
-to L</SetNewValue> internally, with a few exceptions:
-
-- The Replace option defaults to 1 instead of 0 as with L</SetNewValue>.
-
-- The AddValue or DelValue option is set for individual tags if '+>' or '->'
-(or '+E<lt>' or '-E<lt>') are used.
-
-- The Group option is set for tags where a group name is given.
-
-- The Protected flag is set to 1 for individually specified tags.
-
-- The Type option also applies to extracted tags.
-
-=item Return Values:
-
-A hash of information that was set successfully.  May include Warning or
-Error entries if there were problems reading the input file.
-
-=item Notes:
-
-The PrintConv option applies to this routine, but it normally should be left
-on to provide more reliable transfer of information between groups.
-
-If a preview image exists, it is not copied.  The preview image must be
-transferred separately if desired, in a separate call to L</WriteInfo>
-
-When simply copying all information between files of the same type, it is
-usually desirable to preserve the original groups by specifying '*:*' for
-the tags to set.
-
-The L</Duplicates> option is always in effect for tags extracted from the
-source file using this routine.
-
-The L</Struct> option is enabled by default for tags extracted by this
-routine.  This allows the hierarchy of complex structures to be preserved
-when copying, but the Struct option may be set to 0 to override this
-behaviour and copy as flattened tags instead.
-
-=back
-
-=head2 GetNewValues
-
-Get list of new Raw values for the specified tag.  These are the values
-that will be written to file.  Only tags which support a 'List' may return
-more than one value.
-
-    $rawVal = $exifTool->GetNewValues($tag);
-
-    @rawVals = $exifTool->GetNewValues($tag);
-
-=over 4
-
-=item Inputs:
-
-0) ExifTool object reference
-
-1) Tag name (case sensitive, may be prefixed by family 0 or 1 group name)
-
-=item Return Values:
-
-List of new Raw tag values, or first value in list when called in scalar
-context.  The list may be empty either if the tag isn't being written, or if
-it is being deleted (ie. if L</SetNewValue> was called without a value).
-
-=back
-
-=head2 CountNewValues
-
-Return the total number of new values set.
-
-    $numSet = $exifTool->CountNewValues();
-    ($numSet, $numPseudo) = $exifTool->CountNewValues();
-
-=over 4
-
-=item Inputs:
-
-0) ExifTool object reference
-
-=item Return Values:
-
-In scalar context, returns the total number of tags with new values set.  In
-list context, also returns the number of "pseudo" tag values which have been
-set.  "Pseudo" tags are tags like FileName and FileModifyDate which are not
-contained within the file and can be changed without rewriting the file.
-
-=back
-
-=head2 SaveNewValues
-
-Save state of new values to be later restored by L</RestoreNewValues>.
-
-    $exifTool->SaveNewValues();         # save state of new values
-    $exifTool->SetNewValue(ISO => 100); # set new value for ISO
-    $exifTool->WriteInfo($src, $dst1);  # write ISO + previous new values
-    $exifTool->RestoreNewValues();      # restore previous new values
-    $exifTool->WriteInfo($src, $dst2);  # write previous new values only
-
-=over 4
-
-=item Inputs:
-
-0) ExifTool object reference
-
-=item Return Value:
-
-Count of the number of times this routine has been called since the last
-time the new values were reset.
-
-=back
-
-=head2 RestoreNewValues
-
-Restore new values to the settings that existed when L</SaveNewValues> was
-last called.  May be called repeatedly after a single call to
-L</SaveNewValues>.  See L</SaveNewValues> above for an example.
-
-=over 4
-
-=item Inputs:
-
-0) ExifTool object reference
-
-=item Return Value:
-
-None.
-
-=back
-
-=head2 SetFileModifyDate
-
-Set the file modification time from the new value of the FileModifyDate tag.
-
-    $exifTool->SetNewValue(FileModifyDate => '2000:01:02 03:04:05-05:00',
-                           Protected => 1);
-    $result = $exifTool->SetFileModifyDate($file);
-
-=over 4
-
-=item Inputs:
-
-0) ExifTool object reference
-
-1) File name
-
-2) [optional] Base time if applying shift (days before $^T)
-
-=item Return Value:
-
-1 if the time was changed, 0 if nothing was done, or -1 if there was an
-error setting the time.
-
-=item Notes:
-
-Equivalent to, but more efficient than calling L</WriteInfo> when only the
-FileModifyDate tag has been set.  If a timezone is not specified in the
-FileModifyDate value, local time is assumed.  When shifting FileModifyDate,
-the time of the original file is used unless an optional base time is
-specified.
-
-=back
-
-=head2 SetFileName
-
-Set the file name and directory.  If not specified, the new file name is
-derived from the new values of the FileName and Directory tags.  If the
-FileName tag contains a '/', then the file is renamed into a new directory.
-If FileName ends with '/', then it is taken as a directory name and the file
-is moved into the new directory.  The new value for the Directory tag takes
-precedence over any directory specified in FileName.
-
-    $result = $exifTool->SetFileName($file);
-    $result = $exifTool->SetFileName($file, $newName);
-
-=over 4
-
-=item Inputs:
-
-0) ExifTool object reference
-
-1) Current file name
-
-2) [optional] New file name
-
-=item Return Value:
-
-1 if the file name or directory was changed, 0 if nothing was done, or -1 if
-there was an error renaming the file.
-
-=item Notes:
-
-Will not overwrite existing files. New directories are created as necessary.
-
-=back
-
-=head2 SetNewGroups
-
-Set the order of the preferred groups when adding new information.  In
-subsequent calls to L</SetNewValue>, new information will be created in the
-first valid group of this list.  This has an impact only if the group is not
-specified when calling L</SetNewValue> and if the tag name exists in more
-than one group.  The default order is EXIF, IPTC then XMP.  Any family 0
-group name may be used.  Case is not significant.
-
-    $exifTool->SetNewGroups('XMP','EXIF','IPTC');
-
-=over 4
-
-=item Inputs:
-
-0) ExifTool object reference
-
-1-N) Groups in order of priority.  If no groups are specified, the priorities
-are reset to the defaults.
-
-=item Return Value:
-
-None.
-
-=back
-
-=head2 GetNewGroups
-
-Get current group priority list.
-
-    @groups = $exifTool->GetNewGroups();
-
-=over 4
-
-=item Inputs:
-
-0) ExifTool object reference
-
-=item Return Values:
-
-List of group names in order of write priority.  Highest priority first.
-
-=back
-
-=head2 GetTagID
-
-Get the ID for the specified tag.  The ID is the IFD tag number in EXIF
-information, the property name in XMP information, or the data offset in a
-binary data block.  For some tags, such as Composite tags where there is no
-ID, an empty string is returned.  In list context, also returns a language
-code for the tag if available and different from the default language (ie.
-with alternate language entries for XMP "lang-alt" tags).
-
-    $id = $exifTool->GetTagID($tag);
-    ($id, $lang) = $exifTool->GetTagID($tag);
-
-=over 4
-
-=item Inputs:
-
-0) ExifTool object reference
-
-1) Tag key
-
-=item Return Values:
-
-In scalar context, returns the tag ID or '' if there is no ID for this tag.
-In list context, returns the tag ID (or '') and the language code (or
-undef).
-
-=back
-
-=head2 GetDescription
-
-Get description for specified tag.  This function will always return a
-defined value.  In the case where the description doesn't exist, one is
-generated from the tag name.
-
-=over 4
-
-=item Inputs:
-
-0) ExifTool object reference
-
-1) Tag key
-
-=item Return Values:
-
-A description for the specified tag.
-
-=back
-
-=head2 GetGroup
-
-Get group name(s) for a specified tag.
-
-    # return family 0 group name (ie. 'EXIF');
-    $group = $exifTool->GetGroup($tag, 0);
-
-    # return all groups (ie. qw{EXIF IFD0 Author Main})
-    @groups = $exifTool->GetGroup($tag);
-
-    # return groups as a string (ie. 'Main:IFD0:Author')
-    $group = $exifTool->GetGroup($tag, ':3:1:2');
-
-    # return groups as a simplified string (ie. 'IFD0:Author')
-    $group = $exifTool->GetGroup($tag, '3:1:2');
-
-=over 4
-
-=item Inputs:
-
-0) ExifTool object reference
-
-1) Tag key
-
-2) [optional] Group family number, or string of numbers separated by colons
-
-=item Return Values:
-
-Group name (or '' if tag has no group).  If no group family is specified,
-L</GetGroup> returns the name of the group in family 0 when called in scalar
-context, or the names of groups for all families in list context.  Returns a
-string of group names separated by colons if the input group family contains
-a colon.  The string is simplified to remove a leading 'Main:' and adjacent
-identical group names unless the family string begins with a colon.
-
-=item Notes:
-
-The group family numbers are currently available:
-
-    0) Information Type         (ie. EXIF, XMP, IPTC)
-    1) Specific Location        (ie. IFD0, XMP-dc)
-    2) Category                 (ie. Author, Time)
-    3) Document Number          (ie. Main, Doc1, Doc3-2)
-    4) Instance Number          (ie. Copy1, Copy2, Copy3...)
-
-Families 0 and 1 are based on the file structure, and are similar except
-that family 1 is more specific and sub-divides some groups to give more
-detail about the specific location where the information was found.  For
-example, the EXIF group is split up based on the specific IFD (Image File
-Directory), the MakerNotes group is divided into groups for each
-manufacturer, and the XMP group is separated based on the XMP namespace
-prefix.  Note that only common XMP namespaces are listed in the
-L<GetAllGroups documentation|/GetAllGroups [static]>, but additional
-namespaces may be present in some XMP data.  Also note that the 'XMP-xmp...'
-group names may appear in the older form 'XMP-xap...' since these names
-evolved as the XMP standard was developed.  The ICC_Profile group is broken
-down to give information about the specific ICC_Profile tag from which
-multiple values were extracted.  As well, information extracted from the
-ICC_Profile header is separated into the ICC-header group.
-
-Family 2 classifies information based on the logical category to which the
-information refers.
-
-Family 3 gives the document number for tags extracted from embedded
-documents, or 'Main' for tags from the main document.  (See the
-L</ExtractEmbedded> option for extracting tags from embedded documents.) 
-Nested sub-documents (if they exist) are indicated by numbers separated with
-dashes in the group name, to an arbitrary depth. (ie. 'Doc2-3-1' is the 1st
-sub-sub-document of the 3rd sub-document of the 2nd embedded document of the
-main file.)
-
-Family 4 provides a method for differentiating tags when multiple tags exist
-with the same name in the same location.  The primary instance of a tag (the
-tag extracted when the Duplicates option is disabled and no group is
-specified) has no family 4 group name, but additional instances have have
-family 4 group names of 'Copy1', 'Copy2', 'Copy3', etc.
-
-See L</GetAllGroups [static]> for complete lists of group names.
-
-=back
-
-=head2 GetGroups
-
-Get list of group names that exist in the specified information.
-
-    @groups = $exifTool->GetGroups($info, 2);
-    @groups = $exifTool->GetGroups('3:1');
-
-=over 4
-
-=item Inputs:
-
-0) ExifTool object reference
-
-1) [optional] Info hash ref (default is all extracted info)
-
-2) [optional] Group family number, or string of numbers (default 0)
-
-=item Return Values:
-
-List of group names in alphabetical order. If information hash is not
-specified, the group names are returned for all extracted information. See
-L</GetGroup> for an description of family numbers and family number strings.
-
-=back
-
-=head2 BuildCompositeTags
-
-Builds composite tags from required tags.  The composite tags are
-convenience tags which are derived from the values of other tags.  This
-routine is called automatically by L</ImageInfo> and L</ExtractInfo> if the
-Composite option is set.
-
-=over 4
-
-=item Inputs:
-
-0) ExifTool object reference
-
-=item Return Values:
-
-(none)
-
-=item Notes:
-
-Tag values are calculated in alphabetical order unless a tag Require's or
-Desire's another composite tag, in which case the calculation is deferred
-until after the other tag is calculated. Composite tags may need to read
-data from the image for their value to be determined, so for these
-L</BuildCompositeTags> must be called while the image is available.  This is
-only a problem if L</ImageInfo> is called with a filename (as opposed to a
-file reference or scalar reference) since in this case the file is closed
-before L</ImageInfo> returns.  However if you enable the Composite option,
-L</BuildCompositeTags> is called from within L</ImageInfo> before the file
-is closed.
-
-=back
-
-=head2 GetTagName [static]
-
-Get name of tag from tag key.  This is a convenience function that
-strips the embedded instance number, if it exists, from the tag key.
-
-Note: "static" in the heading above indicates that the function does not
-require an ExifTool object reference as the first argument.  All functions
-documented below are also static.
-
-    $tagName = Image::ExifTool::GetTagName($tag);
-
-=over 4
-
-=item Inputs:
-
-0) Tag key
-
-=item Return Value:
-
-Tag name.  This is the same as the tag key but has the instance number
-removed.
-
-=back
-
-=head2 GetShortcuts [static]
-
-Get a list of shortcut tags.
-
-=over 4
-
-=item Inputs:
-
-(none)
-
-=item Return Values:
-
-List of shortcut tags (as defined in Image::ExifTool::Shortcuts).
-
-=back
-
-=head2 GetAllTags [static]
-
-Get list of all available tag names.
-
-    @tagList = Image::ExifTool::GetAllTags($group);
-
-=over 4
-
-=item Inputs:
-
-0) [optional] Group name, or string of group names separated by colons
-
-=item Return Values:
-
-A list of all available tags in alphabetical order, or all tags in a
-specified group or intersection of groups.  The group name is case
-insensitive, and any group in families 0-2 may be used except for EXIF
-family 1 groups (ie. the specific IFD).
-
-=back
-
-=head2 GetWritableTags [static]
-
-Get list of all writable tag names.
-
-    @tagList = Image::ExifTool::GetWritableTags($group);
-
-=over 4
-
-=item Inputs:
-
-0) [optional] Group name, or string of group names separated by colons
-
-=item Return Values:
-
-A list of all writable tags in alphabetical order.  These are the tags for
-which values may be set through L</SetNewValue>.  If a group name is given,
-returns only writable tags in specified group(s).  The group name is case
-insensitive, and any group in families 0-2 may be used except for EXIF
-family 1 groups (ie. the specific IFD).
-
-=back
-
-=head2 GetAllGroups [static]
-
-Get list of all group names in specified family.
-
-    @groupList = Image::ExifTool::GetAllGroups($family);
-
-=over 4
-
-=item Inputs:
-
-0) Group family number (0-4)
-
-=item Return Values:
-
-A list of all groups in the specified family in alphabetical order.
-
-=back
-
-Here is a complete list of groups for each of these families:
-
-=over 4
-
-=item Family 0 (Information Type):
-
-AFCP, AIFF, APE, APP0, APP12, APP13, APP14, APP15, APP4, APP5, APP6, APP8,
-ASF, CanonVRD, Composite, DICOM, DNG, DV, DjVu, Ducky, EXE, EXIF, ExifTool,
-FLAC, File, Flash, FlashPix, Font, FotoStation, GIF, GIMP, GeoTiff, H264,
-HTML, ICC_Profile, ID3, IPTC, ITC, JFIF, JPEG, Jpeg2000, LNK, Leaf, M2TS,
-MIE, MIFF, MNG, MPC, MPEG, MPF, MXF, MakerNotes, Matroska, Meta, Ogg,
-OpenEXR, PDF, PICT, PNG, PSP, PhotoCD, PhotoMechanic, Photoshop, PostScript,
-PrintIM, QuickTime, RAF, RIFF, RSRC, RTF, Radiance, Rawzor, Real, SVG,
-SigmaRaw, Stim, Theora, Vorbis, XML, XMP, ZIP
-
-=item Family 1 (Specific Location):
-
-AC3, AFCP, AIFF, APE, ASF, AVI1, Adobe, AdobeCM, AdobeDNG, CIFF, Canon,
-CanonCustom, CanonRaw, CanonVRD, Casio, Chapter#, Composite, DICOM, DNG, DV,
-DjVu, DjVu-Meta, Ducky, EPPIM, EXE, EXIF, ExifIFD, ExifTool, FLAC, File,
-Flash, FlashPix, Font, FotoStation, FujiFilm, FujiIFD, GE, GIF, GIMP, GPS,
-GeoTiff, GlobParamIFD, GraphConv, H264, HP, HTML, HTML-dc, HTML-ncc,
-HTML-office, HTML-prod, HTML-vw96, HTTP-equiv, ICC-chrm, ICC-clrt,
-ICC-header, ICC-meas, ICC-meta, ICC-view, ICC_Profile, ICC_Profile#, ID3,
-ID3v1, ID3v1_Enh, ID3v2_2, ID3v2_3, ID3v2_4, IFD0, IFD1, IPTC, IPTC#, ITC,
-InteropIFD, JFIF, JPEG, JVC, Jpeg2000, KDC_IFD, Kodak, KodakBordersIFD,
-KodakEffectsIFD, KodakIFD, KyoceraRaw, LNK, Leaf, LeafSubIFD, Leica, M2TS,
-MAC, MIE-Audio, MIE-Camera, MIE-Canon, MIE-Doc, MIE-Extender, MIE-Flash,
-MIE-GPS, MIE-Geo, MIE-Image, MIE-Lens, MIE-Main, MIE-MakerNotes, MIE-Meta,
-MIE-Orient, MIE-Preview, MIE-Thumbnail, MIE-UTM, MIE-Unknown, MIE-Video,
-MIFF, MNG, MPC, MPEG, MPF0, MPImage, MXF, MakerNotes, MakerUnknown,
-Matroska, MetaIFD, Microsoft, Minolta, MinoltaRaw, NITF, Nikon,
-NikonCapture, NikonCustom, NikonScan, Ocad, Ogg, Olympus, OpenEXR, PDF,
-PICT, PNG, PSP, Panasonic, Pentax, PhotoCD, PhotoMechanic, Photoshop,
-PictureInfo, PostScript, PreviewIFD, PrintIM, ProfileIFD, Qualcomm,
-QuickTime, RAF, RAF2, RIFF, RMETA, RSRC, RTF, Radiance, Rawzor, Real,
-Real-CONT, Real-MDPR, Real-PROP, Real-RA3, Real-RA4, Real-RA5, Real-RJMD,
-Reconyx, Ricoh, SPIFF, SR2, SR2DataIFD, SR2SubIFD, SRF#, SVG, Samsung,
-Sanyo, Scalado, Sigma, SigmaRaw, Sony, SonyIDC, Stim, SubIFD, System,
-Theora, Track#, Version0, Vorbis, XML, XMP, XMP-DICOM, XMP-MP, XMP-MP1,
-XMP-PixelLive, XMP-acdsee, XMP-album, XMP-aux, XMP-cc, XMP-cell, XMP-crs,
-XMP-dc, XMP-dex, XMP-digiKam, XMP-exif, XMP-extensis, XMP-iptcCore,
-XMP-iptcExt, XMP-lr, XMP-mediapro, XMP-microsoft, XMP-mwg-coll, XMP-mwg-kw,
-XMP-mwg-rs, XMP-pdf, XMP-pdfx, XMP-photomech, XMP-photoshop, XMP-plus,
-XMP-prism, XMP-prl, XMP-pur, XMP-rdf, XMP-swf, XMP-tiff, XMP-x, XMP-xmp,
-XMP-xmpBJ, XMP-xmpDM, XMP-xmpMM, XMP-xmpNote, XMP-xmpPLUS, XMP-xmpRights,
-XMP-xmpTPg, ZIP
-
-=item Family 2 (Category):
-
-Audio, Author, Camera, Document, ExifTool, Image, Location, Other, Printing,
-Time, Unknown, Video
-
-=item Family 3 (Document Number):
-
-Doc#, Main
-
-=item Family 4 (Instance Number):
-
-Copy#
-
-=back
-
-=head2 GetDeleteGroups [static]
-
-Get list of all deletable group names.
-
-    @delGroups = Image::ExifTool::GetDeleteGroups();
-
-=over 4
-
-=item Inputs:
-
-None.
-
-=item Return Values:
-
-A list of deletable group names in alphabetical order.  The current list of
-deletable group names is:
-
-AFCP, CIFF, CanonVRD, EXIF, ExifIFD, Ducky, File, FlashPix, FotoStation,
-GlobParamIFD, GPS, IFD0, IFD1, InteropIFD, ICC_Profile, IPTC, JFIF,
-MakerNotes, Meta, MetaIFD, MIE, PhotoMechanic, Photoshop, PNG, PrintIM,
-RMETA, SubIFD, Trailer, XMP
-
-All names in this list are either family 0 or family 1 group names, with the
-exception of 'Trailer' which allows all trailers in JPEG and TIFF-format
-images to be deleted at once, including unknown trailers.  To schedule a
-group for deletion, call L</SetNewValue> with an undefined value and a tag
-name like 'Trailer:*'.
-
-=back
-
-=head2 GetFileType [static]
-
-Get type of file given file name.
-
-    my $type = Image::ExifTool::GetFileType($filename);
-    my $desc = Image::ExifTool::GetFileType($filename, 1);
-
-=over 4
-
-=item Inputs:
-
-0) [optional] File name (or just an extension)
-
-1) [optional] Flag to return a description instead of a type.  Set to 0 to
-return type for recognized but unsupported files (otherwise the return value
-for unsupported files is undef).
-
-=item Return Value:
-
-A string, based on the file extension, which indicates the basic format of
-the file.  Note that some files may be based on other formats (like many RAW
-image formats are based on TIFF).  In array context, may return more than
-one file type if the file may be based on different formats.  Returns undef
-if files with this extension are not yet supported by ExifTool.  Returns a
-list of extensions for all supported file types if no input extension is
-specified (or all recognized file types if the description flag is set to 0). 
-Returns a more detailed description of the specific file format when the
-description flag is set.
-
-=back
-
-=head2 CanWrite [static]
-
-Can the specified file be written?
-
-    my $writable = Image::ExifTool::CanWrite($filename);
-
-=over 4
-
-=item Inputs:
-
-0) File name or extension
-
-=item Return Value:
-
-True if ExifTool supports writing files of this type (based on the file
-extension).
-
-=back
-
-=head2 CanCreate [static]
-
-Can the specified file be created?
-
-    my $creatable = Image::ExifTool::CanCreate($filename);
-
-=over 4
-
-=item Inputs:
-
-0) File name or extension
-
-=item Return Value:
-
-True if ExifTool can create files with this extension from scratch. 
-Currently, this can only be done with XMP, MIE, ICC, VRD and EXIF files.
-
-=back
-
-=head1 CHARACTER ENCODINGS
-
-Certain meta information formats allow coded character sets other than plain
-ASCII.  When reading, most known encodings are converted to the external
-character set according to the L</Charset> option, or to UTF-8 by default.
-When writing, the inverse conversions are performed.
-
-A distinction is made between the external character set visible to via the
-ExifTool API, and the internal character used to store text in the metadata
-of a file.  These character sets may be specified separately as follows:
-
-=over 4
-
-=item External Character Set:
-
-The encoding for strings passed to/from ExifTool API functions.  This is set
-via the L</Charset> option, which is 'UTF8' by default.
-
-=item Internal Character Sets:
-
-The encodings used to store strings in the various metadata formats.  These
-encodings may be changed for certain types of metadata via the
-L</CharsetEXIF>, L</CharsetID3>, L</CharsetIPTC>, L</CharsetPhotoshop> and
-L</CharsetQuickTime> options.
-
-=back
-
-Values are returned as byte strings of encoded characters.  Perl wide
-characters are not used.  By default, most returned strings are encoded in
-UTF-8.  For these, Encode::decode_utf8() may be used to convert to a
-sequence of logical Perl characters.
-
-More specific details are given below about how character coding is handled
-for EXIF, IPTC, XMP, PNG, ID3, PDF, Photoshop, QuickTime, AIFF, MIE and
-Vorbis information:
-
-=head2 EXIF
-
-Most textual information in EXIF is stored in "ASCII" format (called
-"string" in the L<ExifTool tag name documentation|Image::ExifTool::TagNames>).
-By default ExifTool does not convert these strings.  However, it is not
-uncommon for applications to write UTF-8 or other encodings where ASCII is
-expected.  To deal with these, ExifTool allows the internal EXIF string
-encoding to be specified with L</CharsetEXIF>, which causes EXIF string
-values to be converted from the specified character set when reading, and
-stored with this character set when writing.  (The MWG recommends using
-UTF-8 encoding for EXIF strings, and in keeping with this the
-L<MWG|Image::ExifTool::MWG> module sets the default internal EXIF string
-encoding to UTF-8, but note that this will have no effect unless the
-external encoding is also set to something other than the default of UTF-8.)
-
-A few EXIF tags (UserComment, GPSProcessingMethod and GPSAreaInformation)
-support a designated internal text encoding, with values stored as ASCII,
-Unicode (UCS-2) or JIS.  When reading these tags, ExifTool converts Unicode
-and JIS to the external character set specified by the L</Charset>
-option, or to UTF-8 by default.  ASCII text is not converted. When writing,
-text is stored as ASCII unless the string contains special characters, in
-which case it is converted from the external character set (or UTF-8 by
-default), and stored as Unicode. ExifTool writes Unicode in native EXIF byte
-ordering by default, but the byte order may be specified by setting the
-ExifUnicodeByteOrder tag (see the
-L<Extra Tags documentation|Image::ExifTool::TagNames/Extra Tags>).
-
-The EXIF "XP" tags (XPTitle, XPComment, etc) are always stored as
-little-endian Unicode (UCS-2), and are read and written using the specified
-character set.
-
-=head2 IPTC
-
-The value of the IPTC:CodedCharacterSet tag determines how the internal IPTC
-string values are interpreted.  If CodedCharacterSet exists and has a value
-of 'UTF8' (or 'ESC % G') then string values are assumed to be stored as
-UTF-8, otherwise Windows Latin1 (cp1252, 'Latin') coding is assumed by
-default, but this can be changed with the L</CharsetIPTC> option.  When
-reading, these strings are converted to the character set specified by the
-L</Charset> option.  When writing, the inverse conversions are performed. 
-No conversion is done if the internal (IPTC) and external (ExifTool)
-character sets are the same.  Note that ISO 2022 character set shifting is
-not supported.  Instead, a warning is issued and the string is not converted
-if an ISO 2022 shift code is encountered.  See L<http://www.iptc.org/IIM/>
-for the official IPTC specification.
-
-Unless CodedCharacterSet is 'UTF8', applications have no reliable way to
-determine the IPTC character encoding.  For this reason, it is recommended
-that CodedCharacterSet be set to 'UTF8' when creating new IPTC.
-
-(Note: Here, "IPTC" Refers to the older IPTC IIM format.  The more recent
-IPTC Core and Extension specifications actually use the XMP format.)
-
-=head2 XMP
-
-Exiftool reads XMP encoded as UTF-8, UTF-16 or UTF-32, and converts them all
-to UTF-8 internally.  Also, all XML character entity references and numeric
-character references are converted.  When writing, ExifTool always encodes
-XMP as UTF-8, converting the following 5 characters to XML character
-references: E<amp> E<lt> E<gt> E<39> E<quot>.  By default no further
-conversion is performed, however if the L</Charset> option is other than
-'UTF8' then text is converted to/from a specified character set when
-reading/writing.
-
-=head2 PNG
-
-L<PNG TextualData tags|Image::ExifTool::TagNames/"PNG TextualData Tags"> are
-stored as tEXt, zTXt and iTXt chunks in PNG images.  The tEXt and zTXt
-chunks use ISO 8859-1 encoding, while iTXt uses UTF-8.  When reading,
-ExifTool converts all PNG textual data to the character set specified by the
-L</Charset> option.  When writing, ExifTool generates a tEXt chunk (or zTXt
-with the L</Compress> option) if the text doesn't contain special characters
-or if Latin encoding is specified; otherwise an iTXt chunk is used and the
-text is converted from the specified character set and stored as UTF-8.
-
-=head2 ID3
-
-The ID3v1 specification officially supports only ISO 8859-1 encoding (a
-subset of Windows Latin1), although some applications may incorrectly use
-other character sets.  By default ExifTool converts ID3v1 text from Latin to
-the character set specified by the L</Charset> option.  However, the
-internal ID3v1 charset may be specified with the L</CharsetID3> option.  The
-encoding for ID3v2 information is stored in the file, so ExifTool converts
-ID3v2 text from this encoding to the character set specified by the
-L</Charset> option. ExifTool does not currently write ID3 information.
-
-=head2 PDF
-
-PDF text strings are stored in either PDFDocEncoding (similar to Windows
-Latin1) or Unicode (UCS-2).  When reading, ExifTool converts to the
-character set specified by the L</Charset> option.  When writing, ExifTool
-encodes input text from the specified character set as Unicode only if the
-string contains special characters, otherwise PDFDocEncoding is used.
-
-=head2 Photoshop
-
-Some Photoshop resource names are stored as Pascal strings with unknown
-encoding.  By default, ExifTool assumes MacRoman encoding and converts this
-to UTF-8, but the internal and external character sets may be specified with
-L</CharsetPhotoshop> and L</Charset> options respectively.
-
-=head2 QuickTime
-
-QuickTime text strings may be stored in a variety of poorly document
-formats. ExifTool does its best to decode these according to the L</Charset>
-option setting.  For some QuickTime strings, ExifTool assumes a default
-encoding of MacRoman, but this may be changed with the L</CharsetQuickTime>
-option.
-
-=head2 AIFF
-
-AIFF strings are assumed to be stored in MacRoman, and are converted
-according to the L</Charset> option when reading.
-
-=head2 MIE
-
-MIE strings are stored as either UTF-8 or ISO 8859-1. When reading, UTF-8
-strings are converted according to the L</Charset> option, and ISO 8859-1
-strings are never converted.  When writing, input strings are converted from
-the specified character set to UTF-8.  The resulting strings are stored as
-UTF-8 if they contain multi-byte UTF-8 character sequences, otherwise they
-are stored as ISO 8859-1.
-
-=head2 Vorbis
-
-Vorbis comments are stored as UTF-8, and are converted to the character set
-specified by the L</Charset> option.
-
-=head1 AUTHOR
-
-Copyright 2003-2012, Phil Harvey
-
-This library is free software; you can redistribute it and/or modify it
-under the same terms as Perl itself.
-
-=head1 ACKNOWLEDGEMENTS
-
-Many people have helped in the development of ExifTool through their bug
-reports, comments and suggestions, and/or additions to the code.  See the
-ACKNOWLEDGEMENTS in the individual Image::ExifTool modules and in
-html/index.html of the Image::ExifTool distribution package for a list of
-people who have contributed to this project.
-
-=head1 SEE ALSO
-
-L<exiftool(1)|exiftool>,
-L<Image::ExifTool::TagNames(3pm)|Image::ExifTool::TagNames>,
-L<Image::ExifTool::Shortcuts(3pm)|Image::ExifTool::Shortcuts>,
-L<Image::ExifTool::Shift.pl|Image::ExifTool::Shift.pl>,
-L<Image::Info(3pm)|Image::Info>,
-L<Image::MetaData::JPEG(3pm)|Image::MetaData::JPEG>
-
-=cut
-
-# end