/* Copyright (C) 1995-1997, Russell Lang.  All rights reserved.
  
  This file is part of GSview.
  
  This program is distributed with NO WARRANTY OF ANY KIND.  No author
  or distributor accepts any responsibility for the consequences of using it,
  or for whether it serves any particular purpose or works at all, unless he
  or she says so in writing.  Refer to the GSview Free Public Licence 
  (the "Licence") for full details.
  
  Every copy of GSview must include a copy of the Licence, normally in a 
  plain ASCII text file named LICENCE.  The Licence grants you the right 
  to copy, modify and redistribute GSview, but only under certain conditions 
  described in the Licence.  Among other things, the Licence requires that 
  the copyright notice and this notice be preserved on all copies.
*/

/* epstool.txt */

1997-02-15

EPSTOOL - Create or extract preview bitmaps in EPS files.

EPSTOOL.EXE is a Win32 console EXE.
EPSTOOL2.EXE is an OS/2 console EXE.

Features:
- Add EPSI or DOS EPS previews.
- Extract postscript from DOS EPS files.
- Uses Ghostscript to create preview bitmaps.
- Scan a bitmap created by Ghostscript to find bounding box.
- Create TIFF, WMF or Interchange from part of a bitmap created 
  by Ghostscript.
- output to stdout or file.
- input must be from a file.
- works under OS/2, Unix, Win32 and MS-DOS.
- works on little-endian machines (Intel) or big endian 
  (Sun Sparc, Motorola) machines.
- Options:
   input file,                 (on command line)
   output file,                -ofilename
   page number,                -npagenumber
   resolution,                 -rdpi  (default 72)
   calculate bounding box,     -b
   gs command,                 -gcommand
   debug mode,                 -d  (leaves temporary files)
   non verbose mode,           -q  (no messages unlesss error occurs)
   specify gs device           -zdevice (for -t6u, -t6p, -tg, -w)

- Operations:  
   Add TIFF 4,                      -t4 or -t
   Add TIFF 6 uncompressed preview, -t6u
   Add TIFF 6 packbits preview,     -t6p
   Add TIFF using GS device         -tg
   Add Interchange,                 -i
   Add user supplied preview,	    -ufilename
   Add WMF,	                    -w
   Extract PostScript,              -p
   Extract Preview,                 -v

On-line help says:
Usage:  epstool [option] operation filename
  Options:
     -b             Calculate BoundingBox from image
     -gcommand      Ghostscript command
     -nnumber       Page number to extract
     -ofilename     Output filename
     -q             Quiet (no messages)
     -rnumber       Preview resolution in dpi
     -zdevice       Ghostscript device name
  Operations: (one only)
     -i             Add Interchange preview   (EPSI)
     -t4            Add TIFF4 preview         (DOS EPS)
     -t6u           Add TIFF6 uncompressed    (DOS EPS)
     -t6p           Add TIFF6 packbits        (DOS EPS)
     -tg            Add GS TIFF preview       (DOS EPS)
     -w             Add WMF preview           (DOS EPS)
     -p             Extract PostScript        (DOS EPS)
     -v             Extract Preview           (DOS EPS)
     -c             Copy without preview      (use with -b)



=========
Examples:
=========

Create EPS file tiger.eps with TIFF (G3 Fax) preview
  epstool -tg -ztiffg3 -g"gsos2 -Id:\gs;d:\psfonts" -otiger.eps tiger.ps
Any GS TIFF device can be used, e.g. -ztiffg4, -ztiffpack

Add colour preview (8bit/pixel) to EPS file
  epstool -t6p -zbmp256 -g"gsos2 -Id:\gs;d:\psfonts" -otiger.eps tiger.ps

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

EPS file has incorrect %%BoundingBox.
Add TIFF4 preview and calculate %%BoundingBox from bitmap.
  epstool -b -t4 -g"gsos2 -Id:\gs;d:\psfonts" -ogolfer.eps golfer.ps

Adjust the BoundingBox of an existing EPS file, but don't add a preview:
  epstool -b -t4 -otemp.eps existing.eps
  epstool -p -oexisting.eps temp.eps
  del temp.eps
or
  epstool -b -c -otemp.eps existing.eps
  del existing.eps
  rename temp.eps existing.eps

Add user supplied Windows Metafile to EPS file.
Typically used when an application can export EPS and WMF separately
but can't export EPS with WMF preview.
  epstool -ulogo.wmf -ologo2.eps logo.eps


=====
Notes
=====
Under OS/2 or MS-DOS, epstool requires Ghostscript 3.51 or later.
If you have command line length problems, try setting the Ghostscript
include path using the GS_LIB environment variable instead of using
-g"c:\gs3.51\gsos2.exe -Ic:\gs3.51;c:\gs3.51\fonts;c:\psfonts"

For MS-DOS, use gs386.exe.
For OS/2, use gsos2.exe.
For Windows 95 or Windows NT, use gswin32c.exe.

The "-b   Calculate BoundingBox from image" option works by scanning
a bitmap returned by Ghostscript.  This will only work for the
operations -i, -t4, -t6u, -t6p, -w and -c.  It does not work with -tg 
or -ufilename. -tg does not return a bitmap in a format understood
by epstool.  -ufilename does not even use Ghostscript.

The "-zdevice" should only be used with -tg, -t6u, -t6p and -w.

For -tg, the -zdevice may be any tiff device.

For -t6u, -t6p and -w:
Under OS/2 or MS-DOS, -zdevice can be one of the following:
  bmpmono, bmp16, bmp256, bmp16m, pbmraw, pgmraw, ppmraw
Under Unix, -zdevice can be one of the following:
  pbmraw, pgmraw, ppmraw

To get a colour preview, you must use -zdevice.
The default device used by epstool is monochrome (bmpmono or pbmraw).

When adding a WMF preview using -w, the preview contains a bitmap,
not a vector representation.  If -zdevice is not used, the
Ghostscript device bmpmono or pbmraw will be used to create the bitmap.
The bitmap in the metafile will be 1bit/pixel black and white.
  epstool -b -w -onew.eps old.eps
If you want a colour bitmap in the metafile, specify a bitmap device 
which supports colour.
  epstool -b -w -zbmp256 -onew.eps old.eps

When adding a WMF preview to an EPS file using -ufilename, 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 it's origin 
at (0,0), which might not be correct.

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.

================
Revision History
================
1.02 1997-02-15
  Removed requirement for EPS file to use showpage.
  Added -c to allow correction of %%BoundingBox
  When calculating %%BoundingBox, render to a page of letter
  width and A4 height.
  Avoid integer overflow on 16bit machines when calculating width 
  and height.
  If TEMP undefined, default to /tmp on Unix.

1.01 1996-11-07
  Release separate from GSview.  No code changes.
  Includes Win32 (epstool.exe) and OS/2 (epstool2.exe) EXEs.

1.0 1996-10-13
  Not a beta version.  Included with GSview 2.1.

0.81 beta 1996-09-12
  Added TIFF packbits compression.
  Added -zdevice.
  -t5 replaced by -t6u, -t6p.
  -wdevice replaced by -w -zdevice
  -ttiff3 replaced by -tg -ztiffg3

0.8 beta 1996-09-09
  Makefile target for Win32.
  Add WMF for all platforms.
  Removed restriction that structures must be byte aligned under Unix.
  Must still be byte aligned under DOS and OS/2.

0.7 alpha 1995-10-20
  Fixed a few error messages.
  Use @file to reduce Ghostscript command line length under MS-DOS and OS/2.
  Added -q option to GSview and -dQUIET option to Ghostscript command line 
  to allow EPS files to be written to stdout.

0.6 alpha 1995-10-12
  Delete temporary bmp file.
  Add user supplied preview to a DOS EPS file (which already had a
  preview) was wrong.

0.5 alpha 1995-09-27
  Put stdout into binary mode.
  Write placeable WMF header correctly on 32bit and big-endian machines.

0.4 alpha 1995-09-15
  Remove placeable WMF header when adding to EPS file, add placeable
  WMF header when extracting from EPS file.

0.3 alpha 1995-09-14
  First release separate from GSview.

