diff options
Diffstat (limited to 'Master/texmf-dist/scripts/epspdf/epspdf.help')
| -rw-r--r-- | Master/texmf-dist/scripts/epspdf/epspdf.help | 485 |
1 files changed, 339 insertions, 146 deletions
diff --git a/Master/texmf-dist/scripts/epspdf/epspdf.help b/Master/texmf-dist/scripts/epspdf/epspdf.help index 5bdc475ff8d..f7d37ff3c2c 100644 --- a/Master/texmf-dist/scripts/epspdf/epspdf.help +++ b/Master/texmf-dist/scripts/epspdf/epspdf.help @@ -1,173 +1,366 @@ - Epspdf and epspdftk User Guide +Epspdf and epsdftk +****************** - A multiplatform GUI- and command-line converter for [e]ps and pdf. +This manual is for epspdf, version 0.4.0. - Siep Kroonenberg, - siepo at cybercomm dot nl +Copyright (C) 2006, 2007, 2008, 2009 Siep Kroonenberg. -Overview + Permission is granted to make and distribute verbatim copies of + this entire document without royalty provided the copyright notice + and this notice are preserved. - Epspdftk converts files between eps, pdf and general PostScript. The main - screen lets you open a file, select some options and convert the file. +1 Usage +******* - When opening a file, epspdf tries to find out file type and, in the case - of a pdf file, the number of pages. This information is displayed in the - box in the upper half of the screen. +1.1 Overview +============ -Viewing +Epspdftk converts files between eps, pdf and general PostScript. The +main screen lets you open a file, select some options and convert the +file. - The View button at the bottom of the screen calls an appropriate external - viewer. For Windows this is determined by the default Open command, for OS - X it is always Preview, and under Linux it is configurable; see below - under [1]The Configuration screen. +When opening a file, epspdf tries to find out file type and, in the +case of a pdf file, the number of pages. This information is displayed +in the box in the upper part of the screen. - The View button is grayed if epspdf thinks that there is no previewer for - the current file; see [2]the epspdf main page for details. -Conversion options - Grayscaling: Simple color figures can be converted to grayscale. - Grayscaling will fail for bitmapped data and for advanced color models. - 'Try harder to grayscale' will handle a few more cases, but may take - longer and still won't handle bitmaps. +1.2 Viewing +=========== - Call for assistance: If a PostScript color expert is reading this: please - have a look at makegray.pro and see whether you can come up with something - that handles more color models. +The View button at the bottom of the screen calls an appropriate +external viewer. - Compute tight boundingbox: This option is only available if a single page - is converted. +Windows: Epspdftk simply tries to use the default Open command. A +second button, labeled View with..., lets the user select a different +program to view the file. - Page selection: The only possibilities are selecting a single page or - selecting all pages. When converting to eps you are restricted to a single - page. +For OS X the viewer is also the default program, but there is no View +with... button. - For general PostScript files, there is no quick way to determine the - number of pages, so the program won't check beforehand whether you picked - an existing page. If you picked a non-existent page, the program will - abort. If you don't like that, convert the entire document to pdf first - - which will be done behind the scenes anyhow. +Under Linux the PostScript- and pdf viewers are configurable; see *note +The configuration screen::. - Specifying options such as grayscaling or page selection may require - several roundtrips between PostScript or eps and pdf. If epspdf cannot use - pdftops then some combinations of options will not be available. +The View button is grayed if epspdf thinks that there is no previewer +for the current file. -Converting +1.3 Conversion options +====================== - The Convert and save... button calls up a file save dialog, with - appropriate default extension. After a successful conversion, the result - becomes the new current file, so you can judge the result by pressing the - View button again. +Grayscaling: Simple color figures can be converted to grayscale. +Bitmapped data won't be converted. If grayscaling doesn't work on +non-bitmapped data, select the "Try harder to grayscale" option. This +may cause an extra pdf-PostScript roundtrip. -The configuration screen +Compute tight boundingbox: This option is only available if a single +page is converted. - Epspdftk also has a configuration screen. The settings here are preserved - between sessions. Pay particular attention to 'Intended use' under PDF - CONVERSION. Choose 'prepress' for pdfs which are intended for commercial - printing. This option will try to embed all fonts, among other things. - More and more often, printshops insist on this. With luck, Ghostscript - fonts and system fonts will be used for fonts which were not originally - embedded. +Page selection: The only possibilities are selecting a single page or +selecting all pages. When converting to eps you are restricted to a +single page. - Under Windows, this screen also lets you tell the program where to find - pdftops.exe. Under Linux, it lets you pick PostScript- and pdf previewers. +For general PostScript files, there is no quick way to determine the +number of pages, so the program won't check beforehand whether you +picked an existing page. If you picked a non-existent page, the program +will abort. If you don't like that, convert the entire document to pdf +first - which will be done behind the scenes anyhow. -Adding standard fonts to an existing pdf +Specifying options such as grayscaling or page selection may require +several roundtrips between PostScript or eps and pdf. - You can add standard fonts such as Times and Helvetica to an existing pdf: - first, convert to ps, with 'Convert all pages' selected. Then, make sure - that in the configuration screen 'Intended use' is set to prepress, then - convert back to pdf. +1.4 Converting +============== - If this option is set to screen, then standard fonts will be removed - instead of added. This option may also affect the resolution of bitmaps. +The Convert and save... button calls up a file save dialog. After a +successful conversion, the result becomes the new current file, so you +can judge the result by pressing the View button again. -Eps preview headers +1.5 The configuration screen +============================ - Preview headers are quietly stripped from eps files. These preview headers - are used by e.g. desktop-publishing software to represent eps files on - screen without having to interpret the PostScript code itself. Epspdf - currently has no option to preserve or add them. + Epspdftk also has a configuration screen. The settings here are +preserved between sessions. -On-the-fly conversion +1.5.1 Configuring viewers +------------------------- + +Under Linux, the preferred PostScript- and pdf viewers can be configured +in this screen. Epspdf looks for a number of PostScript- and pdf +viewers, from which you can select one, but you can also enter one +manually. + +For Windows and Mac OS X, there is no such configuration option. Epspdf +will use the program associated with the file type, which can be +configured outside epspdf. Under Windows, you can use the "View +with..." button instead. + +1.5.2 Options for converting to pdf +----------------------------------- + +Double-check the setting "Target use" under "Conversion to pdf". Choose +"prepress" for pdfs which are target for commercial printing. This +option will try to embed all fonts, among other things. Often, +printshops insist on this. With luck, Ghostscript fonts and system +fonts will be used for fonts which were not originally embedded. + +On the other hand, you may prefer "screen" if file size is a concern. +See also the Ghostscript documentation, in particular Use.htm and +Ps2pdf.htm. + +1.5.3 Options for converting to PostScript +------------------------------------------ + +For conversion the other way you may opt not to use pdftops even if it +is available. In this case, the conversion will be done by Ghostscript. +Characters may be converted to drawn shapes or little bitmaps so this +is not recommended. + +Under Windows, this is also the place to point the program to the +location of pdftops.exe. + +1.5.4 Hires BoundingBox +----------------------- + +Uncheck the option "Use hires boundingbox if possible" if otherwise the +computed boundingbox is slightly too tight, resulting in some clipping. +It has two effects: + * When converting to pdf, it uses the standard rather than the hires + boundingbox for page dimensions + + * When computing a boundingbox, it adds a small safety margin of 1pt + to the standard boundingbox, except where it would make any + boundingbox coordinate negative. + +2 Command-line usage +******************** + +epspdf.rb, the library for epspdftk.rb, does double duty as command-line +version of epspdftk.rb. It shares configuration settings with +epspdftk.rb. + +It is strongly recommended to invoke epspdf.rb via a wrapper script +epspdf or epspdf.bat on the search path, e.g. + #!/bin/sh + PATH_TO_EPSPDF/epspdf.rb "@" +for Unix/Linux/OS X, or + "PATH_TO_RUBY.EXE" "PATH_TO_EPSPDF.RB" %* +for Windows. It is the responsibility of the caller to provide double +quotes. + +The TeX Live package for epspdf already includes such wrapper scripts. + +Basic usage: + + epspdf [OPTIONS] INFILE OUTFILE + +2.1 Option summary +================== + +The summary below is the output of a command `epspdf --help' for help. + $ epspdf --help + Epspdf version 0.4.0 + Copyright (C) 2006, 2008, 2009 Siep Kroonenberg + Epspdf 0.4.0 + Convert between [e]ps and pdf formats + Usage: epspdf.rb [options] infile [outfile] + Default for outfile is file.pdf if infile is file.eps or file.ps + Default for outfile is file.eps if infile is file.pdf + -g, --gray, --grey Convert to grayscale; + success not guaranteed + -G, --GRAY, --GREY Try harder to convert to grayscale + -p, --pagenumber=PAGENUMBER Page to be converted or selected + -b, --bbox, --BoundingBox Compute tight boundingbox + -n, --no-hires Don't use hires boundingbox + -r, --hires Use hires boundingbox + -T, --target=TARGET Target use of pdf; one of + default, printer, prepress, screen, ebook + -N, --pdfversion=PDFVERSION Pdf version to be generated + -V, --version=PDFVERSION Deprecated; use `-N' or `--pdfversion'. + -I Ignore pdftops even if available + (default: use if available) + -U Use pdftops if available + (overrides previous -I setting) + -C, --custom=CUSTOMOPTIONS Custom options for conversion to pdf, + view Use.htm and ps2pdf.htm from + the Ghostscript documentation set + -P, --psoptions=PSOPTIONS Options for pdftops; default -level3, + don't include -eps or page number options; + these will be generated by the program + -i, --info Info: display detected filetype + -s Save (some) settings + -d Debug: don't remove temp files + -v Prints version info + -h, --help Show this message + +3 Notes on PostScript and pdf +***************************** + +3.1 Bitmapped and vector +======================== + +Pictures can be described either in terms of pixels, or more abstractly, +in terms of geometric shapes, fonts and text. + +Bitmapped or pixel-based graphics are appropriate for photographs and +screenshots, but less so for diagrams and spreadsheet-generated +graphics. + +A file in PostScript- or pdf format can contain both types of graphic +data, e.g. a text in vector format agains a photographic background in +bitmapped format. + +Vector graphics can be freely scaled without losing sharpness or +becoming pixellated. If bitmapped graphics are enlarged too much, +individual pixels become apparent. With low-resolution bitmaps this +happens sooner than with high-resolution bitmaps, but high-resolution +bitmaps have (much) larger file sizes, and take longer to process. + +So avoid converting vector to bitmap. However, converting from bitmap to +vector is also best avoided, since it is very hard to do well. + +Epspdf normally avoids conversion from vector to bitmap and never +converts the other way. With the screen- and ebook "Target use" option, +included bitmaps tend to be downsampled, i.e. reduced to a lower +resolution. + +3.2 Font embedding +================== + +When converting to pdf, Ghostscript handles font embedding differently +depending on the "Target use" option. For prepress, it embeds even the +standard fonts, including Times etc. Ghostscript has copies of these +fonts in case the PostScript file doesn't have them. For screen, it +doesn't embed standard fonts. + +You can embed fonts after the fact by converting pdf to eps or ps, and +back to pdf, with target use set to "prepress". However, don't try this +unless you have pdftops. + +If target use is set to "screen", then standard fonts will be removed +instead of added. This option may also cause downsampling of bitmaps. + +3.3 Eps preview headers +======================= + +Preview headers are quietly stripped from eps files. These preview +headers are used by e.g. desktop-publishing software to represent eps +files on screen without having to interpret the PostScript code itself. +Epspdf currently has no option to preserve or add them. + +3.4 Bounding- and other boxes +============================= + +A PostScript file may have a page size and a boundingbox defined. A pdf +file may have a mediabox, a trimbox and various other boxes. Ghostscript +by itself normally converts the PostScript page - which is anchored at +(0,0) - to the pdf mediabox. + +When epspdf or a similar program converts eps to pdf, it adds code to +move the bottom left corner of the graphic to (0,0) and to set the page +to the size of the graphic. Anything outside the boundingbox should be +cut off. + +Both Ghostscript and pdftops have some parameters for setting or using +these boxes; consult Ps2pdf.htm from the Ghostscript documentation and +"pdftops -help" or "man pdftops". + +3.5 Orientation +=============== + +There appears to be no reliable way to set orientation for PostScript- +and pdf files. This may result part of a graphic being cut off after +conversion or even everything falling outside the page / mediabox / +boundingbox. It may help to change the extension from ".eps" to ".ps" +before converting to pdf. In this case, let epspdf generate a new +boundingbox. + +3.6 Exporting PostScript from Windows programs +============================================== + +Often, the only way to get EPS or PostScript from a Windows program is +by "printing" to a PostScript file. From some programs, you can print a +selection. A suitable driver which comes with Windows is Generic / MS +Publisher Imagesetter. Pay attention to the printer properties: choose +"Outline" for font downloading and avoid the "Optimize for speed" +setting for PostScript Output Option. Try e.g. "Archive" instead. These +options can be found under the Advanced button. + + Other possibilities are the TpX and wmf2eps programs, which both have +options to write clipboard contents to an emf file. Wmf2eps uses a +printer driver in the background. For faithful conversion, pick +wmf2eps; for subsequent editing, choose TpX. Both programs are +available from `http://www.tug.org/ctan.html'. + +4 Troubleshooting +***************** + +4.1 Grayscaling fails +===================== + +See above, under *note Grayscaling: gray. Epspdf is limited by what can +be done by the backend tools, i.e. Ghostscript and pdftops. In +particular, epspdf cannot grayscale bitmapped data. + +4.2 Part of the graphic gets cut off +==================================== + +Things to try: + * If the PostScript file was generated with the Windows PostScript + driver, experiment with the PostScript Output option. Don't choose + Optimize for Speed. + + * Replace the extension with ".ps" and let epspdf generate a + boundingbox. + + * Boundingbox calculations may be slightly inaccurate where text is + involved. If just a sliver is cut off, let epspdf ignore the + high-resolutuion boundingbox. Command-line option: "-n" or + "-no-hires". + +4.3 Fonts look ugly +=================== + +If Ghostscript has to do the conversion from pdf to ps then text will +not remain text, but will be replaced by drawn shapes or bitmaps. Try +to get hold of the xpdf suite, which includes pdftops, especially if +your files contain serious amount of text. + +4.4 Resources for troubleshooting +================================= + +Logfile. Epspdf and epspdftk maintain a log file epspdf.log in your +home directory or, in case of Windows, your profile directory. This +profile directory may be `c:\Documents and Settings\YOUR USER NAME'. +Otherwise, open a DOS box and type `echo %USERPROFILE%', which will +produce this information. + +This logfile lists all Ghostscript- and pdftops program calls plus +error information. "EPCallError" is probably a program error. +'EPSystemError" is more likely caused by a faulty file, but may be a +program error as well. + +Temporary files. The temporary files may give clues as well. They will +be deleted at the end of the session (for the command-line version, +give a -d parameter to keep the temporary files). Check the logfile as +to which temporary files have been created. + +Ghostscript- and pdftops documentation. For Ghostscript, the most +important files are Ps2pdf.htm and Use.htm. For pdftops, type `pdftops +-h'. For Unix, there is also a man page, and for Windows there is a +file pdftops.txt in the distribution zip. + +5 Changes in version 0.4 +************************ + +Hi-res boundingboxes are now supported. By default, conversion from eps +to pdf now uses the hires boundingbox as "page" to determine the page +dmensions of the pdf file. Other conversions preserve or generate a +hires boundingbox. + +Under Windows, the new version looks for an installed TeX and will use +its private Ghostscript if it cannot find separately installed +Ghostscript. TeX Live's pdftops, being on the searchpath, will be used +unless epspdf finds another copy first. + +There is now a "-v" (lowercase) option to print the version string. - Daniel Becker wrote a LaTeX package epspdfconversion which converts eps - files on the fly to pdf, like Heiko Oberdiek's epstopdf package, but with - epspdf as backend. It can make use of the epspdf conversion options. Both - packages are available from [3]CTAN and included in TeX Live. - -Exporting PostScript from Windows programs - - Often, the only way to get EPS or PostScript from a Windows program is by - 'printing' to a PostScript file. From some programs, you can print a - selection. A suitable driver which comes with Windows is Generic / MS - Publisher Imagesetter. Pay attention to the printer properties: avoid the - 'Optimize for speed' setting and choose Outline for font downloading. - These options can be found under the Advanced button. - - Other possibilities are the TpX and wmf2eps programs, which both have - options to write clipboard contents to an emf file. Wmf2eps uses a printer - driver in the background. For faithful conversion, pick wmf2eps; for - subsequent editing, choose TpX. Both programs are availbable from [4]CTAN. - -Command-line use - - Epspdf.rb, the library for epspdftk.rb, does double duty as command-line - version of epspdftk.rb. Type epspdf.rb -h for help. It shares - configuration settings with epspdftk. - -Troubleshooting - - Grayscaling fails - - See above, under [5]Grayscaling. Epspdf is limited by what can be done by - the backend tools, i.e. Ghostscript and pdftops. - - Part of the graphic gets cut off - - I have seen this happen with eps files generated by printing landscape - PowerPoint slides to PostScript with the Encapsulated PostScript output - option. Using the Archive output option instead solved the problem. In - general, experiment a bit in generating your PostScript. - - Mac OS X problems with epspdftk - - Even though epspdftk is not an X11 program, you may still need some pieces - of X11 and the X11 SDK, which are optional installs of OS X. - - Under Leopard, the window that is displayed during the conversion stays - blank. I have no idea why. - - Resources for troubleshooting - - Logfile. Epspdf and epspdftk maintain a log file. For Unix and Mac OS X it - is epspdf.log in your home directory. For Windows, it is epspdf.log or - epspdftl.log in your profile directory. The latter filename is used if - epspdf is embedded in TeX Live. This profile directory may be c:\Documents - and Settings\<your user name>. Otherwise, open a DOS box and type 'echo - %USERPROFILE%', which will produce this information. - - This logfile lists all Ghostscript- and pdftops program calls plus error - information. 'EPCallError' is probably a program error. 'EPSystemError' is - more likely caused by a faulty file, but may be a program error as well. - - Temporary files. The temporary files may give clues as well. They will be - deleted at the end of the session (for the command-line version, give a -d - parameter to keep the temporary files). The logfile can tell you which - temporary files have been created. - - [6]Main page... - - -------------------------------------------------------------------------- - - Last revised: July 27, 2008 - -References - - Visible links - 1. http://tex.aanhet.net/epspdf/epspdf_UG.html#configure - 2. http://tex.aanhet.net/epspdf/index.html#preview - 3. http://www.tug.org/ctan.html - 4. http://www.tug.org/ctan.html - 5. http://tex.aanhet.net/epspdf/epspdf_UG.html#gray - 6. http://tex.aanhet.net/epspdf/index.html |