summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/man/man1/ps2eps.1
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2013-04-07 18:26:53 +0000
committerKarl Berry <karl@freefriends.org>2013-04-07 18:26:53 +0000
commitb04c2e1a42573e9735547702356c7b9a769a6855 (patch)
treec0753443f39500a062d7698fe6b94359c813f871 /Master/texmf-dist/doc/man/man1/ps2eps.1
parentfb0bf13304a356f197bfc1add17f98c07e96f17b (diff)
texmf -> texmf-dist: doc
git-svn-id: svn://tug.org/texlive/trunk@29714 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/man/man1/ps2eps.1')
-rw-r--r--Master/texmf-dist/doc/man/man1/ps2eps.1366
1 files changed, 366 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/man/man1/ps2eps.1 b/Master/texmf-dist/doc/man/man1/ps2eps.1
new file mode 100644
index 00000000000..d74e88ca34f
--- /dev/null
+++ b/Master/texmf-dist/doc/man/man1/ps2eps.1
@@ -0,0 +1,366 @@
+.\" 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" "31 August 2010" "" ""
+
+.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-a\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.68.
+.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-a, --accuracy \fR
+increase the accuracy by turning subsample antialiasing on (may be slower)
+.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.
+.PP
+Another option in case of memory problems and too long run times
+is to use the much more memory efficient internal ghostscript bbox by using the
+\fB-g\fR option.
+.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, Michael Sharpe.
+Special thanks goes to Michael Sharpe from UCSD who suggested a lot of useful features for ps2eps and
+who fixed bbox to become more precise and robust.
+.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)