path: root/Build/source/utils/ps2eps/ps2eps.1

.\" This manpage has been automatically generated by docbook2man 
.\" from a DocBook document.  This tool can be found at:
.\" <http://shell.ipoline.com/~elmert/comp/docbook2X/> 
.\" Please send any bug reports, improvements, comments, patches, 
.\" etc. to Steve Cheng <steve@ggi-project.org>.
.TH "PS2EPS" "1" "24 Januar 2007" "" ""

.SH NAME
ps2eps \- convert PostScript to EPS (Encapsulated PostScript) files
.SH SYNOPSIS

\fBps2eps\fR [ \fB-f\fR ] [ \fB-q\fR ] [ \fB-N\fR ] [ \fB-O\fR ] [ \fB-n\fR ] [ \fB-P\fR ] [ \fB-c\fR ] [ \fB-C\fR ] [ \fB-m\fR ] [ \fB-B\fR ] [ \fB-E\fR ] [ \fB-s \fIpagedim\fB\fR ] [ \fB-t \fIoffset\fB\fR ] [ \fB-r \fIresolution\fB\fR ] [ \fB-R \fI+|-|^\fB\fR ] [ \fB-l\fR ] [ \fB-g\fR ] [ \fB-H\fR ] [ \fB-d\fR ] [ \fB-h|--help\fR ] [ \fB-W\fR ] [ \fB-L\fR ] [ \fB-V|--version\fR ] [ \fB--\fR ] [ \fB\fIpsfile1\fB\fR ] [ \fB\fIpsfile2\fB\fR ] [ \fB\fI\&...\fB\fR ]

.SH "DESCRIPTION"
.PP
This manual page documents \fBps2eps\fR version 1.64.
.PP
\fBps2eps\fR is a tool (written in Perl) 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
erroneous results on printers. EPS files are often needed for including
(scalable) graphics of high quality into TeX/LaTeX (or even Word) documents.
.PP
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 \fI\&.eps\fR\&. If input filenames have the 
extension \fI\&.ps\fR or \fI\&.prn\fR, this extension is replaced with \fI\&.eps\fR\&.
In all other cases \fI\&.eps\fR is appended to the input filename.
Please note that PostScript files for input should contain
only one single page (you can possibly use the \fBpsselect\fR from the
psutils package to extract a single page from a document that
contains multiple pages).
.PP
If BoundingBox in output seems to be wrong, please try options \fB--size\fR or
\fB--ignoreBB\fR\&. See also section TROUBLESHOOTING. 
.SH "OPTIONS"
.PP
\fBps2eps\fR follows the usual GNU command line syntax,
with long options starting with two dashes (`-').  A summary of
options is included below.
.TP
\fB-h, --help \fR
Show summary of options.
.TP
\fB-V, --version \fR
Show version of program.
.TP
\fB-f, --force \fR
Force overwriting existing files. \fBps2eps\fR 
will not overwrite files by default to avoid deleting original EPS
files accidently.
.TP
\fB-q, --quiet \fR
quiet operation (no output while processing files, except errors).
.TP
\fB-N, --noinsert \fR
do not insert any postscript code. Normally a few postscript
instructions are added around the original postscript code by
\fBps2eps\fR which can be turned off by this option.
.TP
\fB-O, --preserveorientation \fR
do not filter %%Orientation: header comment.
.TP
\fB-n, --nofix \fR
do not try to fix postscript code by filtering some instructions.
.TP
\fB-P, --removepreview \fR
remove preview image (smaller file, but no preview anymore).
.TP
\fB-F, --fixps \fR
fix postscript code unconditionally. Otherwise, filtering is
usually triggered by detection of certain drivers only.
.TP
\fB-c, --comments \fR
preserve document structure comments.
.TP
\fB-C, --clip \fR
insert postscript code for clipping. Unless
\fB--nohires\fR is specified, the HiResBoundingBox
(enlarged by 0.1 points) is used for clipping. 
.TP
\fB-m, --mono \fR
use black/white bitmap as base for calculation (default: off).
.TP
\fB-s, --size=pagedim \fR
where pagedim is a pre-defined standard page size
(e.g., a4,a0,b0,letter,...) or explicitly specified in a 
format pagedim:=\fIX\fRx\fIY\fR[cm|in],
where \fIX\fR and \fIY\fR are numbers (floating points are accepted) followed by
units centimeter (cm) or inch (in), (default: cm). 
Use \fB--size=list\fR to list pre-defined pagesizes. 
See also environment variable PS2EPS_SIZE\&.
.TP
\fB-t, --translate=x,y \fR
specify an x,y offset (may be negative) in postscript points
(1/72 dpi) for drawing. This option may be required
if your drawing has negative coordinates which usually lets ghostscript 
cut the negative part of your picture, because it starts to render
at positive coordinates. The resulting output will
also be shifted.
.TP
\fB-r, --resolution=dpi \fR
specify a resolution in dpi (dots per inch) for drawing under
ghostscript. Default
resolution is 144 dpi which is the double of the typical 72 dpi.
This option may help if there is a hardware dependent resolution
encoded in the postscript, e.g., 600dpi. Example:
\fBps2eps -l -r 600 test.ps\fR
.TP
\fB-R, --rotate=direction \fR
This option rotates the resulting EPS output. 
The parameter direction determines the direction of
rotation: + means +90 degrees (clockwise),- means -90 degrees
(counter-clockwise), and  ^ means 180 degrees (up-side down).
.TP
\fB-l, --loose \fR
expand the original tight bounding box by one point in each
direction.
.TP
\fB-B, --ignoreBB \fR
do not use existing bounding box as page size for
rendering.
.TP
\fB-E, --ignoreEOF \fR
do not use %%EOF as hint for end of file. Otherwise, \fBps2eps\fR assumes
that postscript code ends after the last %%EOF comment, because
some drivers add trailing binary ``garbage'' code which gets deleted 
by \fBps2eps\fR by default. 
.TP
\fB-g, --gsbbox \fR
use internal bbox device of ghostscript instead of the external C
program \fBbbox\fR\&. The internal bbox device of ghostscript
generates different values (sometimes even incorrect), 
so using the provided \fBbbox\fR should be more robust.
See also environment variable PS2EPS_GSBBOX\&.
.TP
\fB-H, --nohires \fR
do not generate a %%HiResBoundingBox comment for output.
.TP
\fB-L, --license \fR
show licensing information.
.TP
\fB-d, --debuggs \fR
show ghostscript call. This may be helpful for solving problems that
occur during a ghostscript call.
.TP
\fB-W, --warnings \fR
show warnings about sanity of generated EPS file. Certain
postscript commands should not be contained in an EPS file.
With this option set \fBps2eps\fR will issue a warning if it 
detects at least one of them.
.SH "TROUBLESHOOTING"
.PP
Based on the given postscript source code (in most cases generated by
some postscript printer driver) there are many potential obstacles or
problems that may occur when trying to create proper EPS files. Please
read this section carefully to be aware of common pitfalls.
.SS "INCOMPLETE/CLIPPED IMAGES"
.PP
or how to determine the right size for ghostscript.
.PP
If you have documents that are larger than your
ghostscript default (usually A4 or US letter), you have to
specify the page dimensions explicitly using the 
\fB-s\fR option. Otherwise your EPS
might be cut off during rasterizing by ghostscript resulting
in a wrongly calculated bounding box. You can pass 
all pre-defined page sizes to \fB-s\fR that ghostscript understands. These are
currently: 11x17, ledger, legal, letter, lettersmall, archA, archB, archC, archD, archE
a0, a1, a2, a3, a4, a5, a6, a7, a8, a9, a10, isob0, isob1, isob2, isob3, isob4, isob5, isob6, 
b0, b1, b2, b3, b4, b5, c0, c1, c2, c3, c4, c5, c6, jisb0, jisb1,
jisb2, jisb3, jisb4, jisb5, jisb6, flsa, flse, halfletter.
Unfortunately, all sizes are currently only available in portrait
orientation (not landscape).
.PP
By default, \fBps2eps\fR 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 not correct, thus resulting in a
wrongly cropped (or even no usable) \fI\&.eps\fR-file. 
\fBps2eps\fR can only do as good as ghostscript does in rendering the original
postscript file (though \fBps2eps\fR even works with negative and
fractional values are contained in the original bounding box by using
automatic translation). Therefore, if the given bounding box is to
small or incorrect anyway, you can ignore the existing bounding box with the \fB-B\fR
option, which will cause ghostscript to use its internal
default size (or use \fB-s\fR). However, if the
BoundingBox has negative coordinates, which is not allowed by
the specification, \fBps2eps\fR will shift the output to positive values.
.PP
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.
.SS "CLIPPING"
.PP
or why gets some of my text deleted above the included \fI\&.eps\fR file?
.PP
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 \fI\&.eps\fR files (within LaTeX you can use
\\includegraphics*{}) for this purpose. If this is unfortunately not
the case, you can use the \fB-C\fR option of \fBps2eps\fR which will (hopefully)
do it for you. Unfortunately, PScript.dll 5.2 (Windows XP) introduced
new very badly behaving Postscript code (initclip) which will even
override the outer clipping! Thus, a new filter had to be installed
in \fBps2eps\fR which will fix it.
.PP
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 \fB-l\fR
option or \fB-C\fR option (for the latter, clipping by the importing program
should be disabled then) to allow for a 1 point larger bounding box.
\fB-C\fR clips around a 1 point enlarged bounding box and \fB-l\fR enlarges the
bounding box values by 1 point (you can also combine both options).
.SS "INCLUDED FILTERS"
.PP
Some postscript sequences, e.g., for using specific printer
features (featurebegin ...), are not working well within an \fI\&.eps\fR
file, so \fBps2eps\fR tries to filter them out. But please note that
filters for postscript code may not work properly for your printer
driver (\fBps2eps\fR 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 \fB-n\fR, or try to find the bad sequence in the postscript
code and adapt the filter rule in the \fBps2eps\fR 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.
.PP
Some applications or drivers generate postscript code with leading
or trailing binary code, which often confuses older postscript
interpreters. \fBps2eps\fR 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 section BUGS).  
.PP
Comment lines or even blank lines are removed
(which is the default to make .eps files smaller), which may corrupt your
output. Please check the next section how to fix this.
\fBps2eps\fR 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
\fBps2eps\fR detects these comments it will refrain from any filtering
action within the marked binary sections.
.PP
\fBps2eps\fR filters also %%Orientation: comments by
default (you can use option \fB-O\fR to turn off filtering),
because ghostscript may ``automagically'' rotate images when generating PDF 
images, which is not desired in most cases. Hint: you can turn off that
feature in ghostscript unconditionally by specifying -dAutoRotatePages=/None.
.SS "CORRUPTED OUTPUT"
.PP
Some postscript code may get corrupted when comment lines or even blank 
lines are removed (which is the default to make .eps files smaller), 
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 \fB-c\fR
option to prevent filtering comments.
.SS "COLOR AND MEMORY"
.PP
\fBps2eps\fR supports colored postscript, consequently
letting ghostscript consume more resources for drawing its bitmap
(roughly 6MBytes for an A4 page). \fBbbox\fR 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 \fB-m\fR option
for using a monochrome image. But this will probably result in wrongly
determined bounding boxes with colored
images, because ghostscript has to do black/white dithering and may thus suppress
objects drawn in light colors.
.SH "ENVIRONMENT VARIABLES"
.PP
Please note that a command line option always takes precedence over
the related environment variable.
.PP
The environment variable PS2EPS_SIZE can be used
to specify a default page size and take any argument that
\fB--size\fR accepts.  Examples: \fBexport PS2EPS_SIZE=a0\fR (bash-like syntax)
or \fBsetenv PS2EPS_SIZE letter\fR (csh syntax). 
.PP
If the environment variable PS2EPS_GSBBOX is set
the internal bbox device of ghostscript will be used instead of the external 
command \fBbbox\fR\&. Examples: \fBexport PS2EPS_GSBBOX=true\fR  (bash-like syntax)
or \fBsetenv PS2EPS_GSBBOX 1\fR (csh syntax).
.SH "EXAMPLES"
.PP
The usual call is simply:
\fBps2eps -l \fIfile\fB\fR
.PP
A relatively failsafe call would be (if your postscript is smaller
than iso b0 [100cm x 141.4cm] and you have a fast computer with enough memory):
\fBps2eps -l -B -s b0 -c -n \fIfile\fB\fR
.PP
If output is not correct try:
\fBps2eps -l -B -s b0 -F \fIfile\fB\fR 
.SH "AUTHOR"
.PP
\fBps2eps\fR was written by Roland Bless. 
.SS "WHY?"
.PP
Other programs like \fBps2epsi\fR do not calculate the
bounding box always correctly (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. \fBps2eps\fR uses a double precision resolution 
of 144 dpi and appropriate rounding to get a proper bounding 
box. The internal bbox device of ghostscript generates different values
(sometimes even incorrect), so using the provided \fBbbox\fR
should be more robust.
However, because normal clipping has only a resolution of 1/72dpi
(postscript point), the clipping process may still erase parts of your
EPS image. In this case please use the \fB-l\fR option to add 
an additional point of white space around the tight bounding box.
.SS "ACKNOWLEDGMENTS"
.PP
Some people contributed code or suggestions to improve \fBps2eps\fR\&. Here
are at least some names (sorry if I forgot your name):
Christophe Druet, Hans Ecke, Berend Hasselman, Erik Joergensen, Koji Nakamaru, Hans Fredrik Nordhaug
.PP
An earlier version of this manual page was originally written by 
Rafael Laboissiere <rafael at debian.org> for
the Debian system. Thank you Rafael! 
.PP
Permission is granted to copy, distribute and/or modify this document under
the terms of the GNU Free Documentation
License, Version 1.1 or any later version published by the Free
Software Foundation; with no Invariant Sections, no Front-Cover
Texts and no Back-Cover Texts.
.SH "BUGS"
.PP
If you experience problems, please check carefully all hints in the section 
TROUBLESHOOTING
first. Otherwise, check for an updated
version at  <URL:http://www.tm.uka.de/~bless/ps2eps>
or send a gzipped file of
relevant postscript source code with your error description 
and \fBps2eps\fR version number to <roland at bless.de> (please allow some time
to reply).
.SH "SEE ALSO"
.PP
bbox (1), gs (1), ps2epsi (1)