Provided by: epstool_3.09-2_amd64 bug

NAME

       epstool - Edit preview images and fix bounding boxes in EPS files.

SYNOPSIS

       epstool command [ options ] inputfile outputfile

DESCRIPTION

       epstool  is  a  utility  to  create or extract preview images in EPS files. It can also calculate optimal
       bounding boxes.

   EPS (Encapsulated PostScript Format)
       EPS is a specialised form of a PostScript file that complies with the  Document  Structuring  Conventions
       (DSC)  and is intended to be embedded inside another PostScript file.  An EPS file must contain a special
       first line that identifies it as an EPS file  (e.g.  %!PS-Adobe-3.0  EPSF-3.0)  and  it  must  contain  a
       %%BoundingBox:  line.   The  EPS  file  only draws within the rectangle defined by the bounding box.  The
       PostScript code must avoid using PostScript operators that would interfere  with  the  embedding.   These
       include operators with global effects such as changing the page size and changing the half tone screen.

   PREVIEWS
       EPS  files  may  contain a preview to be used by programs that can't interpret the PostScript code. There
       are three ways to add a preview to an EPS file.

       Interchange
              This preview is included  within  PostScript  comments  in  a  section  marked  %%BeginPreview:  /
              %%EndPreview.  The actual image data is stored in hexadecimal format. This format is most commonly
              used on Unix.

       DOS EPS
              The preview is a TIFF or Windows Metafile. A DOS EPS file has a 30 byte binary header which  gives
              offsets  and  lengths for the PostScript, TIFF and Windows Metafile sections. You can't send a DOS
              EPS file directly to a printer - you have to remove the binary  header  and  preview  first.  This
              format is most commonly used on MS-Windows.

       PICT   The  preview  is  in  PICT  format  stored  in the resource fork of the file.  This format is most
              commonly used on the Macinstosh.  Epstool provides limited support for this format.

COMMANDS (one only):

       -t4, --add-tiff4-preview
              Add a TIFF 4 preview. The preview is monochrome and is intended for use  with  old  programs  that
              won't read TIFF6, such as Word Perfect 5.1 for DOS.

       -t6u, --add-tiff6u-preview
              Add  a  TIFF  6  uncompressed  preview.  See  --add-tiff6p-preview  for  how to add a greyscale or
              monochrome preview.

       -t6p, --add-tiff6p-preview
              Add a TIFF 6 preview compressed with packbits (simple  run  length  encoding).  The  preview  will
              normally  be  full  colour, but you can make it greyscale by adding the option --device bmpgray or
              --device pgmraw, or monochrome using --device bmpmono or --device pbmraw.

       -tg, --add-tiff-preview
              Add a TIFF preview using ghostscript to generate the TIFF file. You must specify a  suitable  TIFF
              device using --device. If you want a compressed monochrome image, you might use --device tiffg3.

       -i, --add-interchange-preview
              Add a monochrome interchange preview.

       -w, --add-metafile-preview
              Add  a Windows Metafile (WMF) preview. The metafile will contain a bitmap, not vector information.
              The preview will normally be full colour. See --add-tiff6p-preview for how to add a  greyscale  or
              monochrome preview.

       --add-pict-preview
              Add  a  Mac  PICT  preview.   EPSF  files  with  PICT  previews  can generally be used only on Mac
              computers.  The preview will be full colour.  The AppleSingle and MacBinary formats  will  contain
              the  EPSF  and  the preview.  The AppleDouble or Resource format will contain the preview only and
              needs to accompany the  original  EPSF  file.   To  specify  the  file  format  use  --mac-single,
              --mac-double, --mac-binary or --mac-rsrc.

       --add-user-preview  filename
              Add  a user supplied image as a preview. The image can be a Windows bitmap, a PBMPLUS file, a TIFF
              image or a Windows Metafile.  Window  bitmaps  and  PBMPLUS  files  will  be  converted  to  TIFF6
              compressed with packbits. TIFF and Windows Metafile images will be added unchanged.

       --bitmap
              Create  a  bitmap  of the area within the EPS bounding box. The bitmap type must be specified with
              --device.  If processing a DCS 2.0 file, the separation can be specified with --page-number.

       --copy Copy the EPS file. This is generally used with the --bbox option to update the bounding box.

       --dcs2-multi
              Convert DCS 2.0 separations to multiple files. See DCS 2.0. If the output name  is  out.eps,  then
              the separations would be named out.eps.Cyan etc.

       --dcs2-single
              Convert DCS 2.0 separations to a single file. See DCS 2.0.

       --dcs2-report
              Write  the  separation  names,  lengths  and  CMYK  values to standard output. This can be used to
              identify if a DCS 2.0 file is missing the composite page or preview.

       --dump Display some information about the file type and DSC comments.

       -p, --extract-postscript
              Extract the PostScript section from a DOS EPS file.

       -v, --extract-preview
              Extract the preview section from a DOS EPS file.

       -h, --help
              Display a summary of the epstool commands and options.

       --test-eps
              Partially test if a file complies with the EPSF specification.

OPTIONS

       -b, --bbox
              Calculate the bounding box using the ghostscript bbox device and update in the EPS file.

       --combine-separations  filename
              Combine the separations of the input DCS 2.0 file with those of this file.  It is an error if  the
              bounding  boxes  do not match or they contain separations with the same name.  This option must be
              used with --dcs2-multi or --dcs2-single.  The composite page may later need  to  be  updated  with
              --replace-composite.

       --combine-tolerance  pts
              When  using  --combine-separations,  allow  the  bounding  boxes to vary by up to pts points.  The
              default is 0 so the bounding boxes must match exactly.

       --custom-colours  filename
              When using --replace-composite on a DCS 2.0 file, use  the  colours  specified  in  this  file  in
              preference to those specified in the composite page.

       -d, --debug
              Be more verbose about progress. Do not remove temporary files.

       --device name
              Specify   a   ghostscript   device   to   be  used  when  creating  the  preview  or  bitmap.  For
              --add-tiff-preview this must be one of the ghostscript tiff devices (e.g. tiffg3, tiff24nc).   For
              any  other  preview,  it  must be one of the bmp or pbmplus devices (e.g. bmpgray, bmp16m, pgmraw,
              ppmraw). For bitmap output (--bitmap) it can be any ghostscript bitmap device.

       --doseps-reverse
              When writing a DOS EPS file (TIFF or WMF preview), the default is to write the  PostScript  before
              the  preview.   Using  --doseps-reverse  puts  the preview before the PostScript section, which is
              required by some buggy programs.  Either order is correct.

       --dpi resolution
              Set the resolution of the preview or bitmap. The default is 72 dpi.

       --dpi-render resolution
              Render at a higher resolution set by --dpi-render , then  downsample  to  the  resolution  set  by
              --dpi.  This  works  when adding a preview image or using --replace-composite , but not when using
              --bitmap.  This improves the preview quality when the original contains a pre-rendered  image  and
              --dpi-render is set to match the original target printer.

       --ignore-information
              Ignore  information  messages  from the DSC parser.  Use at your own risk.  These messages usually
              indicate that something is wrong with an EPS file, but that most EPS handlers probably won't care.
              An example is a line with more than 255 characters.

       --ignore-warnings
              Ignore  warnings  from  the  DSC  parser.  Use at your own risk.  These messages are usually about
              faults in the DSC comments that are recoverable by epstool, but may confuse  other  EPS  handlers.
              An example is a bounding box that incorrectly uses floating point numbers instead of integer.

       --ignore-errors
              Ignore  warnings  from  the  DSC  parser. Use at your own risk. You really should fix the EPS file
              first.

       --gs command
              Specify the name the ghostscript program. On Unix the default is gs.   On  Windows,  epstool  will
              check the registry for installed versions of ghostscript and use the latest, otherwise it will use
              gswin32c.exe.

       --gs-args arguments
              Specify additional Ghostscript  arguments.  This  might  be  used  to  select  anti-aliasing  with
              "-dTextAlphaBits=4 -dGraphicsAlphaBits=4"

       --output filename
              Specify the output file (instead of using the second file parameter).  Using the filename - causes
              epstool to write to standard output, which requires the use of --quiet.

       --mac-binary
              When adding a PICT preview, use the MacBinary I format.  for the Mac

       --mac-double
              When adding a PICT preview, use the AppleDouble format for the Mac.

       --mac-rsrc
              When adding a PICT preview, use the Resource format for the Mac.

       --mac-single
              When adding a PICT preview, use the AppleSingle format for the Mac.

       --missing-separations
              When writing a DCS 2.0 file, epstool will normally fail if a separation  is  missing.   When  this
              option is used, it will remove references to missing separations when writing the file.

       --page-number page
              When  creating  a  bitmap  with  --device from a DCS 2.0 file, page specifies the separation to be
              used.  Page 1 is the composite and page 2 is the first separation.  Use --dcs2-report to  get  the
              list of separations.

       --quiet
              Try to run without writing to standard output.

       --rename-separation oldname newname
              When  copying a DCS 2.0 file with --dcs2-multi or --dcs2-single, rename separation with oldname to
              newname.  This option implies --missing-separations.  It is assumed that the new name is  just  an
              alias  for  the  same  colour  and that the CMYK or RGB values for the separation are not changed.
              This option may be used multiple times.  This must be used if the input file incorrectly  has  two
              separations of the same name.

       --replace-composite
              Some  DCS 2.0 files do not have an image in the composite page. This option replaces the composite
              page with a CMYK image derived from the separations. This option must be used with --dcs2-multi or
              --dcs2-single. See also the options --dpi and --custom-colours.

MACINTOSH

       The Macintosh does not use a flat file system.  Each file can have a data fork and a resource fork.  EPSF
       files have the PostScript in the data fork, and optionally have a preview in the resource fork as a  PICT
       image.  In addition, file type is obtained from the finder info rather than a file extension.  File types
       use a four character code such as "EPSF" or "PICT".  When Macintosh files are copied to  a  foreign  file
       system,  the  resource  fork may be left behind.  Alternatives to retain the resource fork are to package
       the finder data, data fork and resource fork in a single MacBinary or AppleSingle file,  or  to  put  the
       data  fork  in  a  flat  file  and the finder info and resource fork in an AppleDouble file.  The Mac OSX
       finder will handle AppleDouble files automatically when copying files to and from a foreign file  system.
       When copying test.eps to a foreign file system, the data fork would be written as test.eps and the finder
       info and resource fork to the AppleDouble file ._test.eps or .AppleDouble/test.eps.

       Epstool can read MacBinary and AppleSingle files.  It can write MacBinary I, AppleSingle, AppleDouble  or
       Resource files.  Files written by epstool will have type EPSF and creator MSWD.  When adding a preview to
       test.eps, it is suggested that you create the MacBinary file test.eps.bin.  On a Macintosh  computer  you
       then  need  to extract it with StuffIt Expander.  Another alternative is to write the AppleDouble file to
       ._test.eps then copy both files to a file system accessible to a Mac computer.

       If the output file name starts with . then AppleDouble will be assumed, otherwise if  it  ends  with  .as
       then AppleSingle will be assumed, otherwise if it ends with .rsrc or /rsrc then Resource will be assumed,
       otherwise MacBinary will be assumed.  When writing a MacBinary file, it is recommended that you  end  the
       filename in .bin.  To force the file type, use --mac-single, --mac-double, --mac-binary or --mac-rsrc.

       On  Mac  OS  X  you  can  access a file's resource fork from command line tools by appending /rsrc to the
       original file name.  The easiest way to add a preview to the file test.eps on Mac OS X is to let  epstool
       write in --mac-rsrc format to test.eps/rsrc (see Examples).

DESKTOP COLOR SEPARATIONS (DCS 2.0)

       The  Desktop Color Separation (DCS) image file format contains a low resolution preview, a main file with
       the full resolution composite image, and colour separations with full resolution separated  plates.   The
       separations will typically contain Cyan, Magenta, Yellow, Black and possibly spot colours.  There are two
       versions of DCS 2.0.

       Multiple File
              The main file contains %%PlateFile: (name) EPS Local filename comments which give the filenames of
              the  separation  plates.   The  main  file  may  contain  a  low  resolution DOS EPS preview.  The
              separation files do not contain previews.

       Single File
              This is an abuse of the EPS specification.  The  single  file  contains  the  main  file  and  the
              separations  concatenated  together,  which  makes  the  DSC  comments  incorrect.   The main file
              specifies the byte offsets to the separations using %%PlateFile: (name)  EPS  #offset  size.   The
              single  file  may then be placed inside a DOS EPS file with a low resolution preview.  By default,
              epstool writes single file DCS 2.0.

       Epstool can add previews to single and multiple file DCS 2.0.  It can split  single  file  DCS  2.0  into
       multiple  files  and  vice  versa.   This  allows  a single file DCS 2.0 to be split, the composite image
       replaced, a new preview created, and then be recombined into a single file.

       Some DCS 2.0 files do not have an image in the composite page.  To determine if the composite  page  does
       not  contain  an  image, use --dcs2-report and look to see if the composite section is very short.  Using
       --dcs2-single --replace-composite replaces the composite page with the headers of the original  composite
       page  and  a  body  containing a CMYK image derived from the separations.  Set the resolution of the CMYK
       image using --dpi.

       When replacing the composite page with a  CMYK  image  using  --replace-composite,  the  --custom-colours
       option  is useful for dealing with DCS 2.0 files that have incorrect CMYK colours, for example specifying
       that the varnish layer  is  grey.   Each  line  of  the  CMYK  colours  file  is  formatted  like  a  DSC
       %%CMYKCustomColor: or %%RGBCustomColor: line, as shown in the example below.

       %%CMYKCustomColor: 0.00 0.00 0.00 0.00 Varnish

       %%CMYKCustomColor: 1.00 0.68 0.00 0.12 (Dark Blue)

       %%RGBCustomColor: 0.5 0.0 0.0 (Dark Red)

       DCS2 files should not have two separations with the same name.  Epstool will not allow a DCS2 output file
       to have duplicate separation names.  Use --rename-separation to resolve this.

EXAMPLES

       Add colour preview (24bit/pixel) to EPS file
                epstool -t6p tiger.eps output.eps

       Add TIFF (G3 Fax) preview to tiger.eps.
                epstool --add-tiff-preview --device tiffg3 tiger.eps output.eps

       Any GS TIFF device can be used, e.g. tiffg4, tiffpack

       Extract TIFF preview from tiger.eps
                epstool -v tiger.eps tiger.tif

       Fix incorrect %%BoundingBox then add TIFF4 preview.
                epstool --bbox -t4 golfer.eps output.eps

       Adjust the BoundingBox of an existing EPS file, but don't add a preview:
                epstool --copy --bbox input.eps output.eps

       Add user supplied Windows Metafile to EPS file.
                epstool --add-user-preview logo.wmf logo.eps output.eps

       Typically used when an application can export EPS and WMF  separately  but  can't  export  EPS  with  WMF
       preview.

       Add a PICT preview and write an AppleDouble file.
                epstool --add-pict-preview --mac-double tiger.eps ._tiger.eps

       To be used by a Mac, both tiger.eps and ._tiger.eps need to be on a foreign file system accessible to the
       Mac.

       Add a PICT preview, overwriting the existing resources.
               epstool --add-pict-preview --mac-rsrc tiger.eps tiger.eps/rsrc

       On Mac OS X you can access a file's resource fork from command line tools by  appending  "/rsrc"  to  the
       file's original name.

NOTES

       When  adding a WMF preview to an EPS file using -add-user-preview filename, the placeable metafile header
       is removed from the metafile as it is put into the EPS file.  When extracting a WMF preview from  an  EPS
       file,  a  placeable  metafile  header  is  created  from the EPS BoundingBox information.  This placeable
       metafile header assumes that the WMF has its origin at (0,0), which might not be correct.

       When epstool is creating a TIFF or WMF preview, it will convert palette colour images into 24-bit/pixel.

       The environment variable TEMP should point to a writeable directory for temporary files.  If not defined,
       /tmp will be used for Unix and the current directory will be used for other platforms.

AUTHOR

       epstool was written by Russell Lang <gsview@ghostgum.com.au>

       This  man page was contributed by Martin Pitt <martin@piware.de> for the Debian GNU/Linux system (but may
       be used by others).