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.texi424
1 files changed, 203 insertions, 221 deletions
diff --git a/Master/texmf-dist/doc/support/epspdf/epspdf.texi b/Master/texmf-dist/doc/support/epspdf/epspdf.texi
index 3564ea97765..d1150537efc 100644
--- a/Master/texmf-dist/doc/support/epspdf/epspdf.texi
+++ b/Master/texmf-dist/doc/support/epspdf/epspdf.texi
@@ -1,7 +1,13 @@
\input texinfo @c -*-texinfo -*-
@c %**start of header
@setfilename epspdf.info
-@settitle Epspdf and epspdftk User Guide 0.5
+@settitle Epspdf and epspdftk User Guide 0.6
+
+@dircategory TeX
+@direntry
+* EpsPDF: (epspdf). Portable GUI- and command-line EPS/PS/PDF conversion
+@end direntry
+
@afourpaper
@c %**end of header
@@ -22,7 +28,7 @@
@hyphenation{epspdf-tk epspdf}
@end iftex
-@set version 0.5.3
+@set version 0.6.0
@set homepage http://tex.aanhet.net/epspdf/
@setchapternewpage off
@@ -31,7 +37,7 @@
@copying
This manual is for epspdf, version @value{version}.
-Copyright @copyright{} 2006, 2008, 2009, 2010, 2011 Siep Kroonenberg.
+Copyright @copyright{} 2006, 2008, 2009, 2010, 2011, 2013 Siep Kroonenberg.
@quotation
Copying and distribution of this file, with or without modification,
@@ -47,7 +53,7 @@ without any warranty.
@sp 2
@center @titlefont {Epspdf and epspdftk User Manual}
@sp 1
-@center A multiplatform GUI- and command-line converter for [e]ps and pdf
+@center A cross-platform 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
@@ -57,78 +63,96 @@ without any warranty.
@contents
@ifnottex
-@node Top, Usage, (dir), (dir)
+@node Top, What has changed?, (dir), (dir)
@top Epspdf and epsdftk
@insertcopying
@end ifnottex
@menu
-* Usage::
-* Command-line usage::
-* Notes on PostScript and pdf::
-* Bitmapped graphics for @LaTeX{} and pdflatex::
-* Troubleshooting::
-* Change history::
+* What has changed?::
+* Usage::
+* Command-line usage::
+* Notes on PostScript and pdf::
+* Bitmapped graphics for @LaTeX{} and pdflatex::
+* Troubleshooting::
+* Change history::
@detailmenu
--- The Detailed Node Listing ---
Usage
-* Overview::
-* Viewing::
-* Conversion options::
-* Converting::
-* The configuration screen::
+* Overview::
+* Viewing::
+* Conversion options::
+* Converting::
+* The configuration screen::
Command-line usage
-* Option summary::
+* 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::
+* Bitmapped and vector::
+* Font embedding::
+* Eps preview headers::
+* Bounding- and other boxes::
+* Orientation::
+* Exporting PostScript or pdf from Windows programs::
Bitmapped graphics for @LaTeX{} and pdflatex
-* Linux::
-* Mac OS X::
-* Windows::
-
-Windows
-
-* GUI use of sam2p and bmeps::
+* Linux::
+* Mac OS X::
+* Windows::
Troubleshooting
-* Grayscaling fails::
-* Part of the graphic gets cut off::
-* Fonts look ugly::
-* Resources for troubleshooting::
+* Part of the graphic gets cut off::
+* Fonts look ugly::
+* The page has been converted to a bitmap::
+* Resources for troubleshooting::
Change history
-* Version 0.5::
-* Version 0.4::
+* Version 0.6::
+* Version 0.5::
+* Version 0.4::
@end detailmenu
@end menu
-@node Usage, Command-line usage, Top, Top
+@node What has changed?, Usage, Top, Top
+@unnumbered What has changed?
+
+Improvements:
+@itemize @bullet
+@item
+Grayscaling should now also work on bitmapped images.
+@item
+Revised multistep conversions, with less risk of losing high-level
+structure
+@item
+Rewritten in TeXLua, which is a component of both TeX Live and of
+MikTeX. Command-line use no longer requires an external scripting
+language.
+@end itemize
+
+I have been testing with Ghostscript version 9.05 and 9.06.
+
+For more details, see @ref{Version 0.6}.
+
+@node Usage, Command-line usage, What has changed?, Top
@chapter Usage
@menu
-* Overview::
-* Viewing::
-* Conversion options::
-* Converting::
-* The configuration screen::
+* Overview::
+* Viewing::
+* Conversion options::
+* Converting::
+* The configuration screen::
@end menu
@node Overview, Viewing, Usage, Usage
@@ -142,16 +166,16 @@ 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}
+@noindent @image{images/main_w8,,3in}
@iftex
@hfill
@end iftex
-@image{images/cnv_osx,,3in}
+@image{images/cnv_linux,,3in}
@node Viewing, Conversion options, Overview, Usage
@section Viewing
-The View button at the bottom of the screen calls an appropriate
+The View button at the bottom of the screen calls an
external viewer.
@i{Windows and OS X:} Epspdftk simply tries to use the default Open
@@ -166,18 +190,15 @@ previewer for the current file.
@node Conversion options, Converting, Viewing, Usage
@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 even on non-bitmapped data, select the ``Try harder to
-grayscale'' option. This may cause an extra pdf-PostScript roundtrip,
-but grayscaling may still fail.
+@anchor{gray}@i{Grayscaling:} Grayscaling is now done by Ghostscript
+itself and should ``just work''.
@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.
+@i{Page selection:} The only possibilities are selecting a single page
+or selecting all pages. Converting to eps implies selecting a single
+page.
For general PostScript files, there is no quick way to determine the
number of pages, so the program may not check beforehand whether you
@@ -185,7 +206,7 @@ picked an existing page. 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.
+a multistep conversion.
@node Converting, The configuration screen, Conversion options, Usage
@section Converting
@@ -215,60 +236,48 @@ configured outside epspdf.
@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.
+pdf''. ``prepress'' is for pdfs which are going to be printed
+commercially. The options prepress, printer and default will try to
+embed all fonts. 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.
+Specifying anything other than ``default'' may cause an additional
+conversion step and possibly also loss of high-level structure.
+
+As to pdf versions: this is a trade-off between more features for higher
+versions and better compatibility for lower versions -- although even
+version 1.4 is far from bleeding-edge. Converting to a
+lower version may lead to rasterization of vector data and (much) larger
+file sizes. For prepress use, the printshop or publisher may require a
+low version number but otherwise leave this at ``default''.
+
@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 if the file uses fonts.
-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 your
-conversions come out slightly clipped. 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
+Under Windows and MikTeX, this is also the place to point the program to
+the location of pdftops.exe.
@node Command-line usage, Notes on PostScript and pdf, Usage, Top
@chapter Command-line usage
-epspdf.rb is the backend of epspdftk, but it can also be used
+epspdf.tlu is the backend of epspdftk, but it can also be used
standalone. It shares configuration settings with epspdftk.tcl.
-Under Windows, is strongly recommended to invoke epspdf.rb via a wrapper script
-epspdf.bat on the search path, e.g.
-@example
-"@var{path_to_ruby.exe}" "@var{path_to_epspdf.rb}" %*
-@end example
-
-The TeX Live package for epspdf already includes wrappers for Windows,
-both for epspdf and for epspdftk.
+Below, we assume that there is a suitable wrapper or symlink for epspdf
+on your searchpath. This is the case if you installed epspdf as a TeX
+Live package.
The first parameter of epspdftk is interpreted as startup directory for
the file browser.
-From version 0.5.2 on, there is no longer need for a wrapper script under
-Unix/Linux/Mac OS X; a symlink on the searchpath to the actual script
-suffices.
-
Basic usage:
@example
@@ -276,7 +285,7 @@ epspdf [@var{options}] @var{infile} @var{outfile}
@end example
@menu
-* Option summary::
+* Option summary::
@end menu
@node Option summary, , Command-line usage, Command-line usage
@@ -285,53 +294,43 @@ epspdf [@var{options}] @var{infile} @var{outfile}
Typing @kbd{epspdf --help} gives you the following summary:
@example
$ epspdf --help
-Epspdf version 0.5.3
-Copyright (C) 2006, 2008, 2009, 2010, 2011 Siep Kroonenberg
-Convert between [e]ps and pdf formats
-Usage: epspdf.rb [options] infile [outfile]
+Epspdf version 0.6.0
+Copyright (c) 2006, 2008, 2009, 2010, 2011, 2013 Siep Kroonenberg
+Convert between [e]ps and pdf formats
+Usage: epspdf[.tlu] [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
- -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
- --gui[=ACTION] Do not use; reserved for GUI
-
- -v, --version Prints version info
- -h, --help Show this message
+-p, --page, --pagenumber PNUM
+ Page number; must be a positive integer
+-g, --grey, --gray, -G, --GREY, --GRAY
+ Convert to grayscale
+-b, --bbox, --BoundingBox
+ Compute tight boundingbox
+-T, --target TARGET
+ One of screen, ebook, printer, prepress or default
+-N, --pdfversion VERSION
+ One of 1.2, 1.3, 1.4 or default
+-U Use pdftops if available
+-I Reverses the above
+-s, --save Save some settings to configuration file
+-d Debug: do not remove temp files
+-v, --version
+ Display version info and exit
+-h, --help Display this help message and exit
@end example
@node Notes on PostScript and pdf, Bitmapped graphics for @LaTeX{} and pdflatex, Command-line usage, Top
@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::
+* Bitmapped and vector::
+* Font embedding::
+* Eps preview headers::
+* Bounding- and other boxes::
+* Orientation::
+* Exporting PostScript or pdf from Windows programs::
@end menu
@node Bitmapped and vector, Font embedding, Notes on PostScript and pdf, Notes on PostScript and pdf
@@ -365,17 +364,10 @@ resolution.
@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.
+depending on the ``Target use'' option. According to the Ghostscript
+documentation, it embeds all fonts without exception for prepress- and
+printer settings. Epspdf enforces this also for default settings. For
+screen- and ebook settings, standard fonts such as Times may be omitted.
@node Eps preview headers, Bounding- and other boxes, Font embedding, Notes on PostScript and pdf
@section Eps preview headers
@@ -394,43 +386,36 @@ 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.
+Conversion from eps to pdf usually translates the bottom-left corner to
+the (0,0) origin and sets 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''.
+I have seen Illustrator-generated pdf files with negative coordinates
+for the lower-left corner. However, this does not seem to cause
+problems.
-@node Orientation, Exporting PostScript from Windows programs, Bounding- and other boxes, Notes on PostScript and pdf
+@node Orientation, Exporting PostScript or pdf from Windows programs, Bounding- and other boxes, Notes on PostScript and pdf
@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, , Orientation, Notes on PostScript and pdf
-@section Exporting PostScript from Windows programs
+boundingbox.
-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.
+@node Exporting PostScript or pdf from Windows programs, , Orientation, Notes on PostScript and pdf
+@section Exporting PostScript or pdf from Windows programs
-@image{images/ps_settings,2.5in}
+Microsoft Office 2010 can now export to pdf, either the entire document
+or a selection. This removes a major headache for Windows users.
-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://mirror.ctan.org/}.
+As a last resort, you can ``print'' 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. In my
+tests, ``Encapsulated PostScript'' did not look very promising
+either. Try e.g. ``Archive'' instead. These options can be found under
+the Advanced button.
@node Bitmapped graphics for @LaTeX{} and pdflatex, Troubleshooting, Notes on PostScript and pdf, Top
@chapter Bitmapped graphics for @LaTeX{} and pdflatex
@@ -440,9 +425,9 @@ format (best for photographs) directly. However, for @LaTeX{} you are
stuck with .eps format. Tips for converting to .eps:
@menu
-* Linux::
-* Mac OS X::
-* Windows::
+* Linux::
+* Mac OS X::
+* Windows::
@end menu
@node Linux, Mac OS X, Bitmapped graphics for @LaTeX{} and pdflatex, Bitmapped graphics for @LaTeX{} and pdflatex
@@ -460,14 +445,15 @@ utility: @samp{convert image.png image.eps}
@item The GIMP
This is the premier open source image editing program. It is often
pre-installed on Linux, and is also available for other platforms. The
-GIMP can save in eps format.
+GIMP can save in eps- and pdf format.
@end table
@node Mac OS X, Windows, Linux, Bitmapped graphics for @LaTeX{} and pdflatex
@section Mac OS X
Mac OS X's built-in Preview application can read most bitmapped formats
-and save them as .pdf, which epspdf can convert to .eps.
+and save them as pdf or PostScript. In fact, in many cases it is an
+excellent alternative to epspdf.
@node Windows, , Mac OS X, Bitmapped graphics for @LaTeX{} and pdflatex
@section Windows
@@ -485,69 +471,45 @@ sam2p is distributed with TeX Live (Windows only), bmeps both with TeX
Live and with MikTeX. Without the @code{-c} option, bmeps produces a
grayscale image. It produces larger files than sam2p.
-@menu
-* GUI use of sam2p and bmeps::
-@end menu
-
-@node GUI use of sam2p and bmeps, , Windows, Windows
-@subsection GUI use of sam2p and bmeps
-
-Create a batchfile @file{bitmap2eps.bat} with contents
-@verbatim
-sam2p "%~1" "%~dpn1.eps"
-@end verbatim
-(TeX Live) or
-@verbatim
-bmeps -c "%~1" "%~dpn1.eps"
-@end verbatim
-(MikTeX) and place it @emph{e.g.} on your desktop. Now if you drop a
-bitmapped graphic on this batchfile then you will get an eps file with
-the same name as the original, but with extension @code{.eps}.
+With TeX Live, you can convert to eps by right-clicking an image in
+Windows Explorer and ``open'' with @emph{bitmap2eps}, which uses sam2p
+or bmeps in the background.
@node Troubleshooting, Change history, Bitmapped graphics for @LaTeX{} and pdflatex, Top
@chapter Troubleshooting
@menu
-* Grayscaling fails::
-* Part of the graphic gets cut off::
-* Fonts look ugly::
-* Resources for troubleshooting::
+* Part of the graphic gets cut off::
+* Fonts look ugly::
+* The page has been converted to a bitmap::
+* Resources for troubleshooting::
@end menu
-@node Grayscaling fails, Part of the graphic gets cut off, Troubleshooting, Troubleshooting
-@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, Fonts look ugly, Grayscaling fails, Troubleshooting
+@node Part of the graphic gets cut off, Fonts look ugly, Troubleshooting, Troubleshooting
@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, Resources for troubleshooting, Part of the graphic gets cut off, Troubleshooting
+@node Fonts look ugly, The page has been converted to a bitmap, Part of the graphic gets cut off, Troubleshooting
@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.
+If Ghostscript has to do the conversion from pdf to ps then text may not
+remain text, but may be replaced by bitmaps. Try to get hold of a more
+recent Ghostscript and of either the xpdf suite or the Poppler
+utilities, both of which include pdftops.
+
+@node The page has been converted to a bitmap, Resources for troubleshooting, Fonts look ugly, Troubleshooting
+@section The page has been converted to a bitmap
+
+This may happen if the page contains features such as transparency which
+are not supported by intermediate formats.
+
+Set pdf target use and target version both to ``default'' to avoid
+unnecessary conversions: @code{-T default -N default}
-@node Resources for troubleshooting, , Fonts look ugly, Troubleshooting
+@node Resources for troubleshooting, , The page has been converted to a bitmap, Troubleshooting
@section Resources for troubleshooting
@i{Logfile.} The GUI has a button for viewing log output. This same
@@ -560,9 +522,7 @@ name}\AppData\Roaming}. Otherwise, open a command prompt and type
@kbd{echo %APPDATA%}, which will produce this information.
The logfile lists all epspdf calls and all Ghostscript- and pdftops
-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.
+calls plus error information.
@i{Temporary files.} The temporary files may give clues as
well. Uncheck the button ``Remove temp files'', or for the
@@ -579,11 +539,33 @@ for Windows there is a file pdftops.txt in the distribution zip.
@chapter Change history
@menu
-* Version 0.5::
-* Version 0.4::
+* Version 0.6::
+* Version 0.5::
+* Version 0.4::
@end menu
-@node Version 0.5, Version 0.4, Change history, Change history
+@node Version 0.6, Version 0.5, Change history, Change history
+@section Version 0.6
+
+The command-line backend component has been rewritten in texlua and
+therefore no longer needs an external scripting language.
+
+Grayscaling is now done by Ghostscript's color options for pdf
+output. This also works for bitmaps.
+
+Croppping of pdfs is now accomplished by running luatex on a suitable
+wrapper file (same method as Heiko Oberdiek's pdfcrop). Such a
+conversion preserves advanced features which might otherwise get lost
+during a PostScript round-trip.
+
+I no longer own a Mac, and therefore no longer try to provide an
+AppleScript wrapper.
+
+The current version has no provisions for custom Ghostscript- or pdftops
+parameters. I may of may not re-add those in a future update. The
+corresponding command-line options are accepted but have no effect.
+
+@node Version 0.5, Version 0.4, Version 0.6, Change history
@section Version 0.5
The GUI has been rewritten in Tcl/Tk, removing the dependence on the