What is ps2eps?
---------------
ps2eps is a tool to produce Encapsulated PostScript Files (EPS/EPSF)
from usual one-paged Postscript documents. It calculates correct
Bounding Boxes for those EPS files and filters some special postscript
command sequences that can produce errorneous results on printers.
EPS files are needed for including (scalable) graphics into TeX (or
even Word) documents. I found out that other programs like "ps2epsi"
didn't calculate the bounding box always correct (because the values
are put on the postscript stack which may get corrupted by bad
postscript code) or rounded it off so that clipping the EPS cut off
some part of the image. Therefore ps2eps uses a resolution of 144 dpi
to get the correct bounding box.
Clipping (or why gets some of my text deleted above the included .eps file?)
--------
Some postscript drivers draw a white rectangle from the top left
corner of the page to the right lower corner of the object. This may
erase some or even all text above your imported/included EPS file,
which is very annoying. In order to prevent this, most programs have a
clipping option for imported .eps files (within LaTeX you can use
\includegraphics*{}) for this purpose. If this is unfortunately not
the case, you can use the -C option of ps2eps which will (hopefully)
do it for you. Unfortunately, PScript.dll 5.2 (Windows XP) introduced
new very badly behaving Postscript code which will even override the
clipping!! Thus, a new filter had to be installed in ps2eps which will
fix it.
However, because most programs clip directly on the bounding box,
you still may loose some pixels of your image, because the bounding
box is described in the coarse resolution of postscript points,
i.e. 72 dpi. In order to prevent this, you can use the -l
option or -C option (for the latter, clipping by the importing program
should be disabled then) to allow for a 1 point larger bounding box.
-C clips around a 1 point enlarged bounding box and -l enlarges the
bounding box values by 1 point (you can also combine both options).
Filtering bad behaving postscript code
--------------------------------------
Some postscript sequences, e.g. for using specific printer features
(featurebegin ...), are not working well within an .eps file, so
ps2eps tries to filter them out. But please note that filters for
postscript code may not work properly for your printer driver (ps2eps
was mainly tested with HP and Adobe printer drivers, although it may
work for all printers using the PScript.dll). In this case you can try
to turn of filtering by using option -n, or try to find the bad
sequence in the postscript code and adapt the filter rule in the
ps2eps script (variables $linefilter, $rangefilter_begin,
$rangefilter_end; linefilter is an expression for filtering single
lines, rangefilter_... are expressions that filter all lines between a
pattern matching $rangefilter_begin and $rangefilter_end; drop me an
e-mail with your modifications). However, things may change as the
printer drivers (e.g., PScript.dll) or postscript language evolve.
Filtering junk from postscript code
-----------------------------------
Some applications or drivers generate postscript code with leading or
trailing binary code, which often confuses older postscript
interpreters. ps2eps tries to remove such code, but it may sometimes
make a wrong guess about start and end of the real postscript code
(drop me an e-mail with a zipped postscript source, see below).
Furthermore, some postscript code may get corrupted when comment lines
or even blank lines are removed (which is default), because those
files may contain encoded images which also have a % as first
character in a line or use a special comment as end of image
delimiter. If this is the case, use the -c option to prevent filtering
comments.
Moreover, ps2eps removes blank lines and also <CR> (carriage ceturn
'\r') at the end of lines. However, nicely formatted postscript code
gives a hint by using "%%BeginBinary" "%%EndBinary" comments. When
ps2eps detects these comments it will refrain from any filtering
action within the marked binary sections.
Determining the right size
--------------------------
By default, ps2eps now uses an already given %%BoundingBox from the
source file, which often corresponds to the size of the physical page
format for which the document was printed. However, you should be
aware that this already specified bounding box may be incorrect, thus
resulting in a wrongly cropped (or even no usable) .eps-file. ps2eps
can only do as good as ghostscript does in rendering the original
postscript file. Therefore, if the given bounding box is to small, you
can ignore the existing bounding box with the -B option, which will
cause ghostscript to use its internal default size.
However, if you have documents that are larger than your ghostscript
default (usually A4 or letter), you have to specify the page
dimensions using the -s option or your EPS might be cut off during
rasterizing by ghostscript resulting in a wrong bounding box.
Hint: to avoid rotating the picture if you have the original drawing
in landscape format, you may use the "Encapsulated Postscript" option
in the printer driver which should generate an EPS file (but with a
bounding box of the sheet size!). But some Windows printer drivers are
drawing the image with an offset from the bottom of the portrait page,
so that a part of it is drawn outside the landscape oriented page.
In this case, you'll have to specify a square size of the page using
the maximum length, e.g., 29.7cm x 29.7cm for an A4 page.
Color and memory
----------------
Furthermore, ps2eps now supports colored postscript, consequently
letting ghostscript consume more resources for drawing its bitmap
(roughly 6MBytes for an A4 page). bbox is reading the bitmap line
by line so it consumes only minimal memory. If you experience problems
with memory consumption of ghostscript, you may use the -m option
for using a monochrome image, but this will probably fail with colored
images, because ghostscript has to do b/w dithering and may suppress
objects drawn in light colors.
Usage:
------
You get help by typing "ps2eps --help" or "ps2eps -h".
ps2eps - convert PostScript to EPS (Encapsulated PostScript) files
(C)opyright 1998-2002 Roland Bless
Version: 1.39
Operation:
Without any argument, ps2eps reads from standard input
and writes to standard output.
If filenames are given as arguments they are processed
one by one and output files are written to filenames
with extension '.eps'. If input filenames have the extension
'.ps' or '.prn', this extension is replaced with '.eps'.
In all other cases '.eps' is appended to the input filename.
Please note that PostScript files for input should contain
only one single page.
Syntax:
ps2eps [-f] [-q] [-N] [-n] [-P] [-c] [-C] [-m] [-B] [-E] [-s<pagedim>] [-l] [-h|--help] [-L] [-V|--version] [--] [psfile1] [psfile2] [...]
Options:
-f force overwriting existing files
-q quiet operation (no output while processing files)
-N do not insert any postscript code
-n do not try to fix postscript code
-P remove preview image (smaller file, but no preview)
-F fix postscript code unconditionally
-c preserve document structure comments
-C insert postscript code for clipping
-m use black/white bitmap as base for calculation
-s<pagedim> pagesize in cm (default) or in, format XxY[cm|in], where X and Y are numbers
-l expand the original bounding box by one point in each direction
-B do not use existing bounding box as page size for rendering
-E do not use %%EOF as hint for end of file
--help,
-h help information
-L show licensing information
--version,
-V show version information
-- all following arguments are treated as files
(allows filenames starting with -)
Arguments:
One or more names of PostScript files for input
Author: Roland Bless (roland@bless.de)
INSTALLATION
------------
You need:
- perl (an interpreter for the perl language, see http://www.perl.com)
- ghostscript (an interpreter/raster image processor
for the PostScript language,
see http://www.cs.wisc.edu/~ghost/)
- maybe an ANSI-C compiler if you don't use Linux, Solaris, Digital Unix,
HP-UX or Windows 9x/NT/2000. Sorry for the inconvenience, but I tried
to write a bbox equivalent in perl and it was terribly slow. Therefore
I stick to C, because of much better performance.
How:
UNIX
====
On Unix platforms you simply move the perl script ps2eps into
a directory which is included in the system search path (e.g.
/usr/local/bin). If perl doesn't reside in /usr/local/bin, you
have to edit the location of the perl binary in the first line
of the script or alternatively create a link in /usr/local/bin
pointing to the perl binary. If a bbox binary is included for
your platform you simply move it into any directory of the system
search path. Otherwise, you have to compile bbox.c first by invoking
cc -o bbox -c bbox.c. If you already have a working perl and a working
ghostscript, you're finished here, else you have to install them first.
Windows
=======
For Windows platform you should use the ps2eps.bat instead of ps2eps
and copy it into a location included in your system search path for
binaries. The script assumes that you have "gswin32c" as postscript
interpreter in your path. Please note that the .bat file can only
handle up to 9 arguments/files at once (does anybody know a better
solution for passing those arguments to perl scripts? -> e-Mail me!)
Alternatively, you can use associated file types under
Windows NT/2000/XP:
1.) rename ps2eps to ps2eps.pl and
2.) SET PATHEXT=.pl;%PATHEXT% or use the
settings -> control panel -> system -> "advanced" tab -> environment variables
and edit the PATHEXT entry accordingly.
3.) change in ps2eps.pl
$ghostscriptname= "gs"; to
$ghostscriptname= "gswin32c";
4.) then simply typing ps2eps should invoke ps2eps correctly
(ensure that ps2eps.bat is not in your path)
The last option is to perform step 3.) only and call perl directly:
perl ps2eps ...
However, wildcard support still seems to be very limited under Windows.
There may be other possibilities with Windows Scripting, please let me now!
Contact information:
Roland Bless, roland@bless.de
If you have problems, please send a gzipped file of
relevant postscript code with your error description
and ps2eps version number.
License:
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
---------------------------------------------------------------------------
End of README.txt
---------------------------------------------------------------------------