summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/support/epspdf/epspdf.texi
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/support/epspdf/epspdf.texi')
-rw-r--r--Master/texmf-dist/doc/support/epspdf/epspdf.texi511
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