Debian Codegraph @

texmf-dist/doc/man/man1/ps2eps.1

raw
1 .\" This manpage has been automatically generated by docbook2man
2 .\" from a DocBook document. This tool can be found at:
3 .\" <http://shell.ipoline.com/~elmert/comp/docbook2X/>
4 .\" Please send any bug reports, improvements, comments, patches,
5 .\" etc. to Steve Cheng <[email protected]>.
6 .TH "PS2EPS" "1" "September 1st, 2018" "" ""
7
8 .SH NAME
9 ps2eps \- convert PostScript to EPS (Encapsulated PostScript) files
10 .SH SYNOPSIS
11
12 \fBps2eps\fR [ \fB-f\fR ] [ \fB-q\fR ] [ \fB-N\fR ] [ \fB-O\fR ] [ \fB-X\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 ]
13
14 .SH "DESCRIPTION"
15 .PP
16 This manual page documents \fBps2eps\fR version 1.70.
17 .PP
18 \fBps2eps\fR is a tool (written in Perl) to produce
19 Encapsulated PostScript Files (EPS/EPSF) from usual one-paged Postscript
20 documents. It calculates correct Bounding Boxes for those EPS files and
21 filters some special postscript command sequences that can produce
22 erroneous results on printers. EPS files are often needed for including
23 (scalable) graphics of high quality into TeX/LaTeX (or even Word) documents.
24 It can also be used to calculate correct BoundingBoxes for PDF files by
25 using the option \fB--BBonly\fR\&. However, it cannot produce
26 a PDF file, but it can be used together with \fBpdfcrop\fR\&.
27 .PP
28 Without any argument, ps2eps reads from standard input
29 and writes to standard output.
30 If filenames are given as arguments they are processed
31 one by one and output files are written to filenames
32 with extension \fI\&.eps\fR\&. If input filenames have the
33 extension \fI\&.ps\fR or \fI\&.prn\fR, this extension is replaced with \fI\&.eps\fR\&.
34 In all other cases \fI\&.eps\fR is appended to the input filename.
35 Please note that PostScript files for input should contain
36 only one single page (you can possibly use the \fBpsselect\fR from the
37 psutils package to extract a single page from a document that
38 contains multiple pages).
39 .PP
40 If BoundingBox in output seems to be wrong, please try options \fB--size\fR or
41 \fB--ignoreBB\fR\&. See also section TROUBLESHOOTING.
42 .SH "OPTIONS"
43 .PP
44 \fBps2eps\fR follows the usual GNU command line syntax,
45 with long options starting with two dashes (`-'). A summary of
46 options is included below.
47 .TP
48 \fB-h, --help \fR
49 Show summary of options.
50 .TP
51 \fB-V, --version \fR
52 Show version of program.
53 .TP
54 \fB-f, --force \fR
55 Force overwriting existing files. \fBps2eps\fR
56 will not overwrite files by default to avoid deleting original EPS
57 files accidently.
58 .TP
59 \fB-q, --quiet \fR
60 quiet operation (no output while processing files, except errors).
61 .TP
62 \fB-N, --noinsert \fR
63 do not insert any postscript code. Normally a few postscript
64 instructions are added around the original postscript code by
65 \fBps2eps\fR which can be turned off by this option.
66 .TP
67 \fB-O, --preserveorientation \fR
68 do not filter %%Orientation: header comment.
69 .TP
70 \fB-X, --BBonly \fR
71 Just print the resulting bounding box(es) to standard error, no output file is written.
72 \fBps2eps\fR will perform a read-only operation. This is highly useful to calculate bounding boxes of
73 PDF files. Can be used with option \fB--quiet\fR to suppress other output and
74 also with \fB--nohires\fR to suppress output of the HiResBoundingBox.
75 It can be used with \fBpdfcrop\fR as follows:
76 \fBpdfcrop --gscmd 'gswrap-ps2eps.sh' file.pdf\fR
77 where \fBgswrap-ps2eps.sh\fR containts something like
78 \fBps2eps -l -X -q $BASH_ARGV\fR
79 .TP
80 \fB-n, --nofix \fR
81 do not try to fix postscript code by filtering some instructions.
82 .TP
83 \fB-P, --removepreview \fR
84 remove preview image (smaller file, but no preview anymore).
85 .TP
86 \fB-F, --fixps \fR
87 fix postscript code unconditionally. Otherwise, filtering is
88 usually triggered by detection of certain drivers only.
89 .TP
90 \fB-c, --comments \fR
91 preserve document structure comments.
92 .TP
93 \fB-C, --clip \fR
94 insert postscript code for clipping. Unless
95 \fB--nohires\fR is specified, the HiResBoundingBox
96 (enlarged by 0.1 points) is used for clipping.
97 .TP
98 \fB-m, --mono \fR
99 use black/white bitmap as base for calculation (default: off).
100 .TP
101 \fB-s, --size=pagedim \fR
102 where pagedim is a pre-defined standard page size
103 (e.g., a4,a0,b0,letter,...) or explicitly specified in a
104 format pagedim:=\fIX\fRx\fIY\fR[cm|in],
105 where \fIX\fR and \fIY\fR are numbers (floating points are accepted) followed by
106 units centimeter (cm) or inch (in), (default: cm).
107 Use \fB--size=list\fR to list pre-defined pagesizes.
108 See also environment variable PS2EPS_SIZE\&.
109 .TP
110 \fB-t, --translate=x,y \fR
111 specify an x,y offset (may be negative) in postscript points
112 (1/72 dpi) for drawing. This option may be required
113 if your drawing has negative coordinates which usually lets ghostscript
114 cut the negative part of your picture, because it starts to render
115 at positive coordinates. The resulting output will
116 also be shifted.
117 .TP
118 \fB-r, --resolution=dpi \fR
119 specify a resolution in dpi (dots per inch) for drawing under
120 ghostscript. Default
121 resolution is 144 dpi which is the double of the typical 72 dpi.
122 This option may help if there is a hardware dependent resolution
123 encoded in the postscript, e.g., 600dpi. Example:
124 \fBps2eps -l -r 600 test.ps\fR
125 .TP
126 \fB-R, --rotate=direction \fR
127 This option rotates the resulting EPS output.
128 The parameter direction determines the direction of
129 rotation: + means +90 degrees (clockwise),- means -90 degrees
130 (counter-clockwise), and ^ means 180 degrees (up-side down).
131 .TP
132 \fB-l, --loose \fR
133 expand the original tight bounding box by one point in each
134 direction.
135 .TP
136 \fB-B, --ignoreBB \fR
137 do not use existing bounding box as page size for
138 rendering.
139 .TP
140 \fB-E, --ignoreEOF \fR
141 do not use %%EOF as hint for end of file. Otherwise, \fBps2eps\fR assumes
142 that postscript code ends after the last %%EOF comment, because
143 some drivers add trailing binary ``garbage'' code which gets deleted
144 by \fBps2eps\fR by default.
145 .TP
146 \fB-g, --gsbbox \fR
147 use internal bbox device of ghostscript instead of the external C
148 program \fBbbox\fR\&. The internal bbox device of ghostscript
149 generates different values (sometimes even incorrect),
150 so using the provided \fBbbox\fR should be more robust.
151 See also environment variable PS2EPS_GSBBOX\&.
152 .TP
153 \fB-H, --nohires \fR
154 do not generate a %%HiResBoundingBox comment for output.
155 .TP
156 \fB-a, --accuracy \fR
157 increase the accuracy by turning subsample antialiasing on (may be slower)
158 .TP
159 \fB-L, --license \fR
160 show licensing information.
161 .TP
162 \fB-d, --debuggs \fR
163 show ghostscript call. This may be helpful for solving problems that
164 occur during a ghostscript call.
165 .TP
166 \fB-W, --warnings \fR
167 show warnings about sanity of generated EPS file. Certain
168 postscript commands should not be contained in an EPS file.
169 With this option set \fBps2eps\fR will issue a warning if it
170 detects at least one of them.
171 .SH "TROUBLESHOOTING"
172 .PP
173 Based on the given postscript source code (in most cases generated by
174 some postscript printer driver) there are many potential obstacles or
175 problems that may occur when trying to create proper EPS files. Please
176 read this section carefully to be aware of common pitfalls.
177 .SS "INCOMPLETE/CLIPPED IMAGES"
178 .PP
179 or how to determine the right size for ghostscript.
180 .PP
181 If you have documents that are larger than your
182 ghostscript default (usually A4 or US letter), you have to
183 specify the page dimensions explicitly using the
184 \fB-s\fR option. Otherwise your EPS
185 might be cut off during rasterizing by ghostscript resulting
186 in a wrongly calculated bounding box. You can pass
187 all pre-defined page sizes to \fB-s\fR that ghostscript understands. These are
188 currently: 11x17, ledger, legal, letter, lettersmall, archA, archB, archC, archD, archE
189 a0, a1, a2, a3, a4, a5, a6, a7, a8, a9, a10, isob0, isob1, isob2, isob3, isob4, isob5, isob6,
190 b0, b1, b2, b3, b4, b5, c0, c1, c2, c3, c4, c5, c6, jisb0, jisb1,
191 jisb2, jisb3, jisb4, jisb5, jisb6, flsa, flse, halfletter.
192 Unfortunately, all sizes are currently only available in portrait
193 orientation (not landscape).
194 .PP
195 By default, \fBps2eps\fR uses an already given %%BoundingBox
196 from the source file, which often corresponds to the size of
197 the physical page format for which the document was
198 printed. However, you should be aware that this already
199 specified bounding box may be not correct, thus resulting in a
200 wrongly cropped (or even no usable) \fI\&.eps\fR-file.
201 \fBps2eps\fR can only do as good as ghostscript does in rendering the original
202 postscript file (though \fBps2eps\fR even works with negative and
203 fractional values are contained in the original bounding box by using
204 automatic translation). Therefore, if the given bounding box is to
205 small or incorrect anyway, you can ignore the existing bounding box with the \fB-B\fR
206 option, which will cause ghostscript to use its internal
207 default size (or use \fB-s\fR). However, if the
208 BoundingBox has negative coordinates, which is not allowed by
209 the specification, \fBps2eps\fR will shift the output to positive values.
210 .PP
211 Hint: to avoid rotating the picture
212 if you have the original drawing in landscape format, you may
213 use the ``Encapsulated Postscript'' option in the printer driver
214 which should generate an EPS file (but with a bounding box of
215 the sheet size!). But some Windows printer drivers are drawing
216 the image with an offset from the bottom of the portrait page,
217 so that a part of it is drawn outside the landscape oriented
218 page. In this case, you'll have to specify a square size of
219 the page using the maximum length, e.g., 29.7cm x 29.7cm for
220 an A4 page.
221 .SS "CLIPPING"
222 .PP
223 or why gets some of my text deleted above the included \fI\&.eps\fR file?
224 .PP
225 Some postscript drivers draw a white rectangle from the top left
226 corner of the page to the right lower corner of the object. This may
227 erase some or even all text above your imported/included EPS file,
228 which is very annoying. In order to prevent this, most programs have a
229 clipping option for imported \fI\&.eps\fR files (within LaTeX you can use
230 \\includegraphics*{}) for this purpose. If this is unfortunately not
231 the case, you can use the \fB-C\fR option of \fBps2eps\fR which will (hopefully)
232 do it for you. Unfortunately, PScript.dll 5.2 (Windows XP) introduced
233 new very badly behaving Postscript code (initclip) which will even
234 override the outer clipping! Thus, a new filter had to be installed
235 in \fBps2eps\fR which will fix it.
236 .PP
237 However, because most programs clip directly on the bounding box,
238 you still may loose some pixels of your image, because the bounding
239 box is described in the coarse resolution of postscript points,
240 i.e. 72 dpi. In order to prevent this, you can use the \fB-l\fR
241 option or \fB-C\fR option (for the latter, clipping by the importing program
242 should be disabled then) to allow for a 1 point larger bounding box.
243 \fB-C\fR clips around a 1 point enlarged bounding box and \fB-l\fR enlarges the
244 bounding box values by 1 point (you can also combine both options).
245 .SS "INCLUDED FILTERS"
246 .PP
247 Some postscript sequences, e.g., for using specific printer
248 features (featurebegin ...), are not working well within an \fI\&.eps\fR
249 file, so \fBps2eps\fR tries to filter them out. But please note that
250 filters for postscript code may not work properly for your printer
251 driver (\fBps2eps\fR was mainly tested with HP and Adobe printer
252 drivers, although it may work for all printers using the
253 PScript.dll). In this case you can try to turn of filtering by
254 using option \fB-n\fR, or try to find the bad sequence in the postscript
255 code and adapt the filter rule in the \fBps2eps\fR script (variables
256 $linefilter, $rangefilter_begin, $rangefilter_end; linefilter is
257 an expression for filtering single lines, rangefilter_... are
258 expressions that filter all lines between a pattern matching
259 $rangefilter_begin and $rangefilter_end; drop me an e-mail with
260 your modifications). However, things may change as the printer
261 drivers (e.g., PScript.dll) or postscript language evolve.
262 .PP
263 Some applications or drivers generate postscript code with leading
264 or trailing binary code, which often confuses older postscript
265 interpreters. \fBps2eps\fR tries to remove such code, but it may
266 sometimes make a wrong guess about start and end of the real
267 postscript code (drop me an e-mail with a zipped postscript
268 source, see section BUGS).
269 .PP
270 Comment lines or even blank lines are removed
271 (which is the default to make .eps files smaller), which may corrupt your
272 output. Please check the next section how to fix this.
273 \fBps2eps\fR removes blank lines and also <CR> (carriage ceturn
274 ``\\r'') at the end of lines. However, nicely formatted postscript code
275 gives a hint by using ``%%BeginBinary'' ``%%EndBinary'' comments. When
276 \fBps2eps\fR detects these comments it will refrain from any filtering
277 action within the marked binary sections.
278 .PP
279 \fBps2eps\fR filters also %%Orientation: comments by
280 default (you can use option \fB-O\fR to turn off filtering),
281 because ghostscript may ``automagically'' rotate images when generating PDF
282 images, which is not desired in most cases. Hint: you can turn off that
283 feature in ghostscript unconditionally by specifying -dAutoRotatePages=/None.
284 .SS "CORRUPTED OUTPUT"
285 .PP
286 Some postscript code may get corrupted when comment lines or even blank
287 lines are removed (which is the default to make .eps files smaller),
288 because those files may contain encoded images
289 which also have a % as first character in a line or use a special
290 comment as end of image delimiter. If this is the case, use the \fB-c\fR
291 option to prevent filtering comments.
292 .SS "COLOR AND MEMORY"
293 .PP
294 \fBps2eps\fR supports colored postscript, consequently
295 letting ghostscript consume more resources for drawing its bitmap
296 (roughly 6MBytes for an A4 page). \fBbbox\fR is reading
297 the bitmap line by line so it consumes only minimal memory. If you experience problems
298 with memory consumption of ghostscript, you may use the \fB-m\fR option
299 for using a monochrome image. But this will probably result in wrongly
300 determined bounding boxes with colored
301 images, because ghostscript has to do black/white dithering and may thus suppress
302 objects drawn in light colors.
303 .PP
304 Another option in case of memory problems and too long run times
305 is to use the much more memory efficient internal ghostscript bbox by using the
306 \fB-g\fR option.
307 .SH "ENVIRONMENT VARIABLES"
308 .PP
309 Please note that a command line option always takes precedence over
310 the related environment variable.
311 .PP
312 The environment variable PS2EPS_SIZE can be used
313 to specify a default page size and take any argument that
314 \fB--size\fR accepts. Examples: \fBexport PS2EPS_SIZE=a0\fR (bash-like syntax)
315 or \fBsetenv PS2EPS_SIZE letter\fR (csh syntax).
316 .PP
317 If the environment variable PS2EPS_GSBBOX is set
318 the internal bbox device of ghostscript will be used instead of the external
319 command \fBbbox\fR\&. Examples: \fBexport PS2EPS_GSBBOX=true\fR (bash-like syntax)
320 or \fBsetenv PS2EPS_GSBBOX 1\fR (csh syntax).
321 .SH "EXAMPLES"
322 .PP
323 The usual call is simply:
324 \fBps2eps -l \fIfile\fB\fR
325 .PP
326 A relatively failsafe call would be (if your postscript is smaller
327 than iso b0 [100cm x 141.4cm] and you have a fast computer with enough memory):
328 \fBps2eps -l -B -s b0 -c -n \fIfile\fB\fR
329 .PP
330 If output is not correct try:
331 \fBps2eps -l -B -s b0 -F \fIfile\fB\fR
332 .SH "AUTHOR"
333 .PP
334 \fBps2eps\fR was written by Roland Bless.
335 .SS "WHY?"
336 .PP
337 Other programs like \fBps2epsi\fR do not calculate the
338 bounding box always correctly (because the values are put on the
339 postscript stack which may get corrupted by bad postscript code) or
340 rounded it off so that clipping the EPS cut off some part of the
341 image. \fBps2eps\fR uses a double precision resolution
342 of 144 dpi and appropriate rounding to get a proper bounding
343 box. The internal bbox device of ghostscript generates different values
344 (sometimes even incorrect), so using the provided \fBbbox\fR
345 should be more robust.
346 However, because normal clipping has only a resolution of 1/72dpi
347 (postscript point), the clipping process may still erase parts of your
348 EPS image. In this case please use the \fB-l\fR option to add
349 an additional point of white space around the tight bounding box.
350 .SS "ACKNOWLEDGMENTS"
351 .PP
352 Some people contributed code or suggestions to improve \fBps2eps\fR\&. Here
353 are at least some names (sorry if I forgot your name):
354 Christophe Druet, Hans Ecke, Berend Hasselman, Erik Joergensen, Koji Nakamaru, Hans Fredrik Nordhaug, Michael Sharpe.
355 Special thanks goes to Michael Sharpe from UCSD who suggested a lot of useful features for ps2eps and
356 who fixed bbox to become more precise and robust.
357 .PP
358 An earlier version of this manual page was originally written by
359 Rafael Laboissiere <rafael at debian.org> for
360 the Debian system. Thank you Rafael!
361 .PP
362 Permission is granted to copy, distribute and/or modify this document under
363 the terms of the GNU Free Documentation
364 License, Version 1.1 or any later version published by the Free
365 Software Foundation; with no Invariant Sections, no Front-Cover
366 Texts and no Back-Cover Texts.
367 .SH "BUGS"
368 .PP
369 If you experience problems, please check carefully all hints in the section
370 TROUBLESHOOTING
371 first. Otherwise, check for an updated
372 version at <URL:http://www.tm.uka.de/~bless/ps2eps>
373 or send a gzipped file of
374 relevant postscript source code with your error description
375 and \fBps2eps\fR version number to <roland at bless.de> (please allow some time
376 to reply).
377 .SH "SEE ALSO"
378 .PP
379 bbox (1), gs (1), ps2epsi (1)