diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /support/epspdf/doc/epspdf.texi |
Initial commit
Diffstat (limited to 'support/epspdf/doc/epspdf.texi')
-rw-r--r-- | support/epspdf/doc/epspdf.texi | 680 |
1 files changed, 680 insertions, 0 deletions
diff --git a/support/epspdf/doc/epspdf.texi b/support/epspdf/doc/epspdf.texi new file mode 100644 index 0000000000..1c87952cae --- /dev/null +++ b/support/epspdf/doc/epspdf.texi @@ -0,0 +1,680 @@ +\input texinfo @c -*-texinfo -*- +@c %**start of header +@setfilename epspdf.info +@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 + +@c Actually, we do not produce html anymore +@ifhtml +@alias chapter = unnumbered +@alias section = unnumberedsec +@alias subsection = unnumberedsubsec +@end ifhtml + +@tex +\input pstexi +@end tex + +@iftex +@textfonts +@rm +@raggedbottom +@hyphenation{epspdf-tk epspdf} +@end iftex + +@set version 0.6.4 + +@setchapternewpage off +@paragraphindent none + +@copying +This manual is for epspdf and epspdftk, version @value{version}. + +Copyright @copyright{} 2006-2019 Siep Kroonenberg. + +@quotation +Copying and distribution of this file, with or without modification, +are permitted in any medium without royalty provided the copyright +notice and this notice are preserved. This file is offered as-is, +without any warranty. +@end quotation +@end copying + +@titlepage +@sp 1 +@ifnotinfo +@center @image{images/logo,,.4in} +@end ifnotinfo +@sp 2 +@center @titlefont {Epspdf and epspdftk User Manual} +@sp 1 +@center A cross-platform GUI- and command-line converter for [e]ps and pdf +@sp 2 +@center Siep Kroonenberg (@email{siepo at bitmuis dot nl}) +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@contents + +@ifnottex +@node Top, Usage, (dir), (dir) +@top Epspdf and epspdftk + +@insertcopying +@end ifnottex + +@menu +* Usage:: +* Command-line usage:: +* Notes on PostScript and pdf:: +* Bitmapped graphics for @LaTeX{} and pdflatex:: +* Troubleshooting:: +* Requirements:: +* Change history:: + +@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 or pdf from Windows programs:: + +Bitmapped graphics for @LaTeX{} and pdflatex + +* Linux:: +* Mac OS:: +* Windows:: + +Troubleshooting + +* No options for output format visible:: +* Ghostscript stackunderflow error:: +* Part of the graphic gets cut off:: +* Fonts look ugly:: +* The page has been converted to a bitmap:: +* Temporary files are not removed:: +* Resources for troubleshooting:: + +Change history + +* Version 6.4:: +* Version 0.6:: +* Version 0.5:: +* Version 0.4:: + +@end detailmenu +@end menu + +@node Usage, Command-line usage, Top, Top +@chapter Usage + +@menu +* Overview:: +* Viewing:: +* Conversion options:: +* Converting:: +* The configuration screen:: +@end menu + +@node Overview, Viewing, Usage, Usage +@section Overview + +Epspdftk is a GUI program that converts files between eps, pdf and +general PostScript in any direction. + +It lets you interactively select a file, set conversion options, and +save in the same of another format. A configuration screen offers +some additional conversion options. + +@ifnotinfo +@noindent @image{images/main_wx,,2.9in} +@iftex +@hfill +@end iftex +@image{images/cnv_linux,,2.9in} +@end ifnotinfo + +@node Viewing, Conversion options, Overview, Usage +@section Viewing + +The View button at the bottom of the screen invokes an +external viewer. + +@i{Windows and Mac OS:} Epspdftk simply tries to use the default Open +command. + +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, Converting, Viewing, Usage +@section Conversion options + +@itemize +@item +@anchor{gray}Grayscaling + +@item +Compute tight boundingbox. This option is only available +if a single page is converted. + +@item +Page selection. The only possibilities are selecting a single page +or selecting all pages. Converting to eps implies selecting a single +page. +@end itemize + +@i{Note.} For general PostScript files, there is no quick way to +determine the number of pages, so the program may not check beforehand +whether you picked an existing page. If you don't like that, convert the +entire document to pdf first -- which will be done behind the scenes +anyway. + +Specifying options such as grayscaling or page selection may require +a multistep conversion. + +@node Converting, The configuration screen, Conversion options, Usage +@section Converting + +The Convert and save@dots{} 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 -- if epspdftk +thinks that there is a suitable viewer. + +@node The configuration screen, , Converting, Usage +@section The configuration screen + +@ifnotinfo +@image{images/config_lnx,3in} +@end ifnotinfo + +Epspdftk also has a configuration screen. The settings here are +preserved between sessions. + +@subsection Configuring viewers + +Under Unix, 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 there is no such configuration option. Epspdf +will use the program associated with the file type, which can be +configured outside epspdf. + +@subsection Options for converting to pdf +Double-check the setting ``Target use'' under ``Conversion to +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. + +On the other hand, you may prefer ``screen'' if file size is a +concern. See also the Ghostscript documentation, in particular Use.htm +and VectorDevices.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. Versions below 1.4 +do not support transparency. Converting a page or graphic with +transparencies to version 1.3 will probably result in the whole page or +graphic getting rasterized. For prepress use, consult your printshop or +publisher. Otherwise leave the pdf version at ``default''. + +@subsection Options for converting to PostScript +For conversion to plain or Encapsulated PostScript, pdftops sometimes +does a better job of preserving fonts than Ghostscript. Under Windows, +current versions of both MiKTeX and TeX Live include pdftops. Still, you +may opt @i{not} to use pdftops even if it is available, in which case +Ghostscript will be used instead. + +@node Command-line usage, Notes on PostScript and pdf, Usage, Top +@chapter Command-line usage + +epspdf.tlu is the backend of epspdftk, but it can also be used +standalone. It shares configuration settings with epspdftk.tcl. + +The first parameter of the epspdftk GUI program is interpreted as +startup directory for the file browser. Epspdf itself has a more +elaborate command-line interface. + +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. + +Basic usage of epspdf itself: + +@example +epspdf [@var{options}] @var{infile} [@var{outfile}] +@end example + +@menu +* Option summary:: +@end menu + +@node Option summary, , Command-line usage, Command-line usage +@section Option summary + +Typing @kbd{epspdf --help} gives you the following summary: +@example +$ epspdf --help +Epspdf version 0.6.4 +Copyright (c) 2006-2019 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 + +-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, 1.5, 1.6, 1.7 or default +-U Use pdftops if available +-I Reverses the above +-s, --save Save some settings to configuration file +-i, --info Info: display detected filetype and exit +-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 or pdf from Windows programs:: +@end menu + +@node Bitmapped and vector, Font embedding, Notes on PostScript and pdf, Notes on PostScript and pdf +@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. + +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 usually 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, Eps preview headers, Bitmapped and vector, Notes on PostScript and pdf +@section Font embedding + +When converting to pdf, Ghostscript handles font embedding differently +depending on the ``Target use'' option. According to the Ghostscript +documentation, it embeds all fonts without exception for all targets +except ``screen'', for which 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 + +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 has no option to preserve or add them. + +@node Bounding- and other boxes, Orientation, Eps preview headers, Notes on PostScript and pdf +@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. + +Conversion to pdf usually translates the bottom-left corner to the (0,0) +origin and sets the @dots{}box to the size of the +graphic. Anything outside the @dots{}box should be cut off. + +@node Orientation, Exporting PostScript or pdf from Windows programs, Bounding- and other boxes, Notes on PostScript and pdf +@section Orientation + +Ghostscript may not be able to determine the right orientation of a +PostScript- or pdf file. This may result in part of a graphic being cut +off after conversion or even everything falling outside the page / +mediabox / boundingbox. + +@node Exporting PostScript or pdf from Windows programs, , Orientation, Notes on PostScript and pdf +@section Exporting PostScript or pdf from Windows programs + +Microsoft Office 2010 can now export to pdf, either the entire document +or a selection. This removes a major headache for Windows users. Windows +10 also includes a pdf printer. + +As a last resort on earlier Windows versions, 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 Color +Printer. 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 + +pdflatex can use graphics in .png format (best for screenshots) and .jpg +format (best for photographs) directly. However, for @LaTeX{} you are +stuck with .eps format. Tips for converting to .eps: + +@menu +* Linux:: +* Mac OS:: +* Windows:: +@end menu + +@node Linux, Mac OS, Bitmapped graphics for @LaTeX{} and pdflatex, Bitmapped graphics for @LaTeX{} and pdflatex +@section Linux + +@table @emph +@item sam2p +This command-line bitmap-to-PostScript/pdf conversion utility is +available from @url{http://code.google.com/p/sam2p/} and may already be +packaged for your distribution. It produces very small files: +@samp{sam2p image.png image.eps} +@item ImageMagick/convert +@command{convert} from the ImageMagick package is a command-line +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- and pdf format. +@end table + +@node Mac OS, Windows, Linux, Bitmapped graphics for @LaTeX{} and pdflatex +@section Mac OS + +Mac OS's built-in Preview application can read most bitmapped formats +and save them as pdf or PostScript. In fact, in many cases it is an +excellent alternative to epspdf. + +@node Windows, , Mac OS, Bitmapped graphics for @LaTeX{} and pdflatex +@section Windows + +I know of no built-in facility for converting bitmaps to eps or pdf, +apart from ``printing'' to PostScript or pdf. However, many image +editors can convert to eps or pdf. A couple of command-line utilities: +@example +sam2p image.png image.eps +@end example +or +@example +bmeps -c image.png image.eps +@end example +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. + +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 +* No options for output format visible:: +* Ghostscript stackunderflow error:: +* Part of the graphic gets cut off:: +* Fonts look ugly:: +* The page has been converted to a bitmap:: +* Temporary files are not removed:: +* Resources for troubleshooting:: +@end menu + +@node No options for output format visible, Ghostscript stackunderflow error, Troubleshooting, Troubleshooting +@section No options for output format visible + +Widen the window, to make the output format radio buttons visible. + +@node Ghostscript stackunderflow error, Part of the graphic gets cut off, No options for output format visible, Troubleshooting +@section Ghostscript stackunderflow error + +Some Ghostscript versions, @emph{e.g.} 9.10, have an error in color +handling when converting to pdf: selecting ``printer'' as target may +lead to an error @code{stackunderflow in .setdistillerparams}. If you +run into this, use the ``default'' or ``prepress'' target instead. + +@node Part of the graphic gets cut off, Fonts look ugly, Ghostscript stackunderflow error, Troubleshooting +@section Part of the graphic gets cut off + +If the PostScript file was generated with the Windows PostScript driver, +experiment with the PostScript Output option. Don't choose Optimize for +Speed. + +@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 may not +remain text, but may be replaced by bitmaps. Newer Ghostscript versions +tend to do better in this respect than older ones, but as to preserving +fonts, the pdftops utility may still handle more cases. It is part of the +xpdf suite and of the Poppler utilities. + +@node The page has been converted to a bitmap, Temporary files are not removed, Fonts look ugly, Troubleshooting +@section The page has been converted to a bitmap + +The usual cause is that the page contains features such as transparency which +are not supported by the target format. + +Otherwise, set pdf target use and target version both to ``default'' to +avoid unnecessary conversions: @code{-T default -N default} + +@node Temporary files are not removed, Resources for troubleshooting, The page has been converted to a bitmap, Troubleshooting +@section Temporary files are not removed + +@itemize +@item +Command-line: make sure that you did not specify the option @code{-d}. +@item +Epspdftk GUI: make sure that `Remove temp files' is checked. +@item +Windows: this platform is notorious for excessive file locking. I +already inserted a Windows-specific delay before attempting to delete +the temporary files, but this is not always enough. However, you should +have no trouble removing temporary files manually. +@end itemize + +@node Resources for troubleshooting, , Temporary files are not removed, Troubleshooting +@section Resources for troubleshooting + +@i{Logfile.} The GUI has a button for viewing log output. This same +output is also written to a file @file{epspdf.log}. For Linux/Unix/Mac +Mac OS this is in a subdirectory .epspdf of your home directory; for +Windows it is in a subdirectory epspdf of @file{%APPDATA%}. This APPDATA +directory may be @file{c:\Users\@var{your user +name}\AppData\Roaming}. Type +@example +echo %APPDATA% +@end example +in a Command Prompt window to find out which. + +The logfile lists all epspdf calls and all Ghostscript- and pdftops +calls plus error information. + +@i{Temporary files.} The temporary files may give clues as +well. Uncheck the button ``Remove temp files'', or for the +command-line version, give a -d parameter to keep the temporary +files. Check the log(file) as to which temporary files have been +created. + +@anchor{Documentation}@i{Ghostscript- and pdftops documentation.} For +Ghostscript, the most important files are VectorDevices.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. TeX +Live includes the man page in pdf format: pdftops.pdf. + +@node Requirements +@appendix Requirements + +Epspdftk consists of a GUI front end and a command-line back end. + +The command-line component, which can be used separately from the front +end, requires ghostscript and a not too old @TeX{} installation with +luatex. It may further benefit from the presence of pdftops. MiKTeX and +TeX Live for Windows meet these requirements out of the box. + +The front end requires a Tcl/Tk installation, or at least a tclkit +runtime. TeX Live for Windows contains such a tclkit since late 2018, +and epspdftk as a TeX Live package will make use of it. The minimum +version is 8.5. + +For Windows there is an alternate epspdf-setup package on CTAN with an +embedded Tcl/Tk runtime and a regular Windows installer, which also +creates a menu shortcut and an uninstaller. + +@node Change history, , Troubleshooting, Top +@appendix Change history + +@menu +* Version 6.4:: +* Version 0.6:: +* Version 0.5:: +* Version 0.4:: +@end menu + +@node Version 6.4 +@section Version 6.4 + +Compatibility changes for luatex 1.9 and later. + +The location of pdftops is no longer configurable; it is only searched +for on the searchpath. + +Some corner cases should be handled more successfully. + +The GUI now requires Tcl/Tk version 8.5 or higher. On Windows, +epspdf.tlu is now invoked via a batchfile. This should prevent black +console windows popping up. + +@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. + +I no longer try to provide an AppleScript wrapper. + +The current version has no provisions for custom Ghostscript- or pdftops +parameters. 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 +Ruby/Tk interface library. + +The Windows installer now installs a small Ruby subset and the standard +epspdf distribution, but with epspdftk.tcl replaced with a starpack: a +single executable containing @file{epspdftk.tcl} and a Tcl/Tk +runtime. See @url{http://wiki.tcl.tk/52}. + +Epspdf now uses its own subdirectory for both the logfile and the +configuration file. For Linux/Unix/Mac OS this is +@file{$HOME/.epspdf}, for Windows it is @file{%APPDATA%\epspdf}. +On all supported platforms, settings are stored in the file +@file{config} in this directory. Under Windows, the registry is no +longer used for this. + +A button has been added to view log output. + +There is a second new button ``Remove temp files'', which is normally +checked, causing temporary files to be deleted after each +conversion. Unchecking this button may be useful for troubleshooting. In +previous versions, temporary files were deleted at the end of the entire +epspdftk session but that has become less practical now that the GUI and +epspdf itself have become two separate programs. + +The ``Open with@dots{}'' option for Windows has been dropped for technical +reasons. + +The ``--version'' option now prints the version string instead of +setting the desired pdf version. + +The ``--info'' option now also prints the number of pages for pdf +files. + +@node Version 0.4, , Version 0.5, Change history +@section 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 +dimensions 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 a 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 |