<html><head><title>How to use Ghostscript</title><!-- $Id: Use.htm,v 1.2 2000/03/10 08:02:59 lpd Exp $ --><!-- Originally: use.txt --></head> <body><!-- [1.0 begin visible header] ============================================ --> <!-- [1.1 begin headline] ================================================== --> <table width="100%" border="0"><tr><th align="center" bgcolor="#CCCC00"><font size=6>How to use Ghostscript</font></table> <!-- [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="#Pipe_input">Input from a pipe</a><li><a href="#Output_device">Selecting an output device</a><ul><li><a href="#Printer_resolution">Printer resolution</a><li><a href="#File_output">Output to files</a><ul><li><a href="#One_page_per_file">One page per file</a><li><a href="#Pipe_output">Output to a pipe</a><li><a href="#Output_to_graphics">Output to graphics file formats</a><li><a href="#Bounding_box_output">Bounding box output</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="#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="#Temp_files">Temporary files</a></ul><li><a href="#Environment_variables">Summary of environment variables</a><li><a href="#PDF">Using Ghostscript with PDF files</a><ul><li><a href="#PDF_stdin">PDF files from standard input</a><li><a href="#PDF_switches">Switches for PDF files</a><li><a href="#PDF_problems">Problems interpreting a PDF file</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="#MS-DOS">MS-DOS</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="#Switches">Switches</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="#Interaction_related_parameters">Interaction-related parameters</a><li><a href="#Output_selection_parameters">Device and output selection parameters</a><li><a href="#Other_parameters">Other parameters</a></ul></ul><li><a href="#Improving_performance">Improving performance</a><li><a href="#Debugging">Debugging</a><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></ul></blockquote> <!-- [1.2 end table of contents] =========================================== --> <!-- [1.3 begin hint] ====================================================== --> <p>For other information, see the <a href="Readme.htm">Ghostscriptoverview</a>, the new user's documentation on<a href="New-user.htm#Previewers">previewers</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] ================================================== --> <h1><a name="Invoking"></a>Invoking Ghostscript</h1> <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: <blockquote><b><tt>gs</tt></b> [switches] {filename 1} ... [switches] {filename <em>N</em>} ...</blockquote> <blockquote><table cellpadding=0 cellspacing=0><tr><th colspan=3 bgcolor="#CCCC00"><hr><font size="+1">Ghostscript's name on different systems</font><hr><tr>	<th align=left>System	<td>&nbsp;&nbsp;	<th align=left>Ghostscript's name<tr>	<td colspan=3><hr><tr>	<td>Unix	<td>&nbsp;<td><b><tt>gs</tt></b><tr>	<td>VMS	<td>&nbsp;<td><b><tt>gs</tt></b><tr>	<td>DOS &amp; MS Windows 3	<td>&nbsp;<td><b><tt>gs386</tt></b><tr>	<td>MS Windows 95/98	<td>&nbsp;<td><b><tt>gswin32</tt></b><tr>	<td>MS Windows 95/98 command line	<td>&nbsp;<td><b><tt>gswin32c</tt></b><tr>	<td>OS/2	<td>&nbsp;<td><b><tt>gsos2</tt></b></table></blockquote> <p>Note, though, that on a system with a windowed graphical user interface,it's common to use Ghostscript through a previewer, so you should read the<a href="New-user.htm#Previewers">section about previewers</a> in thedocumentation for new users. <p>Ghostscript is capable of interpreting PostScript, encapsulated PostScript(EPS), DOS EPS (EPSF), and -- if the executable was built for it -- AdobePortable Document Format (PDF).  The interpreter reads and executes thefiles in sequence, using the method described under"<a href="#File_searching">File searching</a>" to find them.  After doingthis, it reads further lines of PostScript language commands from theprimary input stream, normally the keyboard, interpreting each lineseparately.  To quit the interpreter, type "<b><tt>quit</tt></b>".  Theinterpreter also quits gracefully if it encounters end-of-file orcontrol-C. <p>The interpreter recognizes many <a href="#Switches">switches</a>. A switchmay appear anywhere in the command line, and applies to all files namedafter it on the line. Many of the switches include "<b><tt>=</tt></b>"followed by a parameter.  (However, with the DOS executable<b><tt>gs386.exe</tt></b> in the standard Ghostscript distribution, youmust use "<b><tt>#</tt></b>" rather than "<b><tt>=</tt></b>", because of astrange design decision in the Watcom C/C++ run-time library used to buildit.) <h2><a name="Help_command"></a>Help at the command line: <b><tt>gs -h</tt></b></h2> <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><b><tt>gs -h<br>gs -?</tt></b></blockquote> <p>(Of course, for "<b><tt>gs</tt></b>" use the right<a href="#Command_line">command for your system</a>.)  The message showsfor this executable <ul><li>its version<li>the format of the command to invoke it<li>a few of the most useful switches<li>the formats it can interpret<li>the devices for which it can produce output<li>where it looks for font files<li>where and how to send bug reports</ul> <h1><a name="Pipe_input"></a>Input from a pipe</h1> <p>As noted above, one normally specifies input with file names on the commandline.  However, one can also "pipe" input into Ghostscript by using thespecial file name "<b><tt>-</tt></b>" or "<b><tt>-_</tt></b>", for instance <blockquote>{some program producing PS} <b><tt>| gs</tt></b> {...options...} <b><tt>-</tt></b><br>{some program producing PS} <b><tt>| gs</tt></b> {...options...} <b><tt>-_</tt></b></blockquote> <p>These switches differ from a named file in two respects: <ol><li>When Ghostscript finishes reading from the pipe, it quits rather thangoing into interactive mode.  Because of this, these switches arereally only useful as the last argument on the command line. <li>These switches can't be used to pipe PDF input to Ghostscript.See "<a href="#PDF">Using Ghostscript with PDF files</a>" below.</ol> <p> The difference between "<b><tt>-</tt></b>" and "<b><tt>-_</tt></b>" is that"<b><tt>-</tt></b>" reads the input one character at a time, which is usefulfor programs such as GSview that generate input for Ghostscript dynamicallyand watch for some response, whereas "<b><tt>-_</tt></b>" reads the input inblocks, which is more efficient for ordinary (batch) execution. <h1><a name="Output_device"></a>Selecting an output device</h1> <p>Ghostscript may be built to handle multiple output devices, and it normallyopens and directs output to the first one built in.  Ghostscript's<b><tt>gs&nbsp;-h</tt></b> <a href="#Help_command">help message</a> liststhe output devices known to the executable.  Once you invoke Ghostscriptyou can also find out what devices are available by"<b><tt>devicenames&nbsp;==</tt></b>" at its command prompt. <p><a name="Source_code"></a> A little more information about devices appears near the beginning of thefiles <b><tt>devs.mak</tt></b> (for Aladdin's own drivers) and<b><tt>contrib.mak</tt></b> (for user-contributed drivers) used to buildGhostscript.  (If you got Ghostscript under the Aladdin<a href="Public.htm">Free Public License</a>, the person or place fromwhich you got it is also required to make the source code available to you;if you got it under the GNU General Public License (GPL), see the GNU<a href="http://www.gnu.org/copyleft/gpl.html">General Public License</a>for more information.) <p><a name="Device_output"></a>To use device <em>xyz</em> as the initial output device, use thecommand-line switch <blockquote>	<b><tt>-sDEVICE=</tt></b><em>xyz</em></blockquote> <p>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"<b><tt>gs&nbsp;myfile.ps</tt></b>" you might use <blockquote>	<b><tt>gs -sDEVICE=epson myfile.ps</tt></b></blockquote> <p>Alternatively, once you invoke Ghostscript and have its own command promptyou can type <blockquote><b><tt>	(epson) selectdevice<br>	(myfile.ps) run</tt></b></blockquote> <p>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 <b><tt>selectdevice</tt></b> procedure, forinstance like one of these: <blockquote><b><tt>	(vga) selectdevice<br>	(epson) selectdevice</tt></b></blockquote> <p><a name="GS_DEVICE"></a>A third possibility is to define an environment variable<b><tt>GS_DEVICE</tt></b> with the name of your desired default device.The order of precedence for these alternatives, highest to lowest, is: <blockquote><table cellpadding=0 cellspacing=0><tr>	<td><b><tt>selectdevice</tt></b>	<td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;	<td>Highest precedence<tr>	<td>(command line)	<td>&nbsp;	<td>&nbsp;<tr>	<td><b><tt>GS_DEVICE</tt></b>	<td>&nbsp;	<td>&nbsp;<tr>	<td>(first device built in)	<td>&nbsp;	<td>Default; lowest precedence</table></blockquote> <h2><a name="Printer_resolution"></a>Printer resolution</h2> <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> <p>For example, on Epson-compatible printers you have these choices: <blockquote><table cellpadding=0 cellspacing=0><tr>	<td><b><tt>gs -sDEVICE=epson</tt></b>	<td>&nbsp;&nbsp;	<td><b><tt>-r60x72</tt></b>	<td>&nbsp;&nbsp;	<td>9-pin	<td>&nbsp;&nbsp;	<td>lowest resolution	<td>&nbsp;&nbsp;	<td>fastest<tr>	<td>&nbsp;	<td>&nbsp;	<td><b><tt>-r240x72</tt></b>	<td>&nbsp;	<td>&nbsp;	<td>&nbsp;	<td>highest	<td>&nbsp;	<td>slowest<tr>	<td>&nbsp;<tr>	<td>&nbsp;	<td>&nbsp;	<td><b><tt>-r60x60</tt></b>	<td>&nbsp;	<td>24-pin	<td>&nbsp;	<td>lowest	<td>&nbsp;	<td>fastest<tr>	<td>&nbsp;	<td>&nbsp;	<td><b><tt>-r360x180</tt></b>	<td>&nbsp;	<td>&nbsp;	<td>&nbsp;	<td>highest	<td>&nbsp;	<td>slowest</table></blockquote> <h2><a name="File_output"></a>Output to files</h2> <p>If you select a printer as the output device, Ghostscript also allows you tocontrol where the device sends its output.  On DOS and MS Windows systems,output normally goes directly to the printer (<b><tt>PRN</tt></b>); on Unixor VMS systems normally to a temporary file for later printing.  To send theoutput to a file, use the <b><tt>-sOutputFile=</tt></b> switch (forcompatibility with older versions of Ghostscript,<b><tt>-sOUTPUTFILE=</tt></b> also works).  For instance, to direct alloutput into the file <b><tt>ABC.xyz</tt></b>, use <blockquote><b><tt>gs -sOutputFile=ABC.xyz</tt></b></blockquote> <p>The file name follows the PostScript convention that if a name begins with<b><tt>%</tt></b>, the name must be in the form <b><tt>%</tt></b>filedeviceor <b><tt>%</tt></b>filedevice<b><tt>%</tt></b>file.  The legal values offiledevice are system-dependent, but the following have consistent meaningsacross systems: <blockquote><table cellpadding=0 cellspacing=0><tr><th colspan=3 bgcolor="#CCCC00"><hr><font size="+1">"%{filedevice}%{file}" in <b><tt>-sOutputFile=</tt></b></font><hr><tr valign=bottom>	<th align=left>filedevice	<td>&nbsp;&nbsp;&nbsp;	<th align=left>Meaning<tr>	<td colspan=3><hr><tr valign=top>	<td><b><tt>%os%xyz</tt></b>	<td>&nbsp;	<td>An ordinary file named <b><tt>xyz</tt></b><tr valign=top>	<td><b><tt>%pipe%cmd</tt></b>	<td>&nbsp;	<td>(if supported) A pipe to an instance of the command <b><tt>cmd</tt></b><tr valign=top>	<td><b><tt>%stdout</tt></b>	<td>&nbsp;	<td>The standard output file</table></blockquote> <p>Note that on DOS and MS Windows systems, the <b><tt>%</tt></b> character hasa special meaning for the command processor (shell), so you will have todouble it, e.g., for a pipe on MS Windows, <blockquote><b><tt>gs -sOutputFile=%%pipe%%cmd</tt></b></blockquote> <h3><a name="One_page_per_file"></a>One page per file</h3> <p>You can also tell Ghostscript to put each page of output in a separatefile.  To send output to a series of files each representing a single page,use in the filename the <b><tt>printf</tt></b> format specifier"<b><tt>%d</tt></b>" (or its extended form like "<b><tt>%02d</tt></b>");for instance <blockquote><table cellpadding=0 cellspacing=0><tr><th colspan=3 bgcolor="#CCCC00"><hr><font size="+1">"%{n}d" in <b><tt>-sOutputFile=</tt></b></font><hr><tr valign=bottom>	<th align=left>Output specification	<td>&nbsp;&nbsp;&nbsp;	<th align=left>Produces the series of 1-page files<tr>	<td colspan=3><hr><tr valign=top>	<td><b><tt>-sOutputFile=ABC%d.xyz</tt></b>	<td>&nbsp;	<td><b><tt>ABC1.xyz</tt></b> ... <b><tt>ABC10.xyz</tt></b> ...<tr valign=top>	<td><b><tt>-sOutputFile=ABC%03d.xyz</tt></b>	<td>&nbsp;	<td><b><tt>ABC001.xyz</tt></b> ... <b><tt>ABC010.xyz</tt></b> ...</table></blockquote> <p>As noted above, on DOS and MS Windows systems, you will have to double the<b><tt>%</tt></b> character, e.g., <blockquote><b><tt>gs -sOutputFile=ABC%%03d.xyz</tt></b></blockquote> <h3><a name="Pipe_output"></a>Output to a pipe</h3> <p>On Unix and (32-bit) MS Windows systems you can use this switch to sendoutput directly to a pipe.  For example, to pipe the output to<b><tt>lpr</tt></b>, use the command <blockquote><b><tt>	gs -sOutputFile=\|lpr</tt></b></blockquote>or, as noted above,<blockquote><b><tt>	gs -sOutputFile=%pipe%lpr</tt></b></blockquote> <p>(doubling the <b><tt>%</tt></b> characters on MS Windows systems, as notedabove.)  You can also send output to standard output for piping in the usualway supported by the system: <blockquote>	<b><tt>gs -sOutputFile=- -q |</tt></b> ...</blockquote>or, as noted above,<blockquote>	<b><tt>gs -sOutputFile=%stdout -q |</tt></b> ...</blockquote> <p>(again, doubling the <b><tt>%</tt></b> character on MS Windows systems.)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. <h3><a name="Output_to_graphics"></a>Output to graphics file formats</h3> <p>File formats like PCX and PBM are also "devices".  When you select a fileformat as the "device", you must also specify an output file, for instance 

Lines 1–500 of 2752. Load more