3400 lines · 141.1 KB · HTML
RawDownload
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd"><html><head><title>How to use Ghostscript</title><!-- $Id: Use.htm,v 1.136 2005/10/20 19:46:23 ray Exp $ --><!-- Originally: use.txt --><link rel="stylesheet" type="text/css" href="gs.css" title="Ghostscript Style"></head> <body><!-- [1.0 begin visible header] ============================================ --> <!-- [1.1 begin headline] ================================================== --> <h1>How to use Ghostscript</h1> <!-- [1.1 end headline] ==================================================== --> <!-- [1.2 begin table of contents] ========================================= --> <h2>Table of contents</h2> <blockquote><ul><li><a href="#Invoking">Invoking Ghostscript</a><ul><li><a href="#Help_command">Help at the command line: <b><tt>gs -h</tt></b></a></ul><li><a href="#Output_device">Selecting an output device</a><ul><li><a href="#Output_resolution">Output resolution</a><li><a href="#File_output">Output to files</a><ul><li><a href="#One_page_per_file">One page per file</a></ul><li><a href="#Paper_size">Choosing paper size</a><li><a href="#Change_default_size">Changing the installed default paper size</a></ul><li><a href="#Pipes">Interacting with pipes</a><li><a href="#PDF">Using Ghostscript with PDF files</a><ul><li><a href="#PDF_switches">Switches for PDF files</a><li><a href="#PDF_problems">Problems interpreting a PDF file</a><li><a href="#PDF_stdin">PDF files from standard input</a></ul> <li><a href="#EPS">Using Ghostscript with EPS files</a><li><a href="#SPOT">Using Ghostscript with overprinting and spot colors</a><li><a href="#Finding_files">How Ghostscript finds files</a><ul><li><a href="#PS_resources">Finding PostScript Level 2 resources</a><li><a href="#Font_lookup">Font lookup</a><li><a href="#CIDFonts">CID fonts</a><li><a href="#CIDFontSubstitution">CID font substitution</a><li><a href="#Temp_files">Temporary files</a></ul> <li><a href="#Platforms">Notes on specific platforms</a><ul><li><a href="#Unix">Unix</a><li><a href="#VMS">VMS</a><ul><li><a href="#VMS_X_Windows">Using X Windows on VMS</a></ul><li><a href="#MS_Windows">MS Windows</a><li><a href="#X_Windows">X Windows</a><ul><li><a href="#X_resources">X resources</a><li><a href="#X_server_bugs">Working around bugs in X servers</a><li><a href="#X_fonts">X fonts</a><li><a href="#GS_fonts_as_X_fonts">Using Ghostscript fonts on X displays</a><li><a href="#X_device_parameters">X device parameters</a></ul><li><a href="#SCO_Unix">SCO Unix</a></ul> <li><a href="#Options">Command line options</a><ul><li><a href="#General_switches">General switches</a><ul><li><a href="#Input_control">Input control</a><li><a href="#File_searching">File searching</a><li><a href="#Parameters">Setting parameters</a><li><a href="#Quiet">Suppress messages</a></ul><li><a href="#Parameter_switches">Parameter switches (<b><tt>-d</tt></b> and <b><tt>-s</tt></b>)</a><ul><li><a href="#Rendering_parameters">Rendering parameters</a><li><a href="#Page_parameters">Page parameters</a><li><a href="#Font_related_parameters">Font-related parameters</a><li><a href="#Resource_related_parameters">Resource-related parameters</a><li><a href="#Interaction_related_parameters">Interaction-related parameters</a><li><a href="#Output_selection_parameters">Device and output selection parameters</a><li><a href="#EPS_parameters">EPS parameters</a><li><a href="#Other_parameters">Other parameters</a></ul></ul><li><a href="#Improving_performance">Improving performance</a><li><a href="#Environment_variables">Summary of environment variables</a> <li><a href="#Debugging">Debugging</a><ul><li><a href="#Debug_switches">Debug Switches</a><li><a href="#Visual_trace">Visual Trace</a></ul><li><a href="#Known_paper_sizes">Appendix: Paper sizes known to Ghostscript</a><li><a href="#X_font_mappings">Appendix: X default font mappings</a><ul><li><a href="#Standard_X_server_fonts">Standard X servers</a><ul><li><a href="#X_regular_fonts">Regular fonts</a><li><a href="#X_symbol_fonts">Symbol fonts</a><li><a href="#X_dingbat_fonts">Dingbat fonts</a></ul><li><a href="#OpenWindows_fonts">Sun OpenWindows</a></ul><li><a href="#FAPI_run">Appendix: Running Ghostscript with 3d party font renderers</a></ul></blockquote> <!-- [1.2 end table of contents] =========================================== --> <!-- [1.3 begin hint] ====================================================== --> <p>For other information, see the <a href="Readme.htm">Ghostscriptoverview</a> and, if necessary, how to<a href="Install.htm">install Ghostscript</a>. <!-- [1.3 end hint] ======================================================== --> <hr> <!-- [1.0 end visible header] ============================================== --> <!-- [2.0 begin contents] ================================================== --> <h2><a name="Invoking"></a>Invoking Ghostscript</h2> <p>This document describes how to use the command line Ghostscript client.Ghostscript is also used as a general engine inside other applications (for viewing files for example).Please refer to the documentation for those applications for using Ghostscript in other contexts. <p><a name="Command_line"></a> The command line to invoke Ghostscript isessentially the same on all systems, although the name of the executableprogram itself may differ among systems.  For instance, to invokeGhostscript on unix-like systems type: <blockquote>        <pre><b><tt>gs</tt></b> [options] {filename 1} ... [options] {filename <em>N</em>} ...</pre></blockquote> <p>Here are some basic examples. The details of how these work are described below. <p>To view a file:<blockquote><pre>gs -dSAFER -dBATCH document.pdf</pre></blockquote>You'll be prompted to press <em>return</em> between pages. <p>To convert a figure to an image file:<blockquote><pre>gs -dSAFER -dBATCH -dNOPAUSE -sDEVICE=png16m -dGraphicsAlphaBits=4 \    -sOutputFile=tiger.png tiger.eps</pre></blockquote> <p>To render the same image at 300 dpi:<blockquote><pre>gs -dSAFER -dBATCH -dNOPAUSE -sDEVICE=png16m -r300 \                -sOutputFile=tiger_300.png tiger.eps</pre></blockquote> <p>To render a figure in grayscale:<blockquote><pre>gs -dSAFER -dBATCH -dNOPAUSE -sDEVICE=pnggray -sOutputFile=figure.png figure.pdf</pre></blockquote> <p>To rasterize a whole document:<blockquote><pre>gs -dSAFER -dBATCH -dNOPAUSE -sDEVICE=pgmraw -r150 \                -dTextAlphaBits=4 -sOutputFile='paper-%00d.pgm' paper.ps</pre></blockquote> <p>There are also a number of utility scripts for common to convert a PostScript document to PDF:<blockquote><pre>ps2pdf file.ps</pre></blockquote>The output is saved as file.pdf. <p>There are other utility scripts besides <tt>ps2pdf</tt>, including <tt>pdf2ps</tt>, <tt>ps2epsi</tt>, <tt>pdf2dsc</tt>, <tt>ps2ascii</tt>,<tt>ps2ps</tt> and <tt>ps2ps2</tt>. These just call Ghostscript with the appropriate(if complicated) set of options. You can use the 'ps2' set with eps files. <p>Ghostscript is capable of interpreting PostScript, encapsulated PostScript(EPS), DOS EPS (EPSF), and Adobe Portable Document Format (PDF).  The interpreter reads and executes the files in sequence, using the method described under "<a href="#File_searching">File searching</a>" to find them. <p>The interpreter runs in interactive mode by default. After processing the files given on the command line (if any) it reads further lines of PostScript language commands from the primary input stream, normally the keyboard, interpreting each line separately. To quit the interpreter, type "<b><tt>quit</tt></b>". The <tt>-dBATCH -dNOPAUSE</tt> options in the examples above disable the interactive prompting. The interpreter also quits gracefully if it encounters end-of-file or control-C. <p>The interpreter recognizes many options. An option may appear anywhere in the command line, and applies to all files named after it on the line. Many of them include "<b><tt>=</tt></b>"followed by a parameter. The most important are described in detail here. Please see the reference sections on <a href="#Options">options</a> and <a href="Devices.htm">devices</a> for a more complete listing. <h3><a name="Help_command"></a>Help at the command line: <b><tt>gs -h</tt></b></h3> <p>You can get a brief help message by invoking Ghostscript with the<b><tt>-h</tt></b> or <b><tt>-?</tt></b> switch, like this: <blockquote><pre>gs -hgs -?</pre></blockquote> <p>The message shows for that version of the Ghostscript executable: <ul><li>the version and release information<li>the general format of the command line<li>a few of the most useful options<li>the formats it can interpret<li>the available output devices<li>the search path<li>the bug report address</ul> <p>On other systems the executable may have a different name: <blockquote><table cellpadding=0 cellspacing=0><tr bgcolor="#CCCC00">        <th align=left>System        <th>&nbsp;&nbsp;        <th align=left>invocation name<tr>    <td>Unix        <td>&nbsp;<td><b><tt>gs</tt></b><tr>    <td>VMS        <td>&nbsp;<td><b><tt>gs</tt></b><tr>    <td>MS Windows 95 and later        <td>&nbsp;<td><b><tt>gswin32c</tt></b><tr>    <td>MS Windows 3.1/Win32s        <td>&nbsp;<td><b><tt>gswin32</tt></b><tr>    <td>OS/2        <td>&nbsp;<td><b><tt>gsos2</tt></b></table></blockquote>  <h2><a name="Output_device"></a>Selecting an output device</h2> <p>Ghostscript has a notion of 'output devices' which handle saving or displaying the results in a particular format. Ghostscript comes with a diverse variety of such devices supporting vector and raster file output, screen display, driving various printers and communicating with other applications. <p>The command line option '<tt>-sDEVICE=</tt><em>device</em>' selects which output device Ghostscript should use. If this option isn't given the default device (usually a display device) is used. Ghostscript's built-in help message (<tt>gs&nbsp;-h</tt>) liststhe available output devices. For complete description of the devices distributed with Ghostscript and their options, please see the <a href="Devices.htm">devices section</a> of the documentation. <p><a name="Device_output"></a>Note that this switch must precede the name of the first input file, andonly its first use has any effect.  For example, for printer output in aconfiguration that includes an Epson printer driver, instead of just<tt>'gs&nbsp;myfile.ps'</tt> you might use <blockquote>        <b><tt>gs -sDEVICE=epson myfile.ps</tt></b></blockquote> <p><a name="GS_DEVICE"></a>The output device can also be set through the <tt>GS_DEVICE</tt> environment variable. <p>Once you invoke Ghostscriptyou can also find out what devices are available by typing'<tt>devicenames&nbsp;==</tt>' at the interactive prompt.You can set the output device and process a file from the interactive prompt as well:  <blockquote><pre>(epson) selectdevice(myfile.ps) run</pre></blockquote> All output then goes to the Epson printer instead of the display until youdo something to change devices.  You can switch devices at any time byusing the <tt>selectdevice</tt> procedure, forinstance like one of these: <blockquote><pre>(x11alpha) selectdevice(epson) selectdevice</pre></blockquote> <h3><a name="Output_resolution"></a>Output resolution</h3> <p>Some printers can print at several different resolutions, letting youbalance resolution against printing speed.  To select the resolution onsuch a printer, use the <b><tt>-r</tt></b> switch: <blockquote>        <b><tt>gs -sDEVICE=</tt></b><em>printer</em><b><tt> -r</tt></b><em>XRES</em><b><tt>x</tt></b><em>YRES</em></blockquote> where <em>XRES</em> and <em>YRES</em> are the requested number of dots (or pixels) per inch. Where the two resolutions are same, as is the common case, you can simply use <tt>-r</tt><em>res</em>. <p>The <tt>-r</tt> option is also useful for controlling the density of pixels when rasterizing to an image file. It is used this way in the examples at the beginning of this document. <h3><a name="File_output"></a>Output to files</h3> <p>Ghostscript also allows you to control where it sends its output. With a display device this isn't necessary as the device handles presenting the output on screen internally. Some specialized printer drivers operate this way as well, but most devices are general and need to be directed to a particular file or printer. <p>To send the output to a file, use the <tt>-sOutputFile=</tt> switch.For instance, to direct all output into the file <tt>ABC.xyz</tt>, use <blockquote><b><tt>gs -sOutputFile=ABC.xyz</tt></b></blockquote> <p>When printing on MS Windows systems, output normally goes directly to the printer, <tt>PRN</tt>. On Unix and VMS systems it normally goes to a temporary file which is sent to the printer in a separate step. When using Ghostscript as a file rasterizer (converting PostScript or PDF to a raster image format) you will of course want to specify an appropriately named file for the output. <p>Ghostscript also accepts the special filename '<tt>-</tt>' which indicates the output should be written to standard output (the command shell). <p>Be aware that filenames beginning with the character <tt>%</tt> have a special meaning in PostScript. If you need to specify a file name that actuallybegins with <tt>%</tt>, you must prepend the <tt>%os%</tt> filedevice explicitly. For example to output to a file named <tt>%abc</tt>, you need to specify <blockquote><b><tt>gs -sOutputFile=%os%%abc</tt></b></blockquote> Please see <a href="Language.htm">Ghostscript and the PostScript Language</a> and the PostScript Language Reference Manual for more details on <tt>%</tt> and filedevices. <p>Note that on MS Windows systems, the <b><tt>%</tt></b> character also has a special meaning for the command processor (shell), so you will have to double it: <blockquote><b><tt>gs -sOutputFile=%%os%%%%abc</tt></b> (on MS Windows)</blockquote> <h4><a name="One_page_per_file"></a>One page per file</h4> <p>Specifying a single output file works fine for printing and rasterizingfigures, but sometimes you want images of each page of a multi-pagedocument. You can tell Ghostscript to put each page of output in aseries of similarly named files. To do this place a template'<tt>%d</tt>' in the filename which Ghostscript will replace with thepage number. <p>You can also control the number of digits used in the file name: <blockquote><dl><dt><b><tt>-sOutputFile=ABC-%d.png</tt></b><dd>produces '<tt>ABC-1.png</tt>', ... , '<tt>ABC-10.png</tt>', ...<p><dt><b><tt>-sOutputFile=ABC-%03d.pgm</tt></b><dd>produces '<tt>ABC-001.pgm</tt>', ... , '<tt>ABC-010.pgm</tt>', ...<p><dt><b><tt>-sOutputFile=ABC_p%04d.tiff</tt></b><dd>produces '<tt>ABC_p0001.tiff</tt>', ... , '<tt>ABC_p0510.tiff</tt>', ... , '<tt>ABC_p5238.tiff</tt>'<p></dl></blockquote> Generally <tt>%03d</tt> is the best option for normal documents. <p>Note however that this features is not supported by all devices; in particularit does not work with document-oriented output devices like <tt>pdfwrite</tt> and<tt>pswrite</tt>. See the <tt>-dFirstPage</tt> and <tt>-dLastPage</tt> switches<a href="#PDF_switches">below</a> for a way to extract single pdf pages. <p>As noted above, on MS Windows systems, you will have to double the<tt>%</tt> character, e.g., <blockquote><tt><b>gs -sOutputFile=ABC%%03d.xyz</b></tt></blockquote>  <h3><a name="Paper_size"></a>Choosing paper size</h3> <p>Ghostscript is distributed configured to use U.S. letter paper as itsdefault page size.  There are two ways to select other paper sizes from thecommand line: <ul> <li>If the desired paper size is listed in the section on <ahref="#Known_paper_sizes">paper sizes known to Ghostscript</a> below, youcan select it as the default paper size for a single invocation ofGhostscript by using the <b><tt>-sPAPERSIZE=</tt></b> switch, for instance <blockquote><b><tt>-sPAPERSIZE=a4<br>-sPAPERSIZE=legal</tt></b></blockquote> <li>Otherwise you can set the page size using thepair of switches <blockquote><b><tt>-dDEVICEWIDTHPOINTS=</tt></b><em>w</em><b><tt>-dDEVICEHEIGHTPOINTS=</tt></b><em>h</em></blockquote> Where <em>w</em> be the desired paper width and <em>h</em> be thedesired paper height in <em>points</em> (units of 1/72 of an inch).</ul> <p>Individual documents can (and often do) specify a paper size, which takesprecedence over the default size.  To force a specific paper size andignore the paper size specified in the document, select a paper size asjust described, and also include the<a href="#FIXEDMEDIA"><b><tt>-dFIXEDMEDIA</tt></b> switch</a> on thecommand line. <p>The default set of paper sizes will be included in the <b><tt>currentpagedevice</tt></b>in the <b><tt>InputAttributes</tt></b> dictionary with each paper size asone of the entries. The last entry in the dictionary (which has numeric keys)is a non-standard (Ghostscript extension) type of PageSize where the arrayhas four elements rather than the standard two elements. This four elementarray represents a page size range where the first two elements are the lowerbound of the range and the second two are the upper bound. By default theseare [0, 0] for the lower bound and [16#fffff, 16#fffff] for the upper bound.<br>The range type of PageSize is intended to allow flexible page size sepcificationfor non-printer file formats such as JPEG, PNG, TIFF, EPS, ...<br>For actual printers, either the entire <b><tt>InputAttributes</tt></b> dictionaryshould be replaced or the range type entry should not be included. To simplifyusing the default page sizes in the <b><tt>InputAttributes</tt></b> dictionary,the command line option <b><tt>-dNORANGEPAGESIZE</tt></b> can be used. Usingthis option will result in automatic rotation of the document page if the requestedpage size matches one of the default page sizes. <h3><a name="Change_default_size"></a>Changing the installed default paper size</h3> <p>You can change the installed default paper size on an installed version of Ghostscript, by editing the initialization file <b><tt>gs_init.ps</tt></b>.This file is usually in the <tt>lib</tt> directory somewhere in the search path. See the section on <a href="#Finding_files">finding files</a> for details. <p>Find the line <blockquote><pre>% /DEFAULTPAPERSIZE (a4) def</pre></blockquote> <p>Then to make A4 the default paper size, uncomment the line to changethis to <blockquote><pre>/DEFAULTPAPERSIZE (a4) def</pre></blockquote> <p>For <tt>a4</tt> you can substitute any<a href="#Known_paper_sizes">paper size Ghostscript knows</a>. <p>This supecedes the previous method of uncommenting the line<b><tt>% (a4) ...</tt></b>. <p>Sometimes the initialization files are compiled into Ghostscript and cannot be changed. <h2><a name="Pipes"></a>Interacting with pipes</h2> <p>As noted above, input files are normally specified on the commandline.  However, one can also "pipe" input into Ghostscript from anotherprogram by using the special file name '<b><tt>-</tt></b>' which is interpreted as standard input. Examples: <blockquote>{<em>some program producing ps</em>} <b><tt>| gs</tt></b> [options] <b><tt>-</tt></b><br><tt>zcat paper.ps.gz</tt> <b><tt>| gs</tt></b> <b><tt>-</tt></b></blockquote> <p><em>Ghostscript cannot read PDF files from standard input or a pipe because the PDF language inherently requires random access to the file. Thus '<tt>-</tt>' only works with PostScript documents.</em> <p>When Ghostscript finishes reading from the pipe, it quits rather thangoing into interactive mode.  Because of this, options and files after the '<tt>-</tt>' in the command line will be ignored. <p>On Unix and MS Windows systems you can send output to a pipe in the same way.  For example, to pipe the output to <tt>lpr</tt>, use the command <blockquote><tt>        <b>gs -q -sOutputFile=- |</b> lpr</tt></blockquote> <p>In this case you must also use the <a href="#Quiet"><b><tt>-q</tt></b>switch</a> to prevent Ghostscript from writing messages to standard outputwhich become mixed with the intended output stream. <p>

Lines 1–500 of 3400.