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).