diff options
Diffstat (limited to 'Master/texmf-dist/doc/support/epspdf/epspdf.texi')
-rw-r--r-- | Master/texmf-dist/doc/support/epspdf/epspdf.texi | 511 |
1 files changed, 511 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/support/epspdf/epspdf.texi b/Master/texmf-dist/doc/support/epspdf/epspdf.texi new file mode 100644 index 00000000000..284b106bdd7 --- /dev/null +++ b/Master/texmf-dist/doc/support/epspdf/epspdf.texi @@ -0,0 +1,511 @@ +\input texinfo @c -*-texinfo -*- +@c %**start of header +@setfilename epspdf.info +@settitle Epspdf and epspdftk User Guide 0.4 +@afourpaper +@c %**end of header + +@ifhtml +@alias chapter = unnumbered +@alias section = unnumberedsec +@alias subsection = unnumberedsubsec +@end ifhtml + +@tex +\input pstexi +@end tex + +@iftex +@textfonts +@rm +@raggedbottom +@end iftex + +@set version 0.4.0 +@set homepage http://tex.aanhet.net/epspdf/ + +@setchapternewpage off +@paragraphindent none + +@copying +This manual is for epspdf, version @value{version}. + +Copyright @copyright{} 2006, 2007, 2008, 2009 Siep Kroonenberg. + +@quotation +Permission is granted to make and distribute verbatim copies of this +entire document without royalty provided the copyright notice and this +notice are preserved. +@end quotation +@end copying + +@titlepage +@sp 2 +@center @titlefont {Epspdf and epspdftk User Manual} +@sp 1 +@center A multiplatform GUI- and command-line converter for [e]ps and pdf +@sp 2 +@center Siep Kroonenberg (@email{n dot s dot kroonenberg at rug dot nl}) +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@contents + +@ifnottex +@node Top +@top Epspdf and epsdftk + +@insertcopying +@end ifnottex + +@menu +* Usage:: +* Command-line usage:: +* Notes on PostScript and pdf:: +* Troubleshooting:: +* Changes in version 0.4:: + +@detailmenu + --- The Detailed Node Listing --- + +Usage + +* Overview:: +* Viewing:: +* Conversion options:: +* Converting:: +* The configuration screen:: + +Command-line usage + +* Option summary:: + +Notes on PostScript and pdf + +* Bitmapped and vector:: +* Font embedding:: +* Eps preview headers:: +* Bounding- and other boxes:: +* Orientation:: +* Exporting PostScript from Windows programs:: + +Troubleshooting + +* Grayscaling fails:: +* Part of the graphic gets cut off:: +* Fonts look ugly:: +* Resources for troubleshooting:: + +@end detailmenu +@end menu + +@node Usage +@chapter Usage + +@menu +* Overview:: +* Viewing:: +* Conversion options:: +* Converting:: +* The configuration screen:: +@end menu + +@node Overview +@section Overview + +Epspdftk converts files between eps, pdf and general +PostScript. The main screen lets you open a file, select some options +and convert the file. + +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. + +@noindent @image{images/main_w32,,3in} +@iftex +@hfill +@end iftex +@image{images/cnv_osx,,3in} + +@node Viewing +@section Viewing + +The View button at the bottom of the screen calls an appropriate +external viewer. + +@i{Windows:} Epspdftk simply tries to use the default Open command. A +second button, labeled @i{View with...}, lets the user select a +different program to view the file. + +For OS X the viewer is also the default program, but there is no @i{View +with...} button. + +Under Linux the PostScript- and pdf viewers are +configurable; see @ref{The configuration screen}. + +The View button is grayed if epspdf thinks that there is no +previewer for the current file. + +@node Conversion options +@section Conversion options + +@anchor{gray}@i{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. + +@i{Compute tight boundingbox:} This option is only available +if a single page is converted. + +@i{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 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. + +Specifying options such as grayscaling or page selection may require +several roundtrips between PostScript or eps and pdf. + +@node Converting +@section Converting + +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. + +@node The configuration screen +@section The configuration screen + +@image{images/config_lnx,3in} + +Epspdftk also has a configuration screen. The settings here are +preserved between sessions. + +@subsection 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. + +@subsection 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. + +@subsection Options for converting to PostScript +For conversion the other way you may opt @i{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. + +@anchor{hires}@subsection 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: +@itemize @bullet +@item +When converting to pdf, it uses the standard rather than the hires +boundingbox for page dimensions +@item +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. +@end itemize + +@node Command-line usage +@chapter 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. +@example +#!/bin/sh +@var{path_to_epspdf}/epspdf.rb "@@" +@end example +for Unix/Linux/OS X, or +@example +"@var{path_to_ruby.exe}" "@var{path_to_epspdf.rb}" %* +@end example +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: + +@example +epspdf [@var{options}] @var{infile} @var{outfile} +@end example + +@menu +* Option summary:: +@end menu + +@node Option summary +@section Option summary + +The summary below is the output of a command @kbd{epspdf --help} +for help. +@example +$ 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 +@end example + +@node Notes on PostScript and pdf +@chapter Notes on PostScript and pdf + +@menu +* Bitmapped and vector:: +* Font embedding:: +* Eps preview headers:: +* Bounding- and other boxes:: +* Orientation:: +* Exporting PostScript from Windows programs:: +@end menu + +@node Bitmapped and vector +@section 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. + +@node Font embedding +@section 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. + +@node Eps preview headers +@section 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. + +@node Bounding- and other boxes +@section 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''. + +@node Orientation +@section 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. + +@node Exporting PostScript from Windows programs +@section 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. + +@image{images/ps_settings,2.5in} + +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 @url{http://www.tug.org/ctan.html}. + +@node Troubleshooting +@chapter Troubleshooting + +@menu +* Grayscaling fails:: +* Part of the graphic gets cut off:: +* Fonts look ugly:: +* Resources for troubleshooting:: +@end menu + +@node Grayscaling fails +@section Grayscaling fails + +See above, under @ref{gray,,Grayscaling}. Epspdf is +limited by what can be done by the backend tools, i.e. Ghostscript +and pdftops. In particular, epspdf cannot grayscale bitmapped data. + +@node Part of the graphic gets cut off +@section Part of the graphic gets cut off + +Things to try: +@itemize @bullet +@item +If the PostScript file was generated with the Windows PostScript driver, +experiment with the PostScript Output option. Don't choose Optimize for +Speed. +@item +Replace the extension with ``.ps'' and let epspdf generate a +boundingbox. +@item +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''. +@end itemize + +@node Fonts look ugly +@section 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. + +@node Resources for troubleshooting +@section Resources for troubleshooting + +@i{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 @file{c:\Documents and +Settings\@var{your user name}}. Otherwise, open a DOS box and type +@kbd{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. + +@i{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. + +@anchor{Documentation}@i{Ghostscript- and pdftops documentation.} For +Ghostscript, the most important files are Ps2pdf.htm and Use.htm. For +pdftops, type @kbd{pdftops -h}. For Unix, there is also a man page, and +for Windows there is a file pdftops.txt in the distribution zip. + +@node Changes in version 0.4 +@chapter 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. + +@ifhtml +@section @url{index.html,Main page} +@end ifhtml + +@bye |