diff options
author | Karl Berry <karl@freefriends.org> | 2008-07-26 18:10:58 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2008-07-26 18:10:58 +0000 |
commit | 792834f087e5d6fa723eb7b0101693636a22d533 (patch) | |
tree | 94ec1000d52586974175b16f8f1ab06969a153fd /Master/texmf/doc/man/man1/ps2eps.1 | |
parent | fe136e3276dbd8a40f1a1ac60a756cfdfe68ee50 (diff) |
update man pages from la(te)st build
git-svn-id: svn://tug.org/texlive/trunk@9788 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf/doc/man/man1/ps2eps.1')
-rw-r--r-- | Master/texmf/doc/man/man1/ps2eps.1 | 357 |
1 files changed, 357 insertions, 0 deletions
diff --git a/Master/texmf/doc/man/man1/ps2eps.1 b/Master/texmf/doc/man/man1/ps2eps.1 new file mode 100644 index 00000000000..4c0c674ada8 --- /dev/null +++ b/Master/texmf/doc/man/man1/ps2eps.1 @@ -0,0 +1,357 @@ +.\" 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) |