1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 2"http://www.w3.org/TR/html4/loose.dtd"> 3<html> 4<head> 5<title>How to use Ghostscript</title> 6<!-- $Id: Use.htm,v 1.136 2005/10/20 19:46:23 ray Exp $ --> 7<!-- Originally: use.txt --> 8<link rel="stylesheet" type="text/css" href="gs.css" title="Ghostscript Style"> 9</head> 10 11<body> 12<!-- [1.0 begin visible header] ============================================ --> 13 14<!-- [1.1 begin headline] ================================================== --> 15 16<h1>How to use Ghostscript</h1> 17 18<!-- [1.1 end headline] ==================================================== --> 19 20<!-- [1.2 begin table of contents] ========================================= --> 21 22<h2>Table of contents</h2> 23 24<blockquote><ul> 25<li><a href="#Invoking">Invoking Ghostscript</a> 26<ul> 27<li><a href="#Help_command">Help at the command line: <b><tt>gs -h</tt></b></a> 28</ul> 29<li><a href="#Output_device">Selecting an output device</a> 30<ul> 31<li><a href="#Output_resolution">Output resolution</a> 32<li><a href="#File_output">Output to files</a> 33<ul> 34<li><a href="#One_page_per_file">One page per file</a> 35</ul> 36<li><a href="#Paper_size">Choosing paper size</a> 37<li><a href="#Change_default_size">Changing the installed default paper size</a> 38</ul> 39<li><a href="#Pipes">Interacting with pipes</a> 40<li><a href="#PDF">Using Ghostscript with PDF files</a> 41<ul> 42<li><a href="#PDF_switches">Switches for PDF files</a> 43<li><a href="#PDF_problems">Problems interpreting a PDF file</a> 44<li><a href="#PDF_stdin">PDF files from standard input</a> 45</ul> 46 47<li><a href="#EPS">Using Ghostscript with EPS files</a> 48<li><a href="#SPOT">Using Ghostscript with overprinting and spot colors</a> 49<li><a href="#Finding_files">How Ghostscript finds files</a> 50<ul> 51<li><a href="#PS_resources">Finding PostScript Level 2 resources</a> 52<li><a href="#Font_lookup">Font lookup</a> 53<li><a href="#CIDFonts">CID fonts</a> 54<li><a href="#CIDFontSubstitution">CID font substitution</a> 55<li><a href="#Temp_files">Temporary files</a> 56</ul> 57 58<li><a href="#Platforms">Notes on specific platforms</a> 59<ul> 60<li><a href="#Unix">Unix</a> 61<li><a href="#VMS">VMS</a> 62<ul> 63<li><a href="#VMS_X_Windows">Using X Windows on VMS</a> 64</ul> 65<li><a href="#MS_Windows">MS Windows</a> 66<li><a href="#X_Windows">X Windows</a> 67<ul> 68<li><a href="#X_resources">X resources</a> 69<li><a href="#X_server_bugs">Working around bugs in X servers</a> 70<li><a href="#X_fonts">X fonts</a> 71<li><a href="#GS_fonts_as_X_fonts">Using Ghostscript fonts on X displays</a> 72<li><a href="#X_device_parameters">X device parameters</a> 73</ul> 74<li><a href="#SCO_Unix">SCO Unix</a> 75</ul> 76 77<li><a href="#Options">Command line options</a> 78<ul> 79<li><a href="#General_switches">General switches</a> 80<ul> 81<li><a href="#Input_control">Input control</a> 82<li><a href="#File_searching">File searching</a> 83<li><a href="#Parameters">Setting parameters</a> 84<li><a href="#Quiet">Suppress messages</a> 85</ul> 86<li><a href="#Parameter_switches">Parameter switches (<b><tt>-d</tt></b> and <b><tt>-s</tt></b>)</a> 87<ul> 88<li><a href="#Rendering_parameters">Rendering parameters</a> 89<li><a href="#Page_parameters">Page parameters</a> 90<li><a href="#Font_related_parameters">Font-related parameters</a> 91<li><a href="#Resource_related_parameters">Resource-related parameters</a> 92<li><a href="#Interaction_related_parameters">Interaction-related parameters</a> 93<li><a href="#Output_selection_parameters">Device and output selection parameters</a> 94<li><a href="#EPS_parameters">EPS parameters</a> 95<li><a href="#Other_parameters">Other parameters</a> 96</ul> 97</ul> 98<li><a href="#Improving_performance">Improving performance</a> 99<li><a href="#Environment_variables">Summary of environment variables</a> 100 101<li><a href="#Debugging">Debugging</a> 102<ul> 103<li><a href="#Debug_switches">Debug Switches</a> 104<li><a href="#Visual_trace">Visual Trace</a> 105</ul> 106<li><a href="#Known_paper_sizes">Appendix: Paper sizes known to Ghostscript</a> 107<li><a href="#X_font_mappings">Appendix: X default font mappings</a> 108<ul> 109<li><a href="#Standard_X_server_fonts">Standard X servers</a> 110<ul> 111<li><a href="#X_regular_fonts">Regular fonts</a> 112<li><a href="#X_symbol_fonts">Symbol fonts</a> 113<li><a href="#X_dingbat_fonts">Dingbat fonts</a> 114</ul> 115<li><a href="#OpenWindows_fonts">Sun OpenWindows</a> 116</ul> 117<li><a href="#FAPI_run">Appendix: Running Ghostscript with 3d party font renderers</a> 118</ul></blockquote> 119 120<!-- [1.2 end table of contents] =========================================== --> 121 122<!-- [1.3 begin hint] ====================================================== --> 123 124<p>For other information, see the <a href="Readme.htm">Ghostscript 125overview</a> and, if necessary, how to 126<a href="Install.htm">install Ghostscript</a>. 127 128<!-- [1.3 end hint] ======================================================== --> 129 130<hr> 131 132<!-- [1.0 end visible header] ============================================== --> 133 134<!-- [2.0 begin contents] ================================================== --> 135 136<h2><a name="Invoking"></a>Invoking Ghostscript</h2> 137 138<p>This document describes how to use the command line Ghostscript client. 139Ghostscript is also used as a general engine inside other applications (for viewing files for example). 140Please refer to the documentation for those applications for using Ghostscript in other contexts. 141 142<p><a name="Command_line"></a> The command line to invoke Ghostscript is 143essentially the same on all systems, although the name of the executable 144program itself may differ among systems. For instance, to invoke 145Ghostscript on unix-like systems type: 146 147<blockquote> 148 <pre><b><tt>gs</tt></b> [options] {filename 1} ... [options] {filename <em>N</em>} ... 149</pre></blockquote> 150 151<p>Here are some basic examples. The details of how these work are described below. 152 153<p>To view a file: 154<blockquote><pre>gs -dSAFER -dBATCH document.pdf</pre></blockquote> 155You'll be prompted to press <em>return</em> between pages. 156 157<p>To convert a figure to an image file: 158<blockquote><pre>gs -dSAFER -dBATCH -dNOPAUSE -sDEVICE=png16m -dGraphicsAlphaBits=4 \ 159 -sOutputFile=tiger.png tiger.eps</pre></blockquote> 160 161<p>To render the same image at 300 dpi: 162<blockquote><pre>gs -dSAFER -dBATCH -dNOPAUSE -sDEVICE=png16m -r300 \ 163 -sOutputFile=tiger_300.png tiger.eps 164</pre></blockquote> 165 166<p>To render a figure in grayscale: 167<blockquote><pre>gs -dSAFER -dBATCH -dNOPAUSE -sDEVICE=pnggray -sOutputFile=figure.png figure.pdf 168</pre></blockquote> 169 170<p>To rasterize a whole document: 171<blockquote><pre>gs -dSAFER -dBATCH -dNOPAUSE -sDEVICE=pgmraw -r150 \ 172 -dTextAlphaBits=4 -sOutputFile='paper-%00d.pgm' paper.ps</pre></blockquote> 173 174<p>There are also a number of utility scripts for common 175 176to convert a PostScript document to PDF: 177<blockquote><pre>ps2pdf file.ps</pre></blockquote> 178The output is saved as file.pdf. 179 180<p>There are other utility scripts besides <tt>ps2pdf</tt>, including <tt>pdf2ps</tt>, <tt>ps2epsi</tt>, <tt>pdf2dsc</tt>, <tt>ps2ascii</tt>, 181<tt>ps2ps</tt> and <tt>ps2ps2</tt>. These just call Ghostscript with the appropriate 182(if complicated) set of options. You can use the 'ps2' set with eps files. 183 184<p> 185Ghostscript is capable of interpreting PostScript, encapsulated PostScript 186(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. 187 188<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. 189 190<p> 191The 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>" 192followed by a parameter. The most important are described in detail here. Please see the reference 193 sections on <a href="#Options">options</a> and <a href="Devices.htm">devices</a> for a more complete listing. 194 195<h3><a name="Help_command"></a>Help at the command line: <b><tt>gs -h</tt></b></h3> 196 197<p> 198You can get a brief help message by invoking Ghostscript with the 199<b><tt>-h</tt></b> or <b><tt>-?</tt></b> switch, like this: 200 201<blockquote><pre> 202gs -h 203gs -? 204</pre></blockquote> 205 206<p> 207The message shows for that version of the Ghostscript executable: 208 209<ul> 210<li>the version and release information 211<li>the general format of the command line 212<li>a few of the most useful options 213<li>the formats it can interpret 214<li>the available output devices 215<li>the search path 216<li>the bug report address 217</ul> 218 219<p> 220On other systems the executable may have a different name: 221 222<blockquote><table cellpadding=0 cellspacing=0> 223<tr bgcolor="#CCCC00"> 224 <th align=left>System 225 <th> 226 <th align=left>invocation name 227<tr> <td>Unix 228 <td> <td><b><tt>gs</tt></b> 229<tr> <td>VMS 230 <td> <td><b><tt>gs</tt></b> 231<tr> <td>MS Windows 95 and later 232 <td> <td><b><tt>gswin32c</tt></b> 233<tr> <td>MS Windows 3.1/Win32s 234 <td> <td><b><tt>gswin32</tt></b> 235<tr> <td>OS/2 236 <td> <td><b><tt>gsos2</tt></b> 237</table></blockquote> 238 239 240<h2><a name="Output_device"></a>Selecting an output device</h2> 241 242<p> 243Ghostscript 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. 244 245<p> 246The 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 -h</tt>) lists 247the 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. 248 249<p><a name="Device_output"></a> 250Note that this switch must precede the name of the first input file, and 251only its first use has any effect. For example, for printer output in a 252configuration that includes an Epson printer driver, instead of just 253<tt>'gs myfile.ps'</tt> you might use 254 255<blockquote> 256 <b><tt>gs -sDEVICE=epson myfile.ps</tt></b> 257</blockquote> 258 259<p><a name="GS_DEVICE"></a> 260The output device can also be set through the <tt>GS_DEVICE</tt> environment variable. 261 262<p> 263Once you invoke Ghostscript 264you can also find out what devices are available by typing 265'<tt>devicenames ==</tt>' at the interactive prompt. 266You can set the output device and process a file from the interactive prompt as well: 267 268 269<blockquote><pre> 270(epson) selectdevice 271(myfile.ps) run 272</pre></blockquote> 273 274All output then goes to the Epson printer instead of the display until you 275do something to change devices. You can switch devices at any time by 276using the <tt>selectdevice</tt> procedure, for 277instance like one of these: 278 279<blockquote><pre> 280(x11alpha) selectdevice 281(epson) selectdevice 282</pre></blockquote> 283 284<h3><a name="Output_resolution"></a>Output resolution</h3> 285 286<p> 287Some printers can print at several different resolutions, letting you 288balance resolution against printing speed. To select the resolution on 289such a printer, use the <b><tt>-r</tt></b> switch: 290 291<blockquote> 292 <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> 293</blockquote> 294 295where <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>. 296 297<p> 298The <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. 299 300<h3><a name="File_output"></a>Output to files</h3> 301 302<p> 303Ghostscript 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. 304 305<p> 306To send the output to a file, use the <tt>-sOutputFile=</tt> switch. 307For instance, to direct all output into the file <tt>ABC.xyz</tt>, use 308 309<blockquote><b><tt> 310gs -sOutputFile=ABC.xyz 311</tt></b></blockquote> 312 313<p> 314When 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. 315 316<p> 317Ghostscript also accepts the special filename '<tt>-</tt>' which indicates the output should be written to standard output (the command shell). 318 319<p> 320Be aware that filenames beginning with the character <tt>%</tt> have a special meaning in PostScript. If you need to specify a file name that actually 321begins 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 322 323<blockquote> 324<b><tt>gs -sOutputFile=%os%%abc</tt></b> 325</blockquote> 326 327Please 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. 328 329<p> 330Note 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: 331 332<blockquote> 333<b><tt>gs -sOutputFile=%%os%%%%abc</tt></b> (on MS Windows) 334</blockquote> 335 336<h4><a name="One_page_per_file"></a>One page per file</h4> 337 338<p> 339Specifying a single output file works fine for printing and rasterizing 340figures, but sometimes you want images of each page of a multi-page 341document. You can tell Ghostscript to put each page of output in a 342series of similarly named files. To do this place a template 343'<tt>%d</tt>' in the filename which Ghostscript will replace with the 344page number. 345 346<p> 347You can also control the number of digits used in the file name: 348 349<blockquote><dl> 350<dt><b><tt>-sOutputFile=ABC-%d.png</tt></b> 351<dd>produces '<tt>ABC-1.png</tt>', ... , '<tt>ABC-10.png</tt>', ...<p> 352<dt><b><tt>-sOutputFile=ABC-%03d.pgm</tt></b> 353<dd>produces '<tt>ABC-001.pgm</tt>', ... , '<tt>ABC-010.pgm</tt>', ...<p> 354<dt><b><tt>-sOutputFile=ABC_p%04d.tiff</tt></b> 355<dd>produces '<tt>ABC_p0001.tiff</tt>', ... , '<tt>ABC_p0510.tiff</tt>', ... , '<tt>ABC_p5238.tiff</tt>'<p> 356</dl></blockquote> 357 358Generally <tt>%03d</tt> is the best option for normal documents. 359 360<p> 361Note however that this features is not supported by all devices; in particular 362it does not work with document-oriented output devices like <tt>pdfwrite</tt> and 363<tt>pswrite</tt>. See the <tt>-dFirstPage</tt> and <tt>-dLastPage</tt> switches 364<a href="#PDF_switches">below</a> for a way to extract single pdf pages. 365 366<p> 367As noted above, on MS Windows systems, you will have to double the 368<tt>%</tt> character, e.g., 369 370<blockquote><tt><b> 371gs -sOutputFile=ABC%%03d.xyz 372</b></tt></blockquote> 373 374 375<h3><a name="Paper_size"></a>Choosing paper size</h3> 376 377<p> 378Ghostscript is distributed configured to use U.S. letter paper as its 379default page size. There are two ways to select other paper sizes from the 380command line: 381 382<ul> 383 384<li> 385If the desired paper size is listed in the section on <a 386href="#Known_paper_sizes">paper sizes known to Ghostscript</a> below, you 387can select it as the default paper size for a single invocation of 388Ghostscript by using the <b><tt>-sPAPERSIZE=</tt></b> switch, for instance 389 390<blockquote><b><tt> 391-sPAPERSIZE=a4<br> 392-sPAPERSIZE=legal 393</tt></b></blockquote> 394 395<li> 396Otherwise you can set the page size using the 397pair of switches 398 399<blockquote> 400<b><tt>-dDEVICEWIDTHPOINTS=</tt></b><em>w</em> 401<b><tt>-dDEVICEHEIGHTPOINTS=</tt></b><em>h</em> 402</blockquote> 403 404Where <em>w</em> be the desired paper width and <em>h</em> be the 405desired paper height in <em>points</em> (units of 1/72 of an inch). 406</ul> 407 408<p> 409Individual documents can (and often do) specify a paper size, which takes 410precedence over the default size. To force a specific paper size and 411ignore the paper size specified in the document, select a paper size as 412just described, and also include the 413<a href="#FIXEDMEDIA"><b><tt>-dFIXEDMEDIA</tt></b> switch</a> on the 414command line. 415 416<p> 417The default set of paper sizes will be included in the <b><tt>currentpagedevice</tt></b> 418in the <b><tt>InputAttributes</tt></b> dictionary with each paper size as 419one of the entries. The last entry in the dictionary (which has numeric keys) 420is a non-standard (Ghostscript extension) type of PageSize where the array 421has four elements rather than the standard two elements. This four element 422array represents a page size range where the first two elements are the lower 423bound of the range and the second two are the upper bound. By default these 424are [0, 0] for the lower bound and [16#fffff, 16#fffff] for the upper bound. 425<br> 426The range type of PageSize is intended to allow flexible page size sepcification 427for non-printer file formats such as JPEG, PNG, TIFF, EPS, ... 428<br> 429For actual printers, either the entire <b><tt>InputAttributes</tt></b> dictionary 430should be replaced or the range type entry should not be included. To simplify 431using the default page sizes in the <b><tt>InputAttributes</tt></b> dictionary, 432the command line option <b><tt>-dNORANGEPAGESIZE</tt></b> can be used. Using 433this option will result in automatic rotation of the document page if the requested 434page size matches one of the default page sizes. 435 436<h3><a name="Change_default_size"></a>Changing the installed default paper size</h3> 437 438<p> 439You 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>. 440This 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. 441 442<p> 443Find the line 444 445<blockquote><pre> 446% /DEFAULTPAPERSIZE (a4) def 447</pre></blockquote> 448 449<p> 450Then to make A4 the default paper size, uncomment the line to change 451this to 452 453<blockquote><pre> 454/DEFAULTPAPERSIZE (a4) def 455</pre></blockquote> 456 457<p> 458For <tt>a4</tt> you can substitute any 459<a href="#Known_paper_sizes">paper size Ghostscript knows</a>. 460 461<p> 462This supecedes the previous method of uncommenting the line 463<b><tt>% (a4) ...</tt></b>. 464 465<p> 466Sometimes the initialization files are compiled into Ghostscript and cannot be changed. 467 468<h2><a name="Pipes"></a>Interacting with pipes</h2> 469 470<p> 471As noted above, input files are normally specified on the command 472line. However, one can also "pipe" input into Ghostscript from another 473program by using the special file name '<b><tt>-</tt></b>' which is interpreted as standard input. Examples: 474 475<blockquote> 476{<em>some program producing ps</em>} <b><tt>| gs</tt></b> [options] <b><tt>-</tt></b> 477<br> 478<tt>zcat paper.ps.gz</tt> <b><tt>| gs</tt></b> <b><tt>-</tt></b> 479</blockquote> 480 481<p> 482<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> 483 484<p> 485When Ghostscript finishes reading from the pipe, it quits rather than 486going into interactive mode. Because of this, options and files after the '<tt>-</tt>' in the command line will be ignored. 487 488<p> 489On 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 490 491<blockquote><tt> 492 <b>gs -q -sOutputFile=- |</b> lpr 493</tt></blockquote> 494 495<p> 496In this case you must also use the <a href="#Quiet"><b><tt>-q</tt></b> 497switch</a> to prevent Ghostscript from writing messages to standard output 498which become mixed with the intended output stream. 499 500<p> 501Similar results can be obtained with the <tt>%stdout</tt> and <tt>%pipe%</tt> filedevices. The example above would become 502 503<blockquote><tt> 504 <b>gs -sOutputFile=%stdout -q |</b> lpr 505</tt></blockquote> 506or 507<blockquote><tt> 508 <b>gs -sOutputFile=%pipe%</b>lpr 509</tt></blockquote> 510 511(again, doubling the <b><tt>%</tt></b> character on MS Windows systems.) 512 513<p> 514In the last case, <tt>-q</tt> isn't necessary since Ghostscript handles the pipe itself and messages sent to stdout will be printed as normal. 515 516<h2><a name="PDF"></a>Using Ghostscript with PDF files</h2> 517 518<p> 519Ghostscript is normally built to interpret both PostScript and PDF files, examining each file to determine automatically whether its contents are PDF or PostScript. All the normal switches and procedures for interpreting PostScript files also apply to PDF files, with a few exceptions. In addition, the 520<tt>pdf2ps</tt> utility uses Ghostscript to convert PDF to (Level 2) PostScript. 521 522<h3><a name="PDF_switches"></a>Switches for PDF files</h3> 523 524<p>Here are some command line options specific to PDF 525 526<dl> 527<dt><b><tt>-dFirstPage=</tt></b><em>pagenumber</em> 528<dd>Begins interpreting on the designated page of the document. 529</dl> 530 531<dl> 532<dt><b><tt>-dLastPage=</tt></b><em>pagenumber</em> 533<dd>Stops interpreting after the designated page of the document. 534</dl> 535 536 <dl> 537<dt><b><tt>-dPDFFitPage</tt></b> 538<dd>Rather than selecting a PageSize given by the PDF MediaBox or 539CropBox (see -dUseCropBox), the PDF file will be scaled to fit 540the current device page size (usually the default page size). 541<p> 542This is useful to avoid clipping information on a PDF document when 543sending to a printer that may have unprintable areas at the edge of 544the media larger than allowed for in the document. 545<p> 546This is also useful for creating fixed size images of PDF files 547that may have a variety of page sizes, for example thumbnail images. 548</dl> 549 550<dl> 551<dt><b><tt>-dPrinted</tt></b> 552<dt><b><tt>-dPrinted=false</tt></b> 553<dd>Determines whether the file should be displayed or printed using the 554"screen" or "printer" options for annotations and images. With 555<b><tt>-dPrinted</tt></b>, the output will use the file's "print" 556options; with <b><tt>-dPrinted=false</tt></b>, the output will use the 557file's "screen" options. If neither of these is specified, the output will 558use the screen options for any output device that doesn't have an 559<b><tt>OutputFile</tt></b> parameter, and the printer options for 560devices that do have this parameter. 561</dl> 562 563<dl> 564<dt><b><tt>-dUseCropBox</tt></b> 565<dd>Sets the page size to the CropBox rather than the MediaBox. 566Some files have a CropBox that is smaller than the MediaBox and 567may include white space, registration or cutting marks outside 568the CropBox. Using this option will set the page size 569appropriately for a viewer. 570</dl> 571 572<dl> 573<dt><b><tt>-sPDFPassword=</tt></b><em>password</em> 574<dd>Sets the user or owner password to be used in decoding encrypted 575PDF files. 576</dl> 577 578<h3><a name="PDF_problems"></a>Problems interpreting a PDF file</h3> 579 580<p> 581Occasionally you may try to read or print a 'PDF' file that 582Ghostscript doesn't recognize as PDF, even though the same file 583<b><em>can</em></b> be opened and interpreted by an Adobe Acrobat viewer. 584In many cases, this is because of incorrectly generated PDF. Acrobat 585tends to be very forgiving of invalid PDF files. Ghostscript tends to 586expect files to conform to the standard. For example, even though 587valid PDF files must begin with <b><tt>%PDF</tt></b>, Acrobat will 588scan the first 1000 bytes or so for this string, and ignore any preceding 589garbage. 590 591<p> 592In the past, Ghostscript's policy has been to simply fail with an 593error message when confronted with these files. This policy has, no 594doubt, encouraged PDF generators to be more careful. However, we now 595recognize that this behavior is not very friendly for people who just 596want to use Ghostscript to view or print PDF files. Our new policy is 597to try to render broken PDF's, and also to print a warning, so that 598Ghostscript is still useful as a sanity-check for invalid files. 599 600<h3><a name="PDF_stdin"></a>PDF files from standard input</h3> 601 602<p> 603The PDF language, unlike the PostScript language, inherently requires 604random access to the file. 605If you provide PDF to standard input using the 606special filename <a href="#Pipes">'<tt>-</tt>'</a>, 607Ghostscript will copy it to a temporary file before interpreting the PDF. 608 609<h2><a name="EPS"></a>Using Ghostscript with EPS files</h2> 610<p> 611Encapsulated PostScript (EPS) files are intended to be incorporated 612in other PostScript documents and may not display or print on their 613own. An EPS file must conform to the Document Structuring Conventions, 614must include a <b><tt>%%BoundingBox</tt></b> line to indicate the 615rectangle in which it will draw, must not use PostScript commands 616which will interfere with the document importing the EPS, 617and can have either zero pages or one page. 618Ghostscript has support for handling EPS files, but requires 619that the <b><tt>%%BoundingBox</tt></b> be in the header, 620not the trailer. 621To customize EPS handling, see <a href="#EPS_parameters">EPS parameters</a>. 622 623<p> 624For the official description of the EPS file format, please 625refer to the Adobe documentation in their tech note #5002. It 626is available from: 627<a href="http://partners.adobe.com/public/developer/ps/index_specs.html" 628class="offsite"> 629http://partners.adobe.com/public/developer/ps/index_specs.html</a> 630 631<h2><a name="SPOT"></a>Using Ghostscript with overprinting and spot colors</h2> 632 633<p> 634In general with PostScript and PDF interpreters, the handling of 635<b>overprinting</b> and <b>spot colors</b> depends upon the 636process color model of the <a href="#Output_device">output device</a>. Devices 637that produce gray or RGB output have an <b>additive</b> process color model. 638Devices which produce CMYK output have a <b>subtractive</b> process color model. 639Devices may, or may not, have support for spot colors. 640 641<blockquote><i> 642Note: The differences in appearance of files with overprinting and spot colors 643caused by the differences in the color model of the output device are part of the 644PostScript and PDF specifications. They are not due to a limitation in the 645implementation of Ghostscript or its output devices. 646</i></blockquote> 647 648<p> 649With devices which use a subtractive process color model, both PostScript 650and PDF allow the drawing of objects using colorants (inks) for one or more planes 651without affecting the data for the remaining colorants. Thus the inks for one 652object may <b><tt>overprint</tt></b> the inks for another object. In some cases 653this produces a transparency like effect. (The effects of overprinting should 654not be confused with the PDF 1.4 blending operations which are supported for 655all output devices.) Overprinting is not allowed for devices with an additive 656process color model. With files that use overprinting, the appearance of the 657resulting image can differ between devices which produce RGB output versus devices 658which produce CMYK output. Ghostscript automatically overprints (if needed) 659when the output device uses a subtractive process color model. For example, 660if the file is using overprinting, differences can be seen in the appearance 661of the output from the <a href="Devices.htm#TIFF">tiff24nc and tiff32nc devices</a> 662which use an RGB and a CMYK process color models. 663 664<p> 665Most of the Ghostscript <a href="Devices.htm">output devices</a> do not have 666file formats which support spot colors. Instead spot colors are converted using 667the tint transform function contained within the color space definition.. However 668there are several devices which have support for spot colors. The PSD format 669(Adobe Photoshop) produced by the <a href="Devices.htm#PSD">psdcmyk device</a> 670contains both the raster data plus an equivalent CMYK color for each spot color. 671This allows Photoshop to simulate the appearance of the spot colors. The <a href="Devices.htm#display_device">display 672device (MS Windows, OS/2, gtk+)</a> can be used with different color models: 673Gray, RGB, CMYK only, or CMYK plus spot colors (separation). The display device, 674when using its CMYK plus spot color (separation) mode, also uses an equivalent 675CMYK color to simulate the appearance of the spot color. The 676<a href="Devices.htm#TIFF">tiffsep 677device</a> creates output files for each separation (CMYK and any spot colors 678present). It also creates a composite CMYK file using an equivalent CMYK color 679to simulate the appearance of spot colors. The 680<a href="Devices.htm#XCF">xcfcmyk device</a> 681creates output files with spot colors placed in separate alpha channels. (The 682XCF file format does not currently directly support spot colors.) 683 684<p> 685Overprinting with spot colors is not allowed if the tint transform function 686is being used to convert spot colors. Thus if spot colors are used with overprinting, 687then the appearance of the result can differ between output devices. One result 688would be obtained with a CMYK only device and another would be obtained with 689a CMYK plus spot color device. In a worst case situation where a file has overprinting 690with both process (CMYK) and spot colors, it is possible to get three different 691appearances for the same input file using the 692<a href="Devices.htm#TIFF">tiff24nc</a> (RGB), 693<a href="Devices.htm#TIFF">tiff32nc</a> (CMYK), and 694<a href="Devices.htm#TIFF">tiffsep</a> (CMYK plus spot colors) devices. 695 696<blockquote><i> 697In Adobe Acrobat, viewing of the effects of overprinting is enabled by the 698'Overprint Preview' item in the 'Advanced' menu. This feature is not available 699in the free Acrobat Reader. The free Acrobat Reader also uses the tint transform 700functions to convert spot colors to the appropriate alternate color space. 701</i></blockquote> 702 703 704<hr> 705 706<h2><a name="Finding_files"></a>How Ghostscript finds files</h2> 707 708<p> 709When looking for initialization files (<b><tt>gs_*.ps</tt></b>, 710<b><tt>pdf_*.ps</tt></b>), font files, the <b><tt>Fontmap</tt></b> file, 711files named on the command line, and resource files, Ghostscript first tests whether the 712file name specifies an absolute path. 713 714<blockquote><table cellpadding=0 cellspacing=0> 715<tr><th colspan=3 bgcolor="#CCCC00"><hr><font size="+1">Testing a file name for an absolute path</font><hr> 716<tr> <th align=left>System 717 <td> 718 <th align=left>Does the name ... 719<tr> <td colspan=3><hr> 720<tr> <td valign=top>Unix 721 <td> 722 <td>Begin with <b><tt><u>/</u></tt></b> ? 723<tr> <td valign=top>MS Windows 724 <td> 725 <td>Have <b><tt><u>:</u></tt></b> as its second character, or 726 begin with <b><tt><u>/</u></tt></b>, <b><tt><u>\</u></tt></b>, 727 or <b><tt><u>//servername/share/</u></tt></b> ? 728<tr> <td valign=top>VMS 729 <td> 730 <td>Contain a node, device, or root specification? 731</table></blockquote> 732 733<p>If the test succeeds, Ghostscript tries to open the file 734using the name given. Otherwise it tries directories in this order: 735 736<ol> 737<li>The current directory (unless disabled by the 738<a href="#P-_switch"><b><tt>-P-</tt></b> switch</a>); 739 740<li>The directories specified by <a href="#I_switch"><b><tt>-I</tt></b> 741switches</a> in the command line, if any; 742 743<li>The directories specified by the <b><tt>GS_LIB</tt></b> 744environment variable, if any; 745 746<li>The directories specified by the 747<b><tt>GS_LIB_DEFAULT</tt></b> macro (if any) in the makefile 748when this executable was built. 749</ol> 750 751<p> 752<b><tt>GS_LIB_DEFAULT</tt></b>, 753<b><tt>GS_LIB</tt></b>, and the 754<b><tt>-I</tt></b> parameter may specify either a single 755directory or a list of directories separated by a character appropriate for 756the operating system ("<b><tt>:</tt></b>" on Unix systems, 757"<b><tt>,</tt></b>" on VMS systems, and 758"<b><tt>;</tt></b>" on MS Windows systems). We think that trying 759the current directory first is a very bad idea -- it opens serious security 760loopholes and can lead to very confusing errors if one has more than one 761version of Ghostscript in one's environment -- but when we attempted to 762change it, users insisted that we change it back. You can disable looking 763in the current directory first by using the 764<a href="#P_switch"><b><tt>-P-</tt></b> switch</a>. 765 766<p> 767Note that Ghostscript does not use this file searching algorithm for the 768<b><tt>run</tt></b> or <b><tt>file</tt></b> 769operators: for these operators, it simply opens the file with the name 770given. To run a file using the searching algorithm, use 771<b><tt>runlibfile</tt></b> instead of 772<b><tt>run</tt></b>. 773 774<h3><a name="PS_resources"></a>Finding PostScript Level 2 resources</h3> 775 776<p> 777Adobe specifies that resources are installed in a single directory. 778Ghostscript instead maintains a list of resource directories, 779and uses an extended method for finding resource files. 780 781<p> 782The search for a resource file depends on whether 783the value of the system parameter <b><tt>GenericResourceDir</tt></b> 784specifies an absolute path. The user may set it as explained in 785<a href="#Resource_related_parameters">Resource-related parameters</a>. 786 787<p> 788If the user doesn't set the system parameter <b><tt>GenericResourceDir</tt></b>, 789Ghostscript creates a default value for it with 790attaching the string <b><tt>../Resource</tt></b> 791to directory paths explained in 792<a href="#Finding_files">How Ghostscript finds files</a>, 793except the current directory. 794The first successful combination is used. 795 796<p> 797If the value of the system parameter <b><tt>GenericResourceDir</tt></b> 798is an absolute path (the default), 799Ghostscript assumes a single resource directory. 800It concatenates : 801 802<ol> 803<li>The value of the system parameter <b><tt>GenericResourceDir</tt></b>; 804<li>The name of the resource category (for instance, <b><tt>CMap</tt></b>); 805<li>The name of the resource instance (for instance, <b><tt>Identity-H</tt></b>). 806</ol> 807 808<p>If the value of the system parameter <b><tt>GenericResourceDir</tt></b> 809is not an absolute path, 810Ghostscript assumes multiple resource directories. 811In this case it concatenates : 812 813<ol> 814<li>A directory listed in the section 815<a href="#Finding_files">How Ghostscript finds files</a>, 816except the current directory; 817 818<li>The value of the system parameter <b><tt>GenericResourceDir</tt></b>; 819 820<li>The name of the resource category (for instance, <b><tt>CMap</tt></b>); 821 822<li>The name of the resource instance (for instance, <b><tt>Identity-H</tt></b>) 823</ol> 824 825Due to possible variety of the part 1, the first successful combination is used. 826For example, if the value of the system parameter <b><tt>GenericResourceDir</tt></b> 827is the string <b><tt>../Resource/</tt></b> 828(or its equivalent in the file path syntax of the underlying platform), 829Ghostscript searches for <b><tt>../Resource/CMap/Identity-H</tt></b> 830from all directories listed in 831<a href="#Finding_files">How Ghostscript finds files</a>. 832So in this example, if the user on a Windows platform specifies 833the command line option <b><tt>-I.;../gs/lib;c:/gs8.50/lib</tt></b>, 834Ghostscript searches for <b><tt>../gs/Resource/CMap/Identity-H</tt></b> and 835then for <tt><b>c:/gs8.50/Resource/CMap/Identity-H</b></tt>. 836 837<p> 838To get a proper platform dependent syntax Ghostscript inserts 839the value of the system parameter 840<b><tt>GenericResourcePathSep</tt></b> (initially 841"<b><tt>/</tt></b>" on Unix and Windows, "<b><tt>:</tt></b>" on MacOS, 842"<b><tt>.</tt></b>" or "<b><tt>]</tt></b>" on OpenVMS). 843The string <b><tt>../Resource</tt></b> is replaced with a 844platform dependent equivalent. 845 846<p> 847In the case of multiple resource directories, 848the default <b><tt>ResourceFileName</tt></b> procedure retrieves either a path 849to the first avaliable resource, or if the resource is not available it 850returns a path starting with <b><tt>GenericResourceDir</tt></b>. 851Consequently Postscript installers of Postscript resources 852will overwrite an existing resource or add a new one to the first resource directory. 853 854<p> 855To look up fonts, after exhausting the search method described in <a href="#Font_lookup">the 856next section</a>, it concatenates together 857 858<ol> 859<li>the value of the system parameter 860<b><tt>FontResourceDir</tt></b> (initially 861<b><tt>/Resource/Font/</tt></b>) 862 863<li>the name of the resource font (for instance, <b><tt>Times-Roman</tt></b>) 864</ol> 865 866<p> 867Note that even although the system parameters are named "somethingDir", they 868are not just plain directory names: they have "<b><tt>/</tt></b>" on the 869end, so that they can be concatenated with the category name or font name. 870 871<h3><a name="Font_lookup"></a>Font lookup</h3> 872 873<p> 874Ghostscript has a slightly different way to find the file containing a font 875with a given name. This rule uses not only the search path defined by 876<b><tt>-I</tt></b>, <b><tt>GS_LIB</tt></b>, and 877<b><tt>GS_LIB_DEFAULT</tt></b> <a href="#Finding_files">as described 878above</a>, but also the directory that is the value of the 879<b><tt>FontResourceDir</tt></b> system parameter, and an additional list of 880directories that is the value of the <b><tt>GS_FONTPATH</tt></b> environment 881variable (or the value provided with the <b><tt>-sFONTPATH=</tt></b> switch, 882if present). 883 884<p> 885At startup time, Ghostscript reads in the <b><tt>Fontmap</tt></b> files in 886every directory on the search path (or in the list provided with the 887<b><tt>-sFONTMAP=</tt></b> switch, if present): these files are catalogs of 888fonts and the files that contain them. (See <a href="Fonts.htm#Fontmap">the 889documentation of fonts</a> for details.) Then, when Ghostscript needs to 890find a font that isn't already loaded into memory, it goes through a series 891of steps. 892 893<ul> 894 895<li> 896First, it looks up the font name in the combined Fontmaps. If there is an 897entry for the desired font name, and the file named in the entry can be 898found in some directory on the general search path (defined by 899<b><tt>-I</tt></b>, <b><tt>GS_LIB</tt></b>, and 900<b><tt>GS_LIB_DEFAULT</tt></b>), and the file is loaded successfully, and 901loading it defines a font of the desired name, that is the end of the 902process. 903 904<li> 905If this process fails at any step, Ghostscript looks for a file whose name 906is the concatenation of the value of the <b><tt>FontResourceDir</tt></b> 907system parameter and the font name, with no extension. If such a file 908exists, can be loaded, and defines a font of the desired name, that again is 909the end. The value of <b><tt>FontResourceDir</tt></b> is normally the 910string <b><tt>/Resource/Font/</tt></b>, but it can be changed with the 911<b><tt>setsystemparams</tt></b> operator: see the PostScript Language 912Reference Manual for details. 913 914<li> 915If that fails, Ghostscript then looks for a file on the general search path 916whose name is the desired font name, with no extension. If such a file 917exists, can be loaded, and defines a font of the desired name, that again is 918the end. 919 920<li> 921If that too fails, Ghostscript looks at the <b><tt>GS_FONTPATH</tt></b> 922environment variable (or the value provided with the 923<b><tt>-sFONTPATH=</tt></b> switch, if present), which is also a list of 924directories. It goes to the first directory on the list, looking for all 925files that appear to contain PostScript fonts; it then adds all those files 926and fonts to the combined Fontmaps, and starts over. 927 928<li> 929If scanning the first FONTPATH directory doesn't produce a file that 930provides the desired font, it adds the next directory on the FONTPATH list, 931and so on until either the font is defined successfully or the list is 932exhausted. 933 934<li> 935Finally, if all else fails, it will try to find a substitute for the font 936from among the standard 35 fonts. 937 938</ul> 939 940<p> 941<a href="#CIDFonts">CID fonts</a> (e.g. Chinese, Japanese and Korean) 942are found using a different method. 943 944<blockquote><table cellpadding=0 cellspacing=0> 945<tr><th colspan=3 bgcolor="#CCCC00"><hr><font size="+1">Differences between search path and font path</font><hr> 946<tr> <th>Search path 947 <td> 948 <th>Font path 949<tr> <td colspan=3><hr> 950<tr> <td><b><tt>-I</tt></b> switch 951 <td> 952 <td><b><tt>-sFONTPATH=</tt></b> switch 953<tr> <td> 954<tr> <td><b><tt>GS_LIB</tt></b> and <b><tt>GS_LIB_DEFAULT</tt></b> 955 environment variables 956 <td> 957 <td><b><tt>GS_FONTPATH</tt></b> environment variable 958<tr> <td> 959<tr> <td valign=top>Consulted first 960 <td> 961 <td valign=top>Consulted only if search path and 962 <b><tt>FontResourceDir</tt></b> don't provide the file. 963<tr> <td> 964<tr> <td valign=top>Font-name-to-file-name mapping given in Fontmap 965 files; aliases are possible, and there need not be any relation 966 between the font name in the Fontmap and the 967 <b><tt>FontName</tt></b> in the file. 968 <td> <td valign=top>Font-name-to-file-name mapping is 969 implicit -- the <b><tt>FontName</tt></b> in the file is 970 used. Aliases are not possible. 971<tr> <td> 972<tr> <td valign=top>Only fonts and files named in Fontmap are used. 973 <td> 974 <td valign=top>Every Type 1 font file in each directory is 975 available; if TrueType fonts are supported (the 976 <b><tt>ttfont.dev</tt></b> feature was included when the 977 executable was built), they are also available. 978</table></blockquote> 979 980<p> 981If you are using one of the following types of computer, you may wish to 982set the environment variable <b><tt>GS_FONTPATH</tt></b> to 983the value indicated so that Ghostscript will automatically acquire all the 984installed Type 1 (and, if supported, TrueType) fonts (but see below for 985notes on systems marked with "*"): 986 987<blockquote><table cellpadding=0 cellspacing=0> 988<tr><th colspan=5 bgcolor="#CCCC00"><hr><font size="+1">Suggested <b><tt>GS_FONTPATH</tt></b> for different systems</font><hr> 989<tr> <td> 990 <td> 991 <th align=left>System type 992 <td> 993 <th valign=bottom align=left><b><tt>GS_FONTPATH</tt></b> 994<tr> <td colspan=5><hr> 995<tr> <td> 996 <td> 997 <td valign=top>Digital Unix 998 <td> 999 <td><b><tt>/usr/lib/X11/fonts/Type1Adobe</tt></b> 1000<tr> <td> 1001 <td> 1002 <td valign=top>Ultrix 1003 <td> 1004 <td><b><tt>/usr/lib/DPS/outline/decwin</tt></b> 1005<tr> <td> 1006 <td> 1007 <td valign=top>HP-UX 9 1008 <td> 1009 <td><b><tt>/usr/lib/X11/fonts/type1.st/typefaces</tt></b> 1010<tr> <td> 1011 <td> 1012 <td valign=top>IBM AIX 1013 <td> 1014 <td><b><tt>/usr/lpp/DPS/fonts/outlines 1015 <br>/usr/lpp/X11/lib/X11/fonts/Type1 1016 <br>/usr/lpp/X11/lib/X11/fonts/Type1/DPS</tt></b> 1017<tr> <td> 1018 <td> 1019 <td valign=top>NeXT 1020 <td> 1021 <td><b><tt>/NextLibrary/Fonts/outline</tt></b> 1022<tr> <td>* 1023 <td> 1024 <td valign=top>SGI IRIX 1025 <td> 1026 <td><b><tt>/usr/lib/DPS/outline/base 1027 <br>/usr/lib/X11/fonts/Type1</tt></b> 1028<tr> <td> 1029 <td> 1030 <td valign=top>SunOS 4.x<br>(NeWSprint only) 1031 <td> 1032 <td valign=top><b><tt>newsprint_2.5/SUNWsteNP/reloc/$BASEDIR/NeWSprint/<br> small_openwin/lib/fonts</tt></b> 1033<tr> <td>** 1034 <td> 1035 <td valign=top>SunOS 4.x 1036 <td> 1037 <td><b><tt>/usr/openwin/lib/X11/fonts/Type1/outline</tt></b> 1038<tr> <td>** 1039 <td> 1040 <td valign=top>Solaris 2.x 1041 <td> 1042 <td><b><tt>/usr/openwin/lib/X11/fonts/Type1/outline</tt></b> 1043<tr> <td> 1044 <td> 1045 <td valign=top>VMS 1046 <td> 1047 <td><b><tt>SYS$COMMON:[SYSFONT.XDPS.OUTLINE]</tt></b> 1048</table> 1049 1050<hr align=left width="25%"> 1051 1052<p> 1053<b>*</b> On SGI IRIX systems, you must use <b><tt>Fontmap.SGI</tt></b> in 1054place of <b><tt>Fontmap</tt></b> or <b><tt>Fontmap.GS</tt></b>, because 1055otherwise the entries in <b><tt>Fontmap</tt></b> will take precedence over 1056the fonts in the FONTPATH directories. 1057 1058<p> 1059<b>**</b> On Solaris systems simply setting <b><tt>GS_FONTPATH</tt></b> or 1060using <b><tt>-sFONTPATH=</tt></b> may not work, because for some reason some 1061versions of Ghostscript can't seem to find any of the Type1 fonts in 1062<b><tt>/usr/openwin/lib/X11/fonts/Type1/outline</tt></b>. (It says: "15 1063files, 15 scanned, 0 new fonts". We think this problem has been fixed in 1064Ghostscript version 6.0, but we aren't sure because we've never been able to 1065reproduce it.) See <b><tt>Fontmap.Sol</tt></b> instead. Also, on Solaris 10662.x it's probably not worth your while to add Sun's fonts to your font path 1067and Fontmap. The fonts Sun distributes on Solaris 2.x in the directories 1068 1069<blockquote><b><tt> 1070 /usr/openwin/lib/X11/fonts/Type1<br> 1071 /usr/openwin/lib/X11/fonts/Type1/outline 1072</tt></b></blockquote> 1073 1074<p> 1075are already represented among the ones distributed as part of Ghostscript; 1076and on some test files, Sun's fonts have been shown to cause incorrect 1077displays with Ghostscript. 1078 1079</blockquote> 1080 1081<p> 1082These paths may not be exactly right for your installation; if the indicated 1083directory doesn't contain files whose names are familiar font names like 1084Courier and Helvetica, you may wish to ask your system administrator where 1085to find these fonts. 1086 1087<p> 1088Adobe Acrobat comes with a set of fourteen Type 1 fonts, on Unix typically 1089in a directory called ...<b><tt>/Acrobat3/Fonts</tt></b>. There is no 1090particular reason to use these instead of the corresponding fonts in the 1091Ghostscript distribution (which are of just as good quality), except to save 1092about a megabyte of disk space, but the installation documentation explains 1093how to do it <a href="Install.htm#Use_Acrobat_fonts_Unix">on Unix</a>. 1094 1095<h3><a name="CIDFonts"></a>CID fonts</h3> 1096 1097<p> 1098CID fonts are PostScript resources containing a 1099large number of glyphs (e.g. glyphs for Far East languages, 1100Chinese, Japanese and Korean). 1101Please refer to the PostScript Language Reference, 1102third edition, for details. 1103 1104<p> 1105CID font resources are a different kind of PostScript resource from fonts. 1106In particular, they cannot be used as regular fonts. 1107CID font resources must first be combined with a CMap resource, which 1108defines specific codes for glyphs, before it can be used as a font. This 1109allows the reuse of a collection of glyphs with different encodings. 1110 1111<p> 1112The simplest method to request a font composed of a CID font resource 1113and a CMap resource in a PostScript document is 1114<blockquote><b><tt> 1115/CIDFont-CMap findfont 1116</tt></b></blockquote> 1117where <b><tt>CIDFont</tt></b> is a name of any 1118CID font resource, and <b><tt>CMap</tt></b> is a name of a CMap resource 1119designed for the same character collection. The interpreter will compose 1120the font automatically from the specified CID font and CMap resources. 1121Another method is possible using the <b><tt>composefont</tt></b> operator. 1122 1123<p> 1124CID fonts must be placed in the <b><tt>/Resource/CIDFont/</tt></b> directory. 1125They are not found using <a href="#Font_lookup">Font lookup</a> 1126on the search path or font path. 1127 1128<h3><a name="CIDFontSubstitution"></a>CID font substitution</h3> 1129 1130<p> 1131 1132<p> 1133Substitution of CID font resources is controlled by the Ghostscript 1134configuration file <b><tt>lib/cidfmap</tt></b>, 1135which defines a CID font resource map. 1136The file forms a table of records, each of which should use one of two formats, 1137explained below. Users may modify <b><tt>lib/cidfmap</tt></b> to configure 1138Ghostscript for a specific need. 1139 1140<p> To substitute a CID font resource with another CID font resource, add a record like this : 1141 1142<blockquote><b><tt> 1143/Substituted /Original ; 1144</tt></b></blockquote> 1145where <b><tt>Substituted</tt></b> is a name of CID font resource being used 1146by a document, and <b><tt>Original</tt></b> is a name of an available 1147CID font resource. Please pay attention that both them must be 1148designed for same character collection. In other words, you 1149cannot substitute a Japanese CID font resource with a Korean CID font resource, 1150etc. CMap resource names must not appear in 1151<b><tt>lib/cidfmap</tt></b>. The trailing semicolon and the space before it 1152are both required. 1153 1154<p> 1155 1156To substitute (emulate) a CID font resource with a TrueType font file, add a record like this : 1157 1158<blockquote><b><tt> 1159/Substituted << keys&values >> ; 1160</tt></b></blockquote> 1161 1162Where <b><tt>keys&values</tt></b> are explained in the table below. 1163 1164<table cellpadding=0 cellspacing=10> 1165 1166<tr valign="top"> <th>Key 1167 <th>Type 1168 <th>Description 1169<tr valign="top"> <td><b><tt>/Path</tt></b> 1170 <td>string 1171 <td>A path to a TrueType font file. This must be an absolute path. 1172 If using <b><tt><a href="#Safer">-dSAFER</a></tt></b>, the directory 1173 containing the font file must be on one of the permitted paths. 1174<tr valign="top"> <td><b><tt>/FileType</tt></b> 1175 <td>name 1176 <td>Must be <b><tt>/TrueType</tt></b>. 1177<tr valign="top"> <td><b><tt>/SubfontID</tt></b> 1178 <td>integer 1179 <td>(optional) Index of the font in font collection, such as TTC. 1180 This is ignored if <b><tt>Path</tt></b> doesn't specify a collection. 1181 The first font in a collection is 0. 1182 Default value is 0. 1183<tr valign="top"> <td><b><tt>/CSI</tt></b> 1184 <td>array of 2 elements 1185 <td>(required) Information for building <b><tt>CIDSystemInfo</tt></b>. 1186 The first element is a string, which specifies <b><tt>Ordering</tt></b>. 1187 The second element is a number, which specifies <b><tt>Supplement</tt></b>. 1188</table> 1189 1190<p> 1191Currently only CIDFontType 2 can be emulated with a TrueType font. 1192The TrueType font must contain enough characters to cover an 1193Adobe character collection, which is specified in <b><tt>Ordering</tt></b> and used in documents. 1194 1195<p> 1196Examples : 1197 1198 1199<blockquote><b><tt> 1200/Ryumin-Medium /ShinGo-Bold ;<br> 1201/MS-Mincho << /FileType /TrueType /Path (C:/WINDOWS/fonts/msmincho.ttc) /SubfontID 0 /CSI [(Japan1) 3] >> ;<br> 1202/Ryumin-Light /MS-Mincho ;<br> 1203<br> 1204/Batang << /FileType /TrueType /Path (C:/WINDOWS/fonts/batang.ttc) /SubfontID 0 /CSI [(Korea1) 3] >> ;<br> 1205/Gulim << /FileType /TrueType /Path (C:/WINDOWS/fonts/gulim.ttc) /SubfontID 0 /CSI [(Korea1) 3] >> ;<br> 1206/Dotum << /FileType /TrueType /Path (C:/WINDOWS/fonts/gulim.ttc) /SubfontID 2 /CSI [(Korea1) 3] >> ;<br> 1207/HYSMyeongJo-Medium /Batang ;<br> 1208/HYRGoThic-Medium /Gulim ;<br> 1209/HYGoThic-Medium /Dotum ;<br> 1210<br> 1211/SimSun << /FileType /TrueType /Path (C:/WINDOWS/fonts/simsun.ttc) /SubfontID 0 /CSI [(GB1) 2] >> ;<br> 1212/SimHei << /FileType /TrueType /Path (C:/WINDOWS/fonts/simhei.ttf) /SubfontID 0 /CSI [(GB1) 2] >> ;<br> 1213/STSong-Light /SimSun ;<br> 1214/STHeiti-Regular /SimHei ;<br> 1215</tt></b></blockquote> 1216 1217<p> 1218Note that the font file path uses Postscript syntax for strings. 1219Due to that backslashes must be represented as a double backslash each. 1220 1221<p> 1222Note that loading truetype fonts directly from 1223<b>><tt>/Resources/CIDFont</tt></b> is no longer supported. 1224There is no reliable way to generate a character ordering for truetype 1225fonts. The 7.0x versions of Ghostscript supported this by assuming a Japanese 1226character ordering. This is replaced in the 8.0x and later releases with the more 1227general <b><tt>cidfmap</tt></b> mechanism. 1228 1229<p> 1230The PDF specification requires CID font files to be embedded, 1231however some documents omit them. As a workaround 1232the PDF interpreter applies an additional substitution method when 1233a requested CID font resource is not embedded and it is not available. 1234It takes values of the keys <b><tt>Registry</tt></b> and <b><tt>Ordering</tt></b> 1235from the <b><tt>CIDFontSystem</tt></b> dictionary, 1236and concatenates them with a dash inserted. 1237For example, if a PDF CID font resource specifies 1238<blockquote><b><tt> 1239/CIDSystemInfo << /Registry (Adobe) /Ordering (CNS1) /Supplement 1 >> 1240</tt></b></blockquote> 1241the generated subsitituite name is <b><tt>Adobe-CNS1</tt></b>. 1242The latter may look some confusing for a font name, 1243but we keep it for compatibility with older Ghostscript versions, 1244which do so due to a historical reason. 1245Add a proper record to <b><tt>lib/cidfmap</tt></b> to provide it. 1246 1247<p> 1248Please note that when a PDF font resource specifies 1249<blockquote><b><tt> 1250/Registry (Adobe) /Ordering (Identity) 1251</tt></b></blockquote> 1252there is no way to determine the language properly. 1253If the CID font file is not embedded, the <b><tt>Adobe-Identity</tt></b> 1254record depends on the document and a correct record isn't possible when 1255a document refers to multiple Far East languages. 1256In the latter case add individual records for specific CID font names used in the document. 1257 1258<p> 1259Consequently, if you want to handle any PDF document with 1260non-embedded CID fonts (which isn't a correct PDF), 1261you need to create a suitable <b><tt>lib/cidfmap</tt></b> by hand, 1262possibly a specific one for each document. 1263 1264<h3><a name="Temp_files"></a>Temporary files</h3> 1265 1266<blockquote><table cellpadding=0 cellspacing=0> 1267<tr><th colspan=5 bgcolor="#CCCC00"><hr><font size="+1">Where Ghostscript puts temporary files</font><hr> 1268<tr valign=bottom> 1269 <th align=left>Platform 1270 <td> 1271 <th align=left>Filename 1272 <td> 1273 <th align=left>Location 1274<tr> <td colspan=5><hr> 1275<tr valign=top> <td>MS Windows and OpenVMS 1276 <td> 1277 <td><b><tt>_temp_</tt></b>XX.XXX 1278 <td> 1279 <td>Current directory 1280<tr valign=top> <td>OS/2 1281 <td> 1282 <td><b><tt>gs</tt></b>XXXXXX 1283 <td> 1284 <td>Current directory 1285<tr valign=top> <td>Unix 1286 <td> 1287 <td><b><tt>gs_</tt></b>XXXXX 1288 <td> 1289 <td><b><tt>/tmp</tt></b> 1290</table></blockquote> 1291 1292<p> 1293You can change in which directory Ghostscript creates temporary files by 1294setting the <b><tt>TMPDIR</tt></b> or <b><tt>TEMP</tt></b> environment 1295variable to the name of the directory you want used. Ghostscript currently 1296doesn't do a very good job of deleting temporary files if it exits because 1297of an error; you may have to delete them manually from time to time. 1298 1299 1300<hr> 1301 1302<h2><a name="Platforms"></a>Notes on specific platforms</h2> 1303 1304<h3><a name="Unix"></a>Unix</h3> 1305 1306<p> 1307The Ghostscript distribution includes some Unix shell scripts to use with 1308Ghostscript in different environments. These are all user-contributed 1309code, so if you have questions, please contact the user identified in the 1310file, not Aladdin Enterprises or artofcode LLC. 1311 1312<dl> 1313<dt><b><tt>pv.sh</tt></b> 1314<dd>Preview a specified page of a <b><tt>dvi</tt></b> file in an X window 1315</dl> 1316 1317<dl> 1318<dt><b><tt>sysvlp.sh</tt></b> 1319<dd>System V 3.2 lp interface for parallel printer 1320</dl> 1321 1322<dl> 1323<dt><b><tt>pj-gs.sh</tt></b> 1324<dd>Printing on an H-P PaintJet under HP-UX 1325</dl> 1326 1327<dl> 1328<dt><b><tt>unix-lpr.sh</tt></b> 1329<dd>Queue filter for <b><tt>lpr</tt></b> under Unix; 1330<a href="Unix-lpr.htm">its documentation</a> is intended for system 1331administrators 1332</dl> 1333 1334<dl> 1335<dt><b><tt>lprsetup.sh</tt></b> 1336<dd>Setup for <b><tt>unix-lpr.sh</tt></b> 1337</dl> 1338 1339<hr> 1340 1341<h3><a name="VMS"></a>VMS</h3> 1342 1343<ul> 1344<li>To be able to specify switches and file names when invoking the 1345interpreter, define <b><tt>gs</tt></b> as a foreign command: 1346 1347<blockquote> 1348<b><tt>$ gs == "$</tt></b><em>disk</em><b><tt>:[</tt></b><em>directory</em><b><tt>]gs.exe</tt></b>" 1349</blockquote> 1350 1351<p> 1352where the "<em>disk</em>" and "<em>directory</em>" specify where 1353the Ghostscript executable is located. For instance, 1354 1355<blockquote><b><tt> 1356$ gs == "$dua1:[ghostscript]gs.exe" 1357</tt></b></blockquote> 1358 1359<li>On VMS systems, the last character of each "directory" name indicates 1360what sort of entity the "directory" refers to. If the "directory" name 1361ends with a colon "<b><tt>:</tt></b>", it is taken to refer to a logical 1362device, for instance 1363 1364<blockquote><b><tt> 1365$ define ghostscript_device dua1:[ghostscript_510]<br> 1366$ define gs_lib ghostscript_device: 1367</tt></b></blockquote> 1368 1369<p> 1370If the "directory" name ends with a closing square bracket 1371"<b><tt>]</tt></b>", it is taken to refer to a real directory, for instance 1372 1373<blockquote><b><tt> 1374$ define gs_lib dua1:[ghostscript] 1375</tt></b></blockquote> 1376 1377<li>Defining the logical <b><tt>GS_LIB</tt></b> 1378 1379<blockquote> 1380<b><tt>$ define gs_lib</tt></b> <em>disk</em><b><tt>:[</tt></b><em>directory</em><b><tt>]</tt></b> 1381</blockquote> 1382 1383<p> 1384allows Ghostscript to find its initialization files in the Ghostscript 1385directory even if that's not where the executable resides.<br> 1386 1387<li>Although VMS DCL itself converts unquoted parameters to upper case, C 1388programs such as Ghostscript receive their parameters through the C runtime 1389library, which forces all unquoted command-line parameters to lower case. 1390That is, with the command 1391 1392<blockquote><b><tt> 1393$ gs -Isys$login: 1394</tt></b></blockquote> 1395 1396<p> 1397Ghostscript sees the switch as <b><tt>-isys$login</tt></b>, 1398which doesn't work. To preserve the case of switches, quote them like 1399this: 1400 1401<blockquote><b><tt> 1402$ gs "-Isys$login:" 1403</tt></b></blockquote> 1404 1405<li>If you write printer output to a file with 1406<b><tt>-sOutputFile=</tt></b> and then want to print the file later, use 1407"<b><tt>PRINT/PASSALL</tt></b>". 1408</ul> 1409 1410<ul> 1411<li>PDF files (or PostScript files that use the 1412<b><tt>setfileposition</tt></b> operator) must be "stream LF" type files to 1413work properly on VMS systems. (<b><em>Note:</em></b> This definitely matters 1414if Ghostscript was compiled with DEC C; we are not sure of the situation if 1415you use <b><tt>gcc</tt></b>.) Because of this, if you transfer files by 1416FTP, you probably need to do one of these two things after the transfer: 1417 1418<ol> 1419<li>If the FTP transfer was in text (ASCII) mode: 1420 1421<blockquote> 1422<b><tt>$ convert/fdl=streamlf.fdl</tt></b> input-file output-file 1423</blockquote> 1424 1425<p> 1426where the contents of the file <b><tt>STREAMLF.FDL</tt></b> are 1427 1428<blockquote> 1429<pre>FILE 1430 ORGANIZATION sequential 1431 1432RECORD 1433 BLOCK_SPAN yes 1434 CARRIAGE_CONTROL carriage_return 1435 FORMAT stream_lf 1436</pre></blockquote> 1437 1438<li>If the FTP transfer was in binary mode: 1439 1440<blockquote><b><tt> 1441 $ set file/attribute=(rfm:stmlf) 1442</tt></b></blockquote> 1443</ol> 1444</ul> 1445 1446<h4><a name="VMS_X_Windows"></a>Using X Windows on VMS</h4> 1447 1448<p> 1449If you are using on an X Windows display, you can set it up with the node 1450name and network transport, for instance 1451 1452<blockquote><b><tt> 1453 $ set display/create/node="doof.city.com"/transport=tcpip 1454</tt></b></blockquote> 1455 1456<p> 1457and then run Ghostscript by typing <b><tt>gs</tt></b> at the command line. 1458 1459<hr> 1460 1461<h3><a name="MS_Windows"></a>MS Windows</h3> 1462 1463<p> 1464The name of the Ghostscript command line executable on MS Windows is 1465<tt>gswin32c</tt> so use this instead of the plain '<tt>gs</tt>' in 1466the quickstart examples. 1467 1468<p> 1469You must add <em>gs\</em><tt>bin</tt> and 1470<em>gs\</em><tt>lib</tt> to the <b><tt>PATH</tt></b>, where 1471<em>gs</em> is the top-level Ghostscript directory. 1472 1473<p> 1474When passing options to ghostcript through a batch file wrapper such as 1475<tt>ps2pdf.bat</tt> you need to substitute '#' for '=' as the separator 1476between options and their arguments. For example: 1477<blockquote><pre> 1478ps2pdf -sPAPERSIZE#a4 file.ps file.pdf 1479</pre></blockquote> 1480 1481Ghostscript treats '#' the same internally, and the '=' is mangled by 1482the command shell. 1483 1484<p> 1485There is also an older version for windows called just <tt>gswin32</tt> 1486that provides its own window for the interactive postscript prompt. Except 1487on Windows 3.1, gswin32c is the better option since it uses the 1488native command prompt window. 1489 1490<hr> 1491 1492<h3><a name="MS-DOS"></a>MS-DOS</h3> 1493 1494<p> 1495<strong>Note:</strong> Ghostscript is no longer supported on MS-DOS. 1496 1497<p> 1498Invoking Ghostscript from the command prompt in Windows is supported by 1499the Windows executable described above. 1500 1501<hr> 1502 1503<h3><a name="X_Windows"></a>X Windows</h3> 1504 1505<p> 1506Ghostscript looks for the following resources under the program name 1507<b><tt>ghostscript</tt></b> and class name 1508<b><tt>Ghostscript</tt></b>; the ones marked "**" are 1509calculated from display metrics: 1510 1511<blockquote><table cellpadding=0 cellspacing=0> 1512<tr><th colspan=5 bgcolor="#CCCC00"><hr><font size="+1">X Windows resources</font><hr> 1513<tr> <th align=left>Name 1514 <td> 1515 <th align=left>Class 1516 <td> 1517 <th align=left>Default 1518<tr> <td colspan=5><hr> 1519<tr> <td><b><tt>background</tt></b> 1520 <td> 1521 <td><b><tt>Background</tt></b> 1522 <td> 1523 <td><b><tt>white</tt></b> 1524<tr> <td><b><tt>foreground</tt></b> 1525 <td> 1526 <td><b><tt>Foreground</tt></b> 1527 <td> 1528 <td><b><tt>black</tt></b> 1529<tr> <td><b><tt>borderColor</tt></b> 1530 <td> 1531 <td><b><tt>BorderColor</tt></b> 1532 <td> 1533 <td><b><tt>black</tt></b> 1534<tr> <td><b><tt>borderWidth</tt></b> 1535 <td> 1536 <td><b><tt>BorderWidth</tt></b> 1537 <td> 1538 <td><b><tt>1</tt></b> 1539<tr> <td><b><tt>geometry</tt></b> 1540 <td> 1541 <td><b><tt>Geometry</tt></b> 1542 <td> 1543 <td><b><tt>NULL</tt></b> 1544<tr> <td><b><tt>xResolution</tt></b> 1545 <td> 1546 <td><b><tt>Resolution</tt></b> 1547 <td> 1548 <td>** 1549<tr> <td><b><tt>yResolution</tt></b> 1550 <td> 1551 <td><b><tt>Resolution</tt></b> 1552 <td> 1553 <td>** 1554<tr> <td><b><tt>useExternalFonts</tt></b> 1555 <td> 1556 <td><b><tt>UseExternalFonts</tt></b> 1557 <td> 1558 <td><b><tt>true</tt></b> 1559<tr> <td><b><tt>useScalableFonts</tt></b> 1560 <td> 1561 <td><b><tt>UseScalableFonts</tt></b> 1562 <td> 1563 <td><b><tt>true</tt></b> 1564<tr> <td><b><tt>logExternalFonts</tt></b> 1565 <td> 1566 <td><b><tt>LogExternalFonts</tt></b> 1567 <td> 1568 <td><b><tt>false</tt></b> 1569<tr> <td><b><tt>externalFontTolerance</tt></b> 1570 <td> 1571 <td><b><tt>ExternalFontTolerance</tt></b> 1572 <td> 1573 <td><b><tt>10.0</tt></b> 1574<tr> <td><b><tt>palette</tt></b> 1575 <td> 1576 <td><b><tt>Palette</tt></b> 1577 <td> 1578 <td><b><tt>Color</tt></b> 1579<tr> <td><b><tt>maxGrayRamp</tt></b> 1580 <td> 1581 <td><b><tt>MaxGrayRamp</tt></b> 1582 <td> 1583 <td><b><tt>128</tt></b> 1584<tr> <td><b><tt>maxRGBRamp</tt></b> 1585 <td> 1586 <td><b><tt>MaxRGBRamp</tt></b> 1587 <td> 1588 <td><b><tt>5</tt></b> 1589<tr> <td><b><tt>maxDynamicColors</tt></b> 1590 <td> 1591 <td><b><tt>MaxDynamicColors</tt></b> 1592 <td> 1593 <td><b><tt>256</tt></b> 1594<tr> <td><b><tt>useBackingPixmap</tt></b> 1595 <td> 1596 <td><b><tt>UseBackingPixmap</tt></b> 1597 <td> 1598 <td><b><tt>true</tt></b> 1599<tr> <td><b><tt>useXPutImage</tt></b> 1600 <td> 1601 <td><b><tt>UseXPutImage</tt></b> 1602 <td> 1603 <td><b><tt>true</tt></b> 1604<tr> <td><b><tt>useXSetTile</tt></b> 1605 <td> 1606 <td><b><tt>UseXSetTile</tt></b> 1607 <td> 1608 <td><b><tt>true</tt></b> 1609<tr> <td><b><tt>regularFonts</tt></b> 1610 <td> 1611 <td><b><tt>RegularFonts</tt></b> 1612 <td> 1613 <td>See "<a href="#X_fonts">X fonts</a>" 1614<tr> <td><b><tt>symbolFonts</tt></b> 1615 <td> 1616 <td><b><tt>SymbolFonts</tt></b> 1617 <td> 1618 <td>See "<a href="#X_fonts">X fonts</a>" 1619<tr> <td><b><tt>dingbatFonts</tt></b> 1620 <td> 1621 <td><b><tt>DingbatFonts</tt></b> 1622 <td> 1623 <td>See "<a href="#X_fonts">X fonts</a>" 1624</table></blockquote> 1625 1626<h4><a name="X_resources"></a>X resources</h4> 1627 1628<ul> 1629<li> 1630To set X resources, put them in a file (such as 1631<b><tt>~/.Xdefaults</tt></b> on Unix) in a form like this: 1632 1633<blockquote><table cellpadding=0 cellspacing=0> 1634<tr><td><b><tt>Ghostscript*geometry:</tt></b><td><b><tt> </tt></b><td><b><tt>595x842-0+0</tt></b> 1635<tr><td><b><tt>Ghostscript*xResolution:</tt></b><td><b><tt> </tt></b><td><b><tt>72</tt></b> 1636<tr><td><b><tt>Ghostscript*yResolution:</tt></b><td><b><tt> </tt></b><td><b><tt>72</tt></b> 1637</table></blockquote> 1638 1639<p> 1640Then merge these resources into the X server's resource database: 1641 1642<blockquote><b><tt> 1643 xrdb -merge ~/.Xdefaults 1644</tt></b></blockquote> 1645 1646<li> 1647Ghostscript doesn't look at the default system background and foreground 1648colors; if you want to change the background or foreground color, you must 1649set them explicitly for Ghostscript. This is a deliberate choice, so that 1650PostScript documents will display correctly by default -- with white as 1651white and black as black -- even if text windows use other colors. 1652 1653<li> 1654The <b><tt>geometry</tt></b> resource affects only window placement. 1655 1656<li> 1657Resolution is expressed in pixels per inch (1 inch = 25.4mm). 1658 1659<li> 1660The font tolerance gives the largest acceptable difference in height of the 1661screen font, expressed as a percentage of the height of the desired font. 1662 1663<li> 1664The <b><tt>palette</tt></b> resource can be used to restrict Ghostscript to 1665using a grayscale or monochrome palette. 1666 1667<li> 1668<b><tt>maxRGBRamp</tt></b> and 1669<b><tt>maxGrayRamp</tt></b> control the maximum number of 1670colors that ghostscript allocates ahead of time for the dither cube (ramp). 1671Ghostscript never preallocates more than half the cells in a colormap. 1672<b><tt>maxDynamicColors</tt></b> controls the maximum 1673number of colors that Ghostscript will allocate dynamically in the 1674colormap. 1675</ul> 1676 1677<h4><a name="X_server_bugs"></a>Working around bugs in X servers</h4> 1678 1679<p> 1680The "<b><tt>use</tt></b>..." resources exist primarily to work around bugs 1681in X servers. 1682 1683<ul> 1684<li> Old versions of DEC's X server (DECwindows) have bugs that 1685 require setting <b><tt>useXPutImage</tt></b> or 1686 <b><tt>useXSetTile</tt></b> to 1687 <b><tt>false</tt></b>. 1688 1689<li> Some servers do not implement backing pixmaps properly, or do not 1690 have enough memory for them. If you get strange behavior or "out 1691 of memory" messages, try setting 1692 <b><tt>useBackingPixmap</tt></b> to 1693 <b><tt>false</tt></b>. 1694 1695<li> Some servers do not implement tiling properly. This appears 1696 as broad bands of color where dither patterns should appear. If 1697 this happens, try setting 1698 <b><tt>useXSetTile</tt></b> to 1699 <b><tt>false</tt></b>. 1700 1701<li> Some servers do not implement bitmap or pixmap displaying properly. 1702 This may appear as white or black rectangles where characters 1703 should appear; or characters may appear in "inverse video" (for 1704 instance, white on a black rectangle rather than black on white). 1705 If this happens, try setting 1706 <b><tt>useXPutImage</tt></b> to 1707 <b><tt>false</tt></b>. 1708</ul> 1709 1710<h4><a name="X_fonts"></a>X fonts</h4> 1711 1712<p> 1713To use native X11 fonts, Ghostscript must map PostScript font names to the 1714XLFD font names. The resources <b><tt>regularFonts</tt></b> 1715(fonts available in standard or ISO-Latin-1 encoding), 1716<b><tt>symbolFonts</tt></b> (using Symbol encoding), and 1717<b><tt>dingbatFonts</tt></b> (using Dingbat encoding) give 1718the name mapping for different encodings. The XLFD font name in the 1719mapping must contain 7 dashes; the X driver adds the additional size and 1720encoding fields to bring the total number of dashes in the font name to 14. 1721See the appendix "<a href="#X_font_mappings">X default font mappings</a>" 1722for the full list of default mappings. 1723 1724<p> 1725Users who switch regularly between different X servers may wish to use the 1726"*" wild card in place of the foundry name 1727(<b><tt>itc</tt></b>, 1728<b><tt>monotype</tt></b>, 1729<b><tt>linotype</tt></b>, 1730<b><tt>b&h</tt></b>, or 1731<b><tt>adobe</tt></b>); users who do not switch X servers 1732should leave the explicit foundry in the name, since it speeds up access to 1733fonts. 1734 1735<p> 1736Ghostscript takes advantage of the "HP XLFD Enhancements," if available, to 1737use native X11 fonts for fonts that are anamorphically scaled, rotated, or 1738mirrored. If the changes have been installed to the X or font server, they 1739are automatically used when appropriate. 1740 1741<h4><a name="GS_fonts_as_X_fonts"></a>Using Ghostscript fonts on X displays</h4> 1742 1743<p> 1744Font files distributed with Ghostscript can be used on X Windows displays. 1745You can find full instructions in the 1746<a href="Fonts.htm#Use_gs_fonts_with_X">documentation on fonts</a>. 1747 1748<h4><a name="X_device_parameters"></a>X device parameters</h4> 1749 1750<p> 1751In addition to the device parameters recognized by <a 1752href="Language.htm#Device_parameters">all devices</a>, Ghostscript's X 1753driver provides parameters to adjust its performance. Users will rarely 1754need to modify these. Note that these are parameters to be set with the 1755<b><tt>-d</tt></b> switch in the command line (e.g., 1756<b><tt>-dMaxBitmap=10000000</tt></b>), not resources to be defined in the 1757<b><tt>~/.Xdefaults</tt></b> file. 1758 1759<dl> 1760<dt><b><tt>AlwaysUpdate <boolean></tt></b> 1761<dd>If <b><tt>true</tt></b>, the driver updates the screen after each 1762primitive drawing operation; if <b><tt>false</tt></b> (the default), the 1763driver uses an intelligent buffered updating algorithm. 1764</dl> 1765 1766<dl> 1767<dt><b><tt>MaxBitmap <integer></tt></b> 1768<dd>If the amount of memory required to hold the pixmap for the window is no 1769more than the value of <b><tt>MaxBitmap</tt></b>, the driver will draw to a 1770pixmap in Ghostscript's address space (called a "client-side pixmap") and 1771will copy it to the screen from time to time; if the amount of memory 1772required for the pixmap exceeds the value of <b><tt>MaxBitmap</tt></b>, the 1773driver will draw to a server pixmap. Using a client-side pixmap usually 1774provides better performance -- for bitmap images, possibly much better 1775performance -- but since it may require quite a lot of RAM (e.g., about 2.2 1776Mb for a 24-bit 1024x768 window), the default value of 1777<b><tt>MaxBitmap</tt></b> is 0. 1778</dl> 1779 1780<dl> 1781<dt><b><tt>MaxTempPixmap, MaxTempImage, MaxBufferedTotal, MaxBufferedArea, 1782MaxBufferedCount <integer></tt></b> 1783<dd>These control various aspects of the driver's buffering behavior. For 1784details, please consult the source file <b><tt>gdevx.h</tt></b>. 1785</dl> 1786 1787<hr> 1788 1789<h3><a name="SCO_Unix"></a>SCO Unix</h3> 1790 1791<p> 1792Because of bugs in the SCO Unix kernel, Ghostscript will not work if you 1793select direct screen output and also allow it to write messages on the 1794console. If you are using direct screen output, redirect Ghostscript's 1795terminal output to a file. 1796 1797<hr> 1798 1799<h2><a name="Options"></a>Command line options</h2> 1800 1801<p> 1802Unless otherwise noted, these switches can be used on all platforms. 1803 1804<h3><a name="General_switches"></a>General switches</h3> 1805 1806<h4><a name="Input_control"></a>Input control</h4> 1807 1808<dl> 1809<dt><b><tt>@</tt></b><em>filename</em> 1810<dd>Causes Ghostscript to read <em>filename</em> and treat its contents the 1811same as the command line. (This was intended primarily for getting around 1812DOS's 128-character limit on the length of a command line.) Switches or 1813file names in the file may be separated by any amount of white space 1814(space, tab, line break); there is no limit on the size of the file. 1815</dl> 1816 1817<dl> 1818<dt><b><tt>--</tt></b> <em>filename arg1 ...</em> 1819<br><b><tt>-+</tt></b> <em>filename arg1 ...</em> 1820<dd>Takes the next argument as a file name as usual, but takes all 1821remaining arguments (even if they have the syntactic form of switches) and 1822defines the name <b><tt>ARGUMENTS</tt></b> in userdict (not systemdict) as 1823an array of those strings, <em>before</em> running the file. When 1824Ghostscript finishes executing the file, it exits back to the shell. 1825</dl> 1826 1827<dl> 1828<dt><b><tt>-@</tt></b> <em>filename arg1 ...</em> 1829<dd>Does the same thing as <b><tt>--</tt></b> and <b><tt>-+</tt></b>, but 1830expands <b><tt>@</tt></b><em>filename</em> arguments. 1831</dl> 1832 1833<dl> 1834<dt><b><tt>-</tt></b> 1835<br><b><tt>-_</tt></b> 1836<dd>These are not really switches: they tell Ghostscript to read from 1837standard input, which is coming from a file or a pipe, 1838with or without buffering. 1839On some systems, Ghostscript may read the input one character at a time, 1840which is useful for programs such as ghostview that generate input for 1841Ghostscript dynamically and watch for some response, but can slow processing. 1842If performance is significantly slower than with a named file, 1843try '<tt>-_</tt>' which always reads the input in blocks. 1844However, '<tt>-</tt>' is equivalent on most systems. 1845</dl> 1846 1847<dl> 1848<dt><b><tt>-c</tt></b> <em>tokens ...</em> 1849<dd>Interprets arguments as PostScript code up to the next argument that 1850begins with "<b><tt>-</tt></b>" followed by a non-digit, or with 1851"<b><tt>@</tt></b>". For example, if the file <b><tt>quit.ps</tt></b> 1852contains just the word "<b><tt>quit</tt></b>", then 1853<b><tt>-c quit</tt></b> on the command line is equivalent to 1854<b><tt>quit.ps</tt></b> there. Each argument must be exactly one token, as 1855defined by the <b><tt>token</tt></b> operator. 1856</dl> 1857 1858<dl> 1859<dt><b><tt>-f</tt></b> 1860<dd>Interprets following non-switch arguments as file names to be executed 1861using the normal <b><tt>run</tt></b> command. Since this is the default 1862behavior, <b><tt>-f</tt></b> is useful only for terminating the list of 1863tokens for the <b><tt>-c</tt></b> switch. 1864</dl> 1865 1866<dl> 1867<dt><b><tt>-f</tt></b><em>filename</em> 1868<dd>Execute the given file, even if its name begins with a 1869"<b><tt>-</tt></b>" or "<b><tt>@</tt></b>". 1870</dl> 1871 1872<h4><a name="File_searching"></a>File searching</h4> 1873 1874<p> 1875Note that by "library files" here we mean all the files identified using 1876the search rule under "<a href="#Finding_files">How Ghostscript finds 1877files</a>" above: Ghostscript's own initialization files, fonts, and files 1878named on the command line. 1879 1880<dl> 1881<dt><a name="I_switch"></a><b><tt>-I</tt></b><em>directories</em> 1882<dd>Adds the designated list of directories at the head of the search path 1883for library files. 1884</dl> 1885 1886<dl> 1887<dt><a name="P_switch"></a><b><tt>-P</tt></b> 1888<dd>Makes Ghostscript look first in the current directory for library 1889files. This is currently the default. 1890</dl> 1891 1892<dl> 1893<dt><a name="P-_switch"></a><b><tt>-P-</tt></b> 1894<dd>Makes Ghostscript <b><em>not</em></b> look first in the current 1895directory for library files (unless, of course, the first explicitly 1896supplied directory is "<b><tt>.</tt></b>"). 1897</dl> 1898 1899<h4><a name="Parameters"></a>Setting parameters</h4> 1900 1901<dl> 1902<dt><b><tt>-D</tt></b><em>name</em> 1903<br><b><tt>-d</tt></b><em>name</em> 1904<dd>Define a name in systemdict with value=true. 1905</dl> 1906 1907<dl> 1908<dt><b><tt>-D</tt></b><em>name</em><b><tt>=</tt></b><em>token</em> 1909<br><b><tt>-d</tt></b><em>name</em><b><tt>=</tt></b><em>token</em> 1910<dd>Define a name in systemdict with the given definition. The token must 1911be exactly one token (as defined by the <b><tt>token</tt></b> operator) and 1912must not contain any whitespace. If the token is a non-literal name, it 1913must be true, false, or null. 1914</dl> 1915 1916<dl> 1917<dt><b><tt>-S</tt></b><em>name</em><b><tt>=</tt></b><em>string</em> 1918<br><b><tt>-s</tt></b><em>name</em><b><tt>=</tt></b><em>string</em> 1919<dd>Define a name in systemdict with a given string as value. This is 1920different from <b><tt>-d</tt></b>. For example, <b><tt>-dXYZ=35</tt></b> 1921on the command line is equivalent to the program fragment 1922 1923<blockquote><b><tt> 1924/XYZ 35 def 1925</tt></b></blockquote> 1926 1927<p> 1928whereas <b><tt>-sXYZ=35</tt></b> is equivalent to 1929 1930<blockquote><b><tt> 1931/XYZ (35) def 1932</tt></b></blockquote> 1933</dl> 1934 1935<dl> 1936<dt><b><tt>-u</tt></b><em>name</em> 1937<dd>Un-define a name, cancelling <b><tt>-d</tt></b> or <b><tt>-s</tt></b>. 1938</dl> 1939 1940<p> 1941Note that the initialization file <b><tt>gs_init.ps</tt></b> makes 1942<b><tt>systemdict</tt></b> read-only, so the values of names defined with 1943<b><tt>-D</tt></b>, <b><tt>-d</tt></b>, <b><tt>-S</tt></b>, and 1944<b><tt>-s</tt></b> cannot be changed -- although, of course, they can be 1945superseded by definitions in <b><tt>userdict</tt></b> or other dictionaries. 1946However, device parameters set this way (<b><tt>PageSize</tt></b>, 1947<b><tt>Margins</tt></b>, etc.) are <em>not</em> read-only, and <em>can</em> 1948be changed by code in PostScript files. 1949 1950<dl> 1951<dt><b><tt>-g</tt></b><em>number1</em><b><tt>x</tt></b><em>number2</em> 1952<dd>Equivalent to <b><tt>-dDEVICEWIDTH=</tt></b><em>number1</em> and 1953<b><tt>-dDEVICEHEIGHT=</tt></b><em>number2</em>, specifying the device 1954width and height in pixels for the benefit of devices such as X11 windows 1955and VESA displays that require (or allow) you to specify width and height. 1956Note that this causes documents of other sizes to be clipped, not scaled: 1957see <b><tt>-dFIXEDMEDIA</tt></b> below. 1958</dl> 1959 1960<dl> 1961<dt><a name="Resolution_switch"></a><b><tt>-r</tt></b><em>number</em> (same 1962as <b><tt>-r</tt></b><em>number</em><b><tt>x</tt></b><em>number</em>) 1963<br><b><tt>-r</tt></b><em>number1</em><b><tt>x</tt></b><em>number2</em> 1964<dd>Equivalent to <b><tt>-dDEVICEXRESOLUTION=</tt></b><em>number1</em> and 1965<b><tt>-dDEVICEYRESOLUTION=</tt></b><em>number2</em>, specifying the device 1966horizontal and vertical resolution in pixels per inch for the benefit of 1967devices such as printers that support multiple X and Y resolutions. 1968</dl> 1969 1970<h4><a name="Quiet"></a>Suppress messages</h4> 1971 1972<dl> 1973<dt><a name="Quiet"></a><b><tt>-q</tt></b> 1974<dd>Quiet startup: suppress normal startup messages, and also do the 1975equivalent of <a href="#dQUIET"><b><tt>-dQUIET</tt></b></a>. 1976</dl> 1977 1978<h3><a name="Parameter_switches"></a>Parameter switches (<b><tt>-d</tt></b> and <b><tt>-s</tt></b>)</h3> 1979 1980<p> 1981As noted above, <b><tt>-d</tt></b> and <b><tt>-s</tt></b> define initial 1982values for PostScript names. Some of these names are parameters that 1983control the interpreter or the graphics engine. You can also use 1984<b><tt>-d</tt></b> or <b><tt>-s</tt></b> to define a value for any device 1985parameter of the initial device (the one defined with 1986<b><tt>-sDEVICE=</tt></b>, or the default device if this switch is not 1987used). For example, since the <b><tt>ppmraw</tt></b> device has a numeric 1988<b><tt>GrayValues</tt></b> parameter that controls the number of bits per 1989component, <b><tt>-sDEVICE=ppmraw -dGrayValues=16</tt></b> will make this 1990the default device and set the number of bits per component to 4 (log2(16)). 1991 1992<h4><a name="Rendering_parameters"></a>Rendering parameters</h4> 1993 1994<dl> 1995<dt><b><tt>-dCOLORSCREEN 1996<br>-dCOLORSCREEN=0 1997<br>-dCOLORSCREEN=false</tt></b> 1998<dd>On high-resolution devices (at least 150 dpi resolution, or 1999<b><tt>-dDITHERPPI</tt></b> specified), <b><tt>-dCOLORSCREEN</tt></b> 2000forces the use of separate halftone screens with different angles for CMYK 2001or RGB if halftones are needed (this produces the best-quality output); 2002<b><tt>-dCOLORSCREEN=0</tt></b> uses separate screens with the same 2003frequency and angle; <b><tt>-dCOLORSCREEN=false</tt></b> forces the use of 2004a single binary screen. The default if <b><tt>COLORSCREEN</tt></b> is not 2005specified is to use separate screens with different angles if the device 2006has fewer than 5 bits per color, and a single binary screen (which is never 2007actually used under normal circumstances) on all other devices. 2008</dl> 2009 2010<dl> 2011<dt><b><tt>-dDITHERPPI=</tt></b><em>lpi</em> 2012<dd>Forces all devices to be considered high-resolution, and forces use of 2013a halftone screen or screens with <em>lpi</em> lines per inch, disregarding 2014the actual device resolution. Reasonable values for <em>lpi</em> are 2015<b><em>N</em></b>/5 to <b><em>N</em></b>/20, where <b><em>N</em></b> is the 2016resolution in dots per inch. 2017</dl> 2018 2019<dl> 2020<dt><b><tt>-dDOINTERPOLATE</tt></b> 2021<dd>Turns on image interpolation for all images, improving image quality for 2022scaled images at the expense of speed. Note that 2023<b><tt>-dNOINTERPOLATE</tt></b> overrides <b><tt>-dDOINTERPOLATE</tt></b> if 2024both are specified. 2025</dl> 2026 2027<dl> 2028<dt><b><tt>-dTextAlphaBits=</tt></b><em>n</em> 2029<dt><b><tt>-dGraphicsAlphaBits=</tt></b><em>n</em> 2030<dd>These options control the use of subsample antialiasing. Their use is highly recommended for producing high quality rasterizations. The subsampling box size <em>n</em> should be 4 for optimum output, but smaller values can be used for faster rendering. Antialiasing is enabled separately for text and graphics content. 2031Allowed values are 1, 2 or 4. 2032<p> 2033Note that because of the way antialiasing blends the edges of shapes into the background when 2034they are drawn some files that rely on joining separate filled polygons together to cover 2035an area may not render as expected with <tt>GraphicsAlphaBits</tt> at 2 or 4. If you encounter 2036strange lines within solid areas, try rendering that file again with 2037<tt>-dGraphicsAlphaBits=1</tt>. 2038</dl> 2039 2040<dl> 2041<dt><b><tt>-dAlignToPixels=</tt></b><em>n</em> 2042<dd>Chooses glyph alignent to integral pixel boundaries (if set to the value 1) 2043or to subpixels (value 0). Subpixels are a smaller raster grid 2044which is used internally for text antialiasing. 2045The number of subpixels in a pixel usually is <tt>2^TextAlphaBits</tt>, 2046but this may be automatically reduced for big characters to save space 2047in character cache. 2048 2049<p> 2050The parameter has no effect if <b><tt>-dTextAlphaBits=1</tt></b>. 2051Default value is 0. 2052 2053<p> 2054Setting <b><tt>-dAlignToPixels=0</tt></b> can improve rendering 2055of poorly hinted fonts, but may impair the appearance of well-hinted fonts. 2056</dl> 2057 2058<dl> 2059<dt><b><tt>-dGridFitTT=</tt></b><em>n</em> 2060<dd> This specifies the initial value for the implementation specific 2061user parameter <a href="Language.htm#GridFitTT">GridFitTT</a>. 2062It controls grid fitting of True Type fonts 2063(Sometimes referred to as "hinting", but strictly speaking 2064the latter is a feature of Type 1 fonts). 2065Setting this to 2 enables automatic grid fitting for True Type glyphs. 2066The value 0 disables grid fitting. The default value is 2. 2067For more information see the description of the user parameter 2068<a href="Language.htm#GridFitTT">GridFitTT</a>. 2069 2070</dl> 2071 2072<dl> 2073<dt><b><tt>-dUseCIEColor</tt></b> 2074<dd>Set UseCIEColor in the page device dictionary, remapping device-dependent 2075color values through a CIE color space. This can can improve conversion 2076of CMYK documents to RGB. 2077</dl> 2078 2079<dl> 2080<dt><b><tt>-dNOCIE</tt></b> 2081<dd>Substitutes <b><tt>DeviceGray</tt></b> and <b><tt>DeviceRGB</tt></b> 2082for CIEBasedA and CIEBasedABC color spaces respectively. Useful only on 2083very slow systems where color accuracy is less important. 2084</dl> 2085 2086<dl> 2087<dt><b><tt>-dNOSUBSTDEVICECOLORS</tt></b> 2088<dd>This switch prevents the substitution of the <b><tt>ColorSpace</tt></b> 2089resources (<b><tt>DefaultGray</tt></b>, <b><tt>DefaultRGB</tt></b>, and 2090<b><tt>DefaultCMYK</tt></b>) for the <b><tt>DeviceGray</tt></b>, 2091<b><tt>DeviceRGB</tt></b>, and <b><tt>DeviceCMYK</tt></b> color spaces. 2092This switch is primarily useful for PDF creation using the <tt><b>pdfwrite</b></tt> 2093device when retaining the color spaces from the original document is 2094important. 2095</dl> 2096 2097<dl> 2098<dt><b><tt>-dNOPSICC</tt></b> 2099<dd>Disables the automatic loading and use of an input color space that is 2100contained in a PostScript file as DSC comments starting with the %%BeginICCProfile: 2101comment. ICC profiles are sometimes embedded by applications to convey the exact 2102input color space allowing better color fidelity. Since the embedded ICC profiles 2103often use multidimensional RenderTables, color conversion may be slower than using 2104the Default color conversion invoked when the <b><tt>-dUseCIEColor</tt></b> 2105option is specified, therefore the <b><tt>-dNOPSICC</tt></b> option may result 2106in improved performance at slightly reduced color fidelity. 2107</dl> 2108 2109<dl> 2110<dt><b><tt>-dNOINTERPOLATE</tt></b> 2111<dd>Turns off image interpolation, improving performance on interpolated 2112images at the expense of image quality. <b><tt>-dNOINTERPOLATE</tt></b> 2113overrides <b><tt>-dDOINTERPOLATE</tt></b>. 2114</dl> 2115 2116<dl> 2117<dt><b><tt>-dNOTRANSPARENCY</tt></b> 2118<dd>Turns off PDF 1.4 transparency, resulting in faster (but possibly 2119incorrect) rendering of pages containing PDF 1.4 transparency and 2120blending. 2121</dl> 2122 2123<dl> 2124<dt><b><tt>-dNO_TN5044</tt></b> 2125<dd>Turns off the TN 5044 psuedo operators. These psuedo operators are not a part 2126of the official Postscript specification. However they are defined in <i>Technical 2127Note #5044 Color Separation Conventions for PostScript Language Programs</i>. 2128These psuedo operators are required for some files from QuarkXPress. However some 2129files from Corel 9 and Illustrator 88 do not operate properly if these operators 2130are present. 2131</dl> 2132 2133<dl> 2134<dt><b><tt>-dDOPS</tt></b> 2135<dd>Enables processing of DoPS directives in PDF files. DoPS has in 2136fact been deprecated for some time. Use of this option is not 2137recommended in security-conscious applications, as it increases the 2138scope for malicious code. <b><tt>-dDOPS</tt></b> has no effect on 2139processing of PostScript source files. Note: in releases 7.30 and 2140earlier, processing of DoPS was always enabled. 2141</dl> 2142 2143<h4><a name="Page_parameters"></a>Page parameters</h4> 2144 2145<dl> 2146<dt><a name="FIXEDMEDIA"></a><b><tt>-dFIXEDMEDIA</tt></b> 2147<dd>Causes the media size to be fixed after initialization, forcing pages 2148of other sizes or orientations to be clipped. This may be useful when 2149printing documents on a printer that can handle their requested paper size 2150but whose default is some other size. Note that <b><tt>-g</tt></b> 2151automatically sets <b><tt>-dFIXEDMEDIA</tt></b>, but 2152<b><tt>-sPAPERSIZE=</tt></b> does not. 2153</dl> 2154 2155<dl> 2156<dt><b><tt>-dFIXEDRESOLUTION</tt></b> 2157<dd>Causes the media resolution to be fixed similarly. <b><tt>-r</tt></b> 2158automatically sets <b><tt>-dFIXEDRESOLUTION</tt></b>. 2159</dl> 2160 2161<dl> 2162<dt><b><tt>-dORIENT1=true 2163<br>-dORIENT1=false</tt></b> 2164<dd>Defines the meaning of the 0 and 1 orientation values for the 2165setpage[params] compatibility operators. The default value of 2166<b><tt>ORIENT1</tt></b> is true (set in <b><tt>gs_init.ps</tt></b>), which 2167is the correct value for most files that use setpage[params] at all, 2168namely, files produced by badly designed applications that "know" that the 2169output will be printed on certain roll-media printers: these applications 2170use 0 to mean landscape and 1 to mean portrait. 2171<b><tt>-dORIENT1=false</tt></b> declares that 0 means portrait and 1 means 2172landscape, which is the convention used by a smaller number of files 2173produced by properly written applications. 2174</dl> 2175 2176<dl> 2177<dt><b><tt>-dDEVICEWIDTHPOINTS=</tt></b><em>w</em> 2178<br><b><tt>-dDEVICEHEIGHTPOINTS=</tt></b><em>h</em> 2179<dd>Sets the initial page width to <em>w</em> or initial page height to 2180<em>h</em> respectively, specified in 1/72" units. 2181</dl> 2182 2183<dl> 2184<dt><b><tt>-sDEFAULTPAPERSIZE=</tt></b><em>a4</em> 2185<dd> 2186This value will be used to replace the device default papersize ONLY 2187if the default papersize for the device is 'letter' or 'a4' serving 2188to insulate users of A4 or 8.5x11 from particular device defaults 2189(the collection of contributed drivers in Ghostscript vary as to 2190the default size). 2191</dd> 2192</dl> 2193 2194<h4><a name="Font_related_parameters"></a>Font-related parameters</h4> 2195 2196<dl> 2197<dt><a name="DISKFONTS"></a><b><tt>-dDISKFONTS</tt></b> 2198<dd>Causes individual character outlines to be loaded from the disk the 2199first time they are encountered. (Normally Ghostscript loads all the 2200character outlines when it loads a font.) This may allow loading more 2201fonts into memory at the expense of slower rendering. 2202<b><tt>DISKFONTS</tt></b> is effective only if the diskfont feature was 2203built into the executable; otherwise it is ignored. 2204</dl> 2205 2206<dl> 2207<dt><b><tt>-dLOCALFONTS</tt></b> 2208<dd>Causes Type 1 fonts to be loaded into the current VM -- normally local 2209VM -- instead of always being loaded into global VM. Useful only for 2210compatibility with Adobe printers for loading some obsolete fonts. 2211</dl> 2212 2213<dl> 2214<dt><b><tt>-dNOCCFONTS</tt></b> 2215<dd>Suppresses the use of fonts precompiled into the Ghostscript executable. 2216See <a href="Fonts.htm#Precompiling">"Precompiling fonts"</a> in the 2217documentation on fonts for details. This is probably useful only for 2218debugging. 2219</dl> 2220 2221<dl> 2222<dt><a name="FONTMAP_switch"></a><b><tt>-dNOFONTMAP</tt></b> 2223<dd>Suppresses the normal loading of the Fontmap file. This may be useful 2224in environments without a file system. 2225</dl> 2226 2227<dl> 2228<dt><b><tt>-dNOFONTPATH</tt></b> 2229<dd>Suppresses consultation of <b><tt>GS_FONTPATH</tt></b>. This may be 2230useful for debugging. 2231</dl> 2232 2233<dl> 2234<dt><b><tt>-dNOPLATFONTS</tt></b> 2235<dd>Disables the use of fonts supplied by the underlying platform (X 2236Windows or Microsoft Windows). This may be needed if the platform fonts 2237look undesirably different from the scalable fonts. 2238</dl> 2239 2240<dl> 2241<dt><b><tt>-sFONTMAP=</tt></b><em>filename1</em><b><tt>;</tt></b><em>filename2</em><b><tt>;</tt></b><em>...</em> 2242<dd>Specifies alternate name or names for the Fontmap file. Note that the 2243names are separated by "<b><tt>:</tt></b>" on Unix systems, by 2244"<b><tt>;</tt></b>" on MS Windows systems, and by 2245"<b><tt>,</tt></b>" on VMS systems, just as for search paths. 2246</dl> 2247 2248<dl> 2249<dt><b><tt>-sFONTPATH=</tt></b><em>dir1</em><b><tt>;</tt></b><em>dir2</em><b><tt>;</tt></b><em>...</em> 2250<dd>Specifies a list of directories that will be scanned when looking for 2251fonts not found on the search path, overriding the environment variable 2252<b><tt>GS_FONTPATH</tt></b>. 2253</dl> 2254 2255<dl> 2256<dt><b><tt>-sSUBSTFONT=</tt></b><em>fontname</em> 2257<dd>Causes the given font to be substituted for all unknown fonts, instead 2258of using the normal intelligent substitution algorithm. Also, in this 2259case, the font returned by <b><tt>findfont</tt></b> is the actual font 2260named <em>fontname</em>, not a copy of the font with its 2261<b><tt>FontName</tt></b> changed to the requested one. 2262THIS OPTION SHOULD NOT BE USED WITH HIGH LEVEL DEVICES, such as 2263<b><tt>pdfwrite</tt></b>, because it prevents such devices from 2264providing the original font names in the output document. The 2265font specified (<em>fontname</em>) will be embedded instead, 2266limiting all future users of the document to the same approximate 2267rendering. 2268</dl> 2269 2270<h4><a name="Resource_related_parameters"></a>Resource-related parameters</h4> 2271 2272<dl> 2273<dt><a name="GenericResourceDir"></a><b><tt>-sGenericResourceDir=path</tt></b> 2274<dd>Specifies a path to resource files. 2275The value is platform dependent. It must end with a directory separator. 2276<p> 2277Adobe specifies <b><tt>GenericResourceDir</tt></b> to be an absolute path 2278to a single resource directory. Ghostscript instead maintains 2279multiple resource directories and uses an extended method for finding 2280resources, which is explained in 2281<a href="PS_resources">"Finding PostScript Level 2 resources"</a>. 2282<p> 2283Due to the extended search method, Ghostscript uses <b><tt>GenericResourceDir</tt></b> 2284only as a default directory for resources being not installed. 2285Therefore <b><tt>GenericResourceDir</tt></b> may be considered as a place 2286where new resources to be installed. The default implementation of the function 2287<b><tt>ResourceFileName</tt></b> uses <b><tt>GenericResourceDir</tt></b> when 2288(1) it is an absolute path, or (2) the resource file is absent. 2289The extended search method does not call <b><tt>ResourceFileName</tt></b> . 2290<p> 2291Default value is <tt><b>(./Resource/)</b></tt> for Unix, and an equivalent one on other 2292platforms. 2293</dl> 2294 2295<dl> 2296<dt><a name="FontResourceDir"></a><b><tt>-sFontResourceDir=path</tt></b> 2297<dd>Specifies a path where font files are installed. 2298It's meaning is similar to <b><tt>GenericResourceDir</tt></b>. 2299 2300<p> 2301Default value is <tt><b>(./Font/)</b></tt> for Unix, and an equivalent one on other 2302platforms. 2303</dl> 2304 2305 2306 2307<h4><a name="Interaction_related_parameters"></a>Interaction-related parameters</h4> 2308 2309<dl> 2310<dt><b><tt>-dBATCH</tt></b> 2311<dd>Causes Ghostscript to exit after processing all files named on the 2312command line, rather than going into an interactive loop reading PostScript 2313commands. Equivalent to putting -c quit at the end of the command line. 2314</dl> 2315 2316<dl> 2317<dt><b><tt>-dNOPAGEPROMPT</tt></b> 2318<dd>Disables only the prompt, but not the pause, at the end of each page. 2319This may be useful on PC displays that get confused if a program attempts 2320to write text to the console while the display is in a graphics mode. 2321</dl> 2322 2323<dl> 2324<dt><a name="NoPause"></a><b><tt>-dNOPAUSE</tt></b> 2325<dd>Disables the prompt and pause at the end of each page. Normally one 2326should use this (along with <b><tt>-dBATCH</tt></b>) when producing output 2327on a printer or to a file; it also may be desirable for applications where 2328another program is "driving" Ghostscript. 2329</dl> 2330 2331<dl> 2332<dt><b><tt>-dNOPROMPT</tt></b> 2333<dd>Disables the prompt printed by Ghostscript when it expects interactive 2334input, as well as the end-of-page prompt (<b><tt>-dNOPAGEPROMPT</tt></b>); 2335also disables the implicit <b><tt>flushpage</tt></b> that normally occurs 2336each time Ghostscript asks for more input. This allows piping input 2337directly into Ghostscript, as long as the data doesn't refer to 2338<b><tt>currentfile</tt></b>. 2339</dl> 2340 2341<dl> 2342<dt><a name="dQUIET"></a><b><tt>-dQUIET</tt></b> 2343<dd>Suppresses routine information comments on standard output. This is 2344currently necessary when redirecting device output to standard output. 2345</dl> 2346 2347<dl> 2348<dt><b><tt>-dSHORTERRORS</tt></b> 2349<dd>Makes certain error and information messages more Adobe-compatible. 2350</dl> 2351 2352<dl> 2353<dt><b><tt>-sstdout=</tt></b><em>filename</em> 2354<dd>Redirect PostScript <b><tt>%stdout</tt></b> to a file or 2355<b><tt>stderr</tt></b>, to avoid it being mixed with device stdout. 2356To redirect stdout to stderr use <b><tt>-sstdout=%stderr</tt></b>. 2357To cancel redirection of stdout use <b><tt>-sstdout=%stdout</tt></b> 2358or <b><tt>-sstdout=-</tt></b>. 2359</dl> 2360 2361<dl> 2362<dt><b><tt>-dTTYPAUSE</tt></b> 2363<dd>Causes Ghostscript to read a character from <b><tt>/dev/tty</tt></b>, 2364rather than standard input, at the end of each page. This may be useful if 2365input is coming from a pipe. Note that <b><tt>-dTTYPAUSE</tt></b> 2366overrides <b><tt>-dNOPAUSE</tt></b>. 2367</dl> 2368 2369<h4><a name="Output_selection_parameters"></a>Device and output selection parameters</h4> 2370 2371<dl> 2372<dt><b><tt>-dNODISPLAY</tt></b> 2373<dd>Initializes Ghostscript with a null device (a device that discards the 2374output image) rather than the default device or the device selected with 2375<b><tt>-sDEVICE=</tt></b>. This is usually useful only when running 2376PostScript code whose purpose is to compute something rather than to 2377produce an output image; for instance, when converting PostScript to PDF. 2378</dl> 2379 2380<dl> 2381<dt><a name="DEVICE_switch"></a><b><tt>-sDEVICE=</tt></b><em>device</em> 2382<dd>Selects an alternate <a href="#Output_device">initial output 2383device</a>. 2384</dl> 2385 2386<dl> 2387<dt><b><tt>-sOutputFile=</tt></b><em>filename</em> 2388<dd>Selects an alternate output file (or pipe) for the initial output 2389device, as described above. 2390</dl> 2391 2392<h4><a name="EPS_parameters"></a>EPS parameters</h4> 2393 2394<dl> 2395<dt><b><tt>-dEPSCrop</tt></b> 2396<dd>Crop an EPS file to the bounding box. 2397This is useful when converting an EPS file to a bitmap. 2398</dl> 2399 2400<dl> 2401<dt><b><tt>-dEPSFitPage</tt></b> 2402<dd>Resize an EPS file to fit the page. 2403This is useful for enlarging an EPS file to fit the paper size when printing. 2404</dl> 2405 2406<dl> 2407<dt><b><tt>-dNOEPS</tt></b> 2408<dd>Prevent special processing of EPS files. 2409This is useful when EPS files have incorrect Document 2410Structuring Convention comments. 2411</dl> 2412 2413<h4><a name="Other_parameters"></a>Other parameters</h4> 2414 2415<dl> 2416<dt><b><tt>-dDELAYBIND</tt></b> 2417<dd>Causes <b><tt>bind</tt></b> to remember all its invocations, but not 2418actually execute them until the <b><tt>.bindnow</tt></b> procedure is 2419called. Useful only for certain specialized packages like 2420<b><tt>pstotext</tt></b> that redefine operators. See the documentation 2421for <a href="Language.htm#bindnow"><tt>.bindnow</tt></a> for more information 2422on using this feature. 2423</dl> 2424 2425<dl> 2426<dt><b><tt>-dDOPDFMARKS</tt></b> 2427<dd>Causes <b><tt>pdfmark</tt></b> to be called for bookmarks, 2428annotations, links and cropbox when processing PDF files. 2429Normally, <b><tt>pdfmark</tt></b> is only called for these types 2430for PostScript files or when the output device requests it 2431(e.g. pdfwrite device). 2432</dl> 2433 2434<dl> 2435<dt><b><tt>-dJOBSERVER</tt></b> 2436<dd>Define <tt>\004 (^D)</tt> to start a new encapsulated job used for 2437compatibility with Adobe PS Interpreters that ordinarily run under a job 2438server. The <b><tt>-dNOOUTERSAVE</tt></b> switch is ignored if <b><tt>-dJOBSERVER</tt></b> 2439is specified since job servers <b>always</b> execute the input PostScript 2440under a save level, although the <b><tt>exitserver</tt></b> operator can 2441be used to escape from the encapsulated job and execute as if the 2442<b><tt>-dNOOUTERSAVE</tt></b> was specified. 2443<p> 2444This also requires that the input be from stdin, otherwise an error will 2445result (<tt>Error: /invalidrestore in --restore--</tt>). 2446<p>Example usage is: 2447<pre> 2448 gs ... -dJOBSERVER - < inputfile.ps 2449 -or- 2450 cat inputfile.ps | gs ... -dJOBSERVER - 2451</pre> 2452<b>Note: </b>The <tt>^D</tt> does not result in an end-of-file action 2453on stdin as it may on some PostScript printers that rely on TBCP (Tagged 2454Binary Communication Protocol) to cause an out-of-band <tt>^D</tt> to 2455signal EOF in a stream input data. This means that direct file actions 2456on stdin such as <b><tt>flushfile</tt></b> and <b><tt>closefile</tt></b> 2457will affect processing of data beyond the <tt>^D</tt> in the stream. 2458</dl> 2459 2460<dl> 2461<dt><b><tt>-dNOBIND</tt></b> 2462<dd>Disables the <b><tt>bind</tt></b> operator. Useful only for debugging. 2463</dl> 2464 2465<dl> 2466<dt><b><tt>-dNOCACHE</tt></b> 2467<dd>Disables character caching. Useful only for debugging. 2468</dl> 2469 2470<dl> 2471<dt><b><tt>-dNOGC</tt></b> 2472<dd>Suppresses the initial automatic enabling of the garbage collector in 2473Level 2 systems. (The <b><tt>vmreclaim</tt></b> operator is not disabled.) 2474Useful only for debugging. 2475</dl> 2476 2477<dl> 2478<dt><b><tt>-dNOOUTERSAVE</tt></b> 2479<dd>Suppresses the initial save that is used for compatibility with Adobe 2480PS Interpreters that ordinarily run under a job server. If a job server is 2481going to be used to set up the outermost save level, then <b><tt>-dNOOUTERSAVE</tt></b> 2482should be used so that the restore between jobs will restore global VM as 2483expected. 2484</dl> 2485 2486<dl> 2487<dt><b><tt>-dNOSAFER</tt></b> (equivalent to <b><tt>-dDELAYSAFER</tt></b>). 2488<dd>This flag disables SAFER mode until the <b><tt>.setsafe</tt></b> 2489procedure is run. This is intended for clients or scripts that cannot 2490operate in SAFER mode. If Ghostscript is started with <b><tt>-dNOSAFER</tt></b> 2491or <b><tt>-dDELAYSAFER</tt></b>, PostScript programs are allowed to read, write, 2492rename or delete any files in the system that are not protected by operating 2493system permissions. 2494<p><b>This mode should be used with caution, and <tt>.setsafe</tt> should be 2495run prior to running any PostScript file with unknown contents.</b> 2496</dl> 2497 2498<a name="Safer"></a> 2499<dl> 2500<dt><b><tt>-dSAFER</tt></b> 2501<dd>Disables the <b><tt>deletefile</tt></b> and <b><tt>renamefile</tt></b> 2502operators, and the ability to open piped commands (<b><tt>%pipe%</tt></b><em>cmd</em>) 2503at all. Only <b><tt>%stdout</tt></b> and <b><tt>%stderr</tt></b> can be opened 2504for writing. Disables reading of files other than <b><tt>%stdin</tt></b>, 2505those given as a command line argument, or those contained on one of the paths 2506given by LIBPATH and FONTPATH and specified by the system params /FontResourceDir 2507and /GenericResourceDir. 2508<p> 2509This mode also sets the <a href="Language.htm#LockSafetyParams">.LockSafetyParams</a> 2510parameter of the default device, or the device specified with the <b><tt>-sDEVICE= </tt></b> 2511switch to protect against programs that attempt to write to files using the 2512OutputFile device parameter. Note that since the device parameters specified 2513on the command line (including OutputFile) are set prior to SAFER mode, 2514the <b><tt>-sOutputFile=...</tt></b> on the command line is unrestricted. 2515<p> 2516SAFER mode also prevents changing the /GenericResourceDir, /FontResourceDir 2517and either the /SystemParamsPassword or the /StartJobPassword. 2518<p> 2519<b>Note: </b>While SAFER mode is not the default, in a subsequent release of 2520Ghostscript, SAFER mode will be the default thus scripts or programs that need 2521to open files or set restricted parameters will require the <b><tt>-dNOSAFER</tt></b> 2522command line option. 2523<p> 2524When running -dNOSAFER it is possible to perform a <b><tt>save</tt></b>, 2525followed by <b><tt>.setsafe</tt></b>, execute a file or procedure in SAFER mode, 2526then use <b><tt>restore</tt></b> to return to NOSAFER mode. In order to prevent 2527the save object from being restored by the foreign file or procedure, the 2528<a href="Language.htm#Runandhide"><b>.runandhide</b></a> operator should 2529be used to hide the save object from the restricted procedure. 2530</dl> 2531 2532<dl> 2533<dt><b><tt>-dSTRICT</tt></b> 2534<dd>Disables as many Ghostscript extensions as feasible, to be more helpful 2535in debugging applications that produce output for Adobe and other RIPs. 2536</dl> 2537 2538<dl> 2539<dt><b><tt>-dWRITESYSTEMDICT</tt></b> 2540<dd>Leaves <b><tt>systemdict</tt></b> writable. This is necessary when 2541running special utility programs such as <b><tt>font2c</tt></b> and 2542<b><tt>pcharstr</tt></b>, which must bypass normal PostScript access 2543protection. 2544</dl> 2545 2546<hr> 2547 2548<h2><a name="Improving_performance"></a>Improving performance</h2> 2549 2550<p> 2551Ghostscript attempts to find an optimum balance between speed and memory 2552consumption, but there are some cases in which you may get a very large 2553speedup by telling Ghostscript to use more memory. 2554 2555<ul> 2556 2557<li> 2558If you are using X Windows, setting the <b><tt>-dMaxBitmap=</tt></b> 2559parameter described <a href="#X_device_parameters">above</a> may 2560dramatically improve performance on files that have a lot of bitmap images. 2561 2562<li> 2563If you are using Chinese, Japanese, or other fonts with very large character 2564sets, adding the following sequence of switches before the first file name 2565may dramatically improve performance at the cost of an additional 2-3 Mb of 2566memory: <b><tt>-c 3000000 setvmthreshold -f</tt></b>. This 2567can also be useful in processing large documents when using a high-level 2568output device (like pdfwrite) that maintains significant internal state. 2569In fact, the <a href="Language.htm#.setpdfwrite"><tt>.setpdfwrite</tt></a> 2570operator used by the ps2pdf script and others sets a vmthreshold value of 25713 MB to account for this. 2572 2573</ul> 2574 2575<h2><a name="Environment_variables"></a>Summary of environment variables</h2> 2576 2577<dl> 2578<dt><b><tt>GS</tt></b>, <b><tt>GSC</tt></b> (MS Windows only) 2579<dd>Specify the names of the Ghostscript executables. <b><tt>GS</tt></b> 2580brings up a new typein window and possibly a graphics window; 2581<b><tt>GSC</tt></b> uses the DOS console. If these are not set, 2582<b><tt>GS</tt></b> defaults to <b><tt>gswin32</tt></b>, and 2583<b><tt>GSC</tt></b> defaults to <b><tt>gswin32c</tt></b>. 2584</dl> 2585 2586<dl> 2587<dt><a href="#GS_DEVICE"><b><tt>GS_DEVICE</tt></b></a> 2588<dd>Defines the default output device. This overrides the compiled-in default, but is overridden by any commandline setting. 2589</dl> 2590 2591<dl> 2592<dt><a href="#Font_lookup"><b><tt>GS_FONTPATH</tt></b></a> 2593<dd>Specifies a list of directories to scan for fonts if a font requested 2594can't be found anywhere on the search path. 2595</dl> 2596 2597<dl> 2598<dt><a href="#Finding_files"><b><tt>GS_LIB</tt></b></a> 2599<dd>Provides a search path for initialization files and fonts. 2600</dl> 2601 2602<dl> 2603<dt><b><tt>GS_OPTIONS</tt></b> 2604<dd>Defines a list of command-line arguments to be processed before the 2605ones actually specified on the command line. For example, setting 2606<b><tt>GS_DEVICE</tt></b> to XYZ is equivalent to setting 2607<b><tt>GS_OPTIONS</tt></b> to <b><tt>-sDEVICE=XYZ</tt></b>. The contents 2608of <b><tt>GS_OPTIONS</tt></b> are not limited to switches; they may include 2609actual file names or even <a href="#Input_control">"@file" arguments</a>. 2610 2611</dl> 2612 2613<dl> 2614<dt><a href="#Temp_files"><b><tt>TEMP</tt></b>, <b><tt>TMPDIR</tt></b></a> 2615<dd>Defines a directory name for temporary files. If both 2616<b><tt>TEMP</tt></b> and <b><tt>TMPDIR</tt></b> are defined, 2617<b><tt>TMPDIR</tt></b> takes precedence. 2618</dl> 2619 2620<hr> 2621 2622<h2><a name="Debugging"></a>Debugging</h2> 2623 2624<p> 2625The information here describing is probably interesting only to developers. 2626 2627<h4><a name="Debug_switches"></a>Debug switches</h4> 2628 2629There are several debugging switches that are detected by the interpreter. 2630These switches are available whether or not Ghostscript was built with the 2631DEBUG macro defined to the compiler (refer to <a href="Make.htm#Debugging"> 2632building a debugging configuration</a>). 2633 2634<p>Previous to 8.10, there was a single DEBUG flag, enabled with <b><tt>-dDEBUG 2635</tt></b> on the command line. Now there are several debugging flags to allow 2636more selective debugging information to be printed containing only what is 2637needed to investigate particular areas. For backward compatibilty, the 2638<b><tt>-dDEBUG</tt></b> option will set all of the subset switches. 2639 2640<ul> 2641<table cellpadding=0 cellspacing=0> 2642 <tr><td><td> <td> 2643 <tr><td><b><tt>-dCCFONTDEBUG</tt></b><td><td>Compiled Fonts 2644 <tr><td><b><tt>-dCFFDEBUG</tt></b><td><td>CFF Fonts 2645 <tr><td><b><tt>-dCMAPDEBUG</tt></b><td><td>CMAP 2646 <tr><td><b><tt>-dDOCIEDEBUG</tt></b><td><td>CIE color 2647 <tr><td><b><tt>-dEPSDEBUG</tt></b><td><td>EPS handling 2648 <tr><td><b><tt>-dFAPIDEBUG</tt></b><td><td>Font API 2649 <tr><td><b><tt>-dINITDEBUG</tt></b><td><td>Initialization 2650 <tr><td><b><tt>-dPDFDEBUG</tt></b><td><td>PDF Interpreter 2651 <tr><td><b><tt>-dPDFOPTDEBUG</tt></b><td><td>PDF Optimizer (Linearizer) 2652 <tr><td><b><tt>-dPDFWRDEBUG</tt></b><td><td>PDF Writer 2653 <tr><td><b><tt>-dSETPDDEBUG</tt></b><td><td>setpagedevice 2654 <tr><td><b><tt>-dSTRESDEBUG</tt></b><td><td>Static Resources 2655 <tr><td><b><tt>-dTTFDEBUG</tt></b><td><td>TTF Fonts 2656 <tr><td><b><tt>-dVGIFDEBUG</tt></b><td><td>ViewGIF 2657 <tr><td><b><tt>-dVJPGDEBUG</tt></b><td><td>ViewJPEG 2658</table></ul> 2659 2660<p><p> 2661The <b><tt>-Z</tt></b> and <b><tt>-T</tt></b> switches apply only 2662if the interpreter was <a href="Make.htm#Debugging">built for a debugging 2663configuration</a>. In the table below, the first column is a debugging 2664switch, the second is an equivalent switch (if any) and the third is its 2665usage. 2666 2667<table cellpadding=0 cellspacing=0> 2668<tr><th colspan=5 bgcolor="#CCCC00"><hr><font size="+1">Switches used in debugging</font><hr> 2669<tr> <th align=left>Switch 2670 <td> 2671 <th align=left>Equivalent 2672 <td> 2673 <th> 2674<tr> <td colspan=5><hr> 2675<tr> <td valign=top><b><tt>-A</tt></b> 2676 <td> 2677 <td valign=top><b><tt>-Z@</tt></b> 2678 <td> 2679 <td>Fill empty storage with a distinctive bit pattern for debugging 2680 2681<tr> <td valign=top><b><tt>-A-</tt></b> 2682 <td> 2683 <td valign=top><b><tt>-Z-@</tt></b> 2684 <td> 2685 <td>Turn off <b><tt>-A</tt></b> 2686<tr> <td valign=top><b><tt>-B</tt></b><em>size</em> 2687 <td> 2688 <td> 2689 <td> 2690 <td>Run all subsequent files named on the command line (except for 2691 <b><tt>-F</tt></b>) through the run_string interface, using a 2692 buffer of <em>size</em> bytes 2693<tr> <td valign=top><b><tt>-B-</tt></b> 2694 <td> 2695 <td> 2696 <td> 2697 <td>Turn off <b><tt>-B</tt></b>: run subsequent files (except for 2698 <b><tt>-F</tt></b>) directly in the normal way 2699<tr> <td valign=top><b><tt>-E</tt></b> 2700 <td> 2701 <td valign=top><b><tt>-Z#</tt></b> 2702 <td> 2703 <td>Turn on tracing of error returns from operators 2704<tr> <td valign=top><b><tt>-E-</tt></b> 2705 <td> 2706 <td valign=top><b><tt>-Z-#</tt></b> 2707 <td> 2708 <td>Turn off <b><tt>-E</tt></b> 2709<tr> <td valign=top><b><tt>-F</tt></b><em>file</em> 2710 <td> 2711 <td> 2712 <td> 2713 <td>Execute the file with <b><tt>-B1</tt></b> temporarily in effect 2714<tr> <td valign=top><b><tt>-K</tt></b><em>n</em> 2715 <td> 2716 <td> 2717 <td> 2718 <td>Limit the total amount of memory that the interpreter can have 2719 allocated at any one time to <b><em>n</em></b>K bytes. 2720 <b><em>n</em></b> is a positive decimal integer. 2721<tr> <td valign=top><b><tt>-M</tt></b><em>n</em> 2722 <td> 2723 <td> 2724 <td> 2725 <td>Force the interpreter's allocator to acquire additional memory 2726 in units of <b><em>n</em></b>K bytes, rather than the default 2727 (currently 20K on DOS systems, 50K on Unix). <b><em>n</em></b> 2728 is a positive decimal integer, on DOS systems no greater than 2729 63. 2730<tr> <td valign=top><b><tt>-N</tt></b><em>n</em> 2731 <td> 2732 <td> 2733 <td> 2734 <td>Allocate space for <b><em>n</em></b>K names, rather than the 2735 default (normally 64K). <b><em>n</em></b> may be greater than 2736 64 only if <b><tt>EXTEND_NAMES</tt></b> was defined when the 2737 interpreter was compiled . 2738<tr> <td valign=top><b><tt>-Z</tt></b><em>xxx</em><br><b><tt>-Z-</tt></b><em>xxx</em> 2739 <td> 2740 <td> 2741 <td> 2742 <td>Turn debugging printout on (off). Each of the <em>xxx</em> 2743 characters selects an option. Case is significant: "a" and 2744 "A" have different meanings. 2745 2746<dl compact> 2747<dt><b><tt>0</tt></b><dd>garbage collector, minimal detail 2748<dt><b><tt>1</tt></b><dd>type 1 and type 42 font interpreter 2749<dt><b><tt>2</tt></b><dd>curve subdivider/rasterizer 2750<dt> <b><tt>3</tt></b><dd>curve subdivider/rasterizer, detail 2751<dt><b><tt>4</tt></b><dd>garbage collector (strings) 2752<dt> <b><tt>5</tt></b><dd>garbage collector (strings, detail) 2753<dt><b><tt>6</tt></b><dd>garbage collector (chunks, roots) 2754<dt> <b><tt>7</tt></b><dd>garbage collector (objects) 2755<dt> <b><tt>8</tt></b><dd>garbage collector (refs) 2756<dt> <b><tt>9</tt></b><dd>garbage collector (pointers) 2757<dt><b><tt>a</tt></b><dd>allocator (large blocks only) 2758<dt> <b><tt>A</tt></b><dd>allocator (all calls) 2759<dt><b><tt>b</tt></b><dd>bitmap image processor 2760<dt> <b><tt>B</tt></b><dd>bitmap images, detail 2761<dt><b><tt>c</tt></b><dd>color/halftone mapper 2762<dt><b><tt>d</tt></b><dd>dictionary put/undef 2763<dt> <b><tt>D</tt></b><dd>dictionary lookups 2764<dt><b><tt>e</tt></b><dd>external (OS-related) calls 2765<dt><b><tt>f</tt></b><dd>fill algorithm (summary) 2766<dt> <b><tt>F</tt></b><dd>fill algorithm (detail) 2767<dt><b><tt>g</tt></b><dd>gsave/grestore[all] 2768<dt><b><tt>h</tt></b><dd>halftone renderer 2769<dt> <b><tt>H</tt></b><dd>halftones, every pixel 2770<dt><b><tt>i</tt></b><dd>interpreter, just names 2771<dt> <b><tt>I</tt></b><dd>interpreter, everything 2772<dt><b><tt>j</tt></b><dd>(Japanese) composite fonts 2773<dt><b><tt>k</tt></b><dd>character cache and xfonts 2774<dt> <b><tt>K</tt></b><dd>character cache, every access 2775<dt><b><tt>l</tt></b><dd>command lists, bands 2776<dt> <b><tt>L</tt></b><dd>command lists, everything 2777<dt><b><tt>m</tt></b><dd>makefont and font cache 2778<dt><b><tt>n</tt></b><dd>name lookup (new names only) 2779<dt><b><tt>o</tt></b><dd>outliner (stroke) 2780<dt> <b><tt>O</tt></b><dd>stroke detail 2781<dt><b><tt>p</tt></b><dd>band list paths 2782<dt> <b><tt>P</tt></b><dd>all paths 2783<dt><b><tt>q</tt></b><dd>clipping 2784<dt><b><tt>r</tt></b><dd>arc renderer 2785<dt><b><tt>s</tt></b><dd>streams 2786<dt> <b><tt>S</tt></b><dd>scanner 2787<dt><b><tt>t</tt></b><dd>tiling algorithm 2788<dt><b><tt>u</tt></b><dd>undo saver (for save/restore), finalization 2789<dt> <b><tt>U</tt></b><dd>undo saver, more detail 2790<dt><b><tt>v</tt></b><dd>alpha/transparency 2791<dt> <b><tt>V</tt></b><dd>alpha/transparency, more detail 2792<dt><b><tt>w</tt></b><dd>compression encoder/decoder 2793<dt><b><tt>x</tt></b><dd>transformations 2794<dt><b><tt>y</tt></b><dd>Type 1 hints 2795<dt> <b><tt>Y</tt></b><dd>Type 1 hints, every access 2796<dt><b><tt>z</tt></b><dd>trapezoid fill 2797<dt><b><tt>#</tt></b><dd>operator error returns 2798<dt><b><tt>%</tt></b><dd>externally processed comments 2799<dt><b><tt>*</tt></b><dd>image and RasterOp parameters 2800<dt><b><tt>:</tt></b><dd>command list and allocator/time summary 2801<dt><b><tt>~</tt></b><dd>math functions and Functions 2802<dt><b><tt>'</tt></b><dd>contexts, create/destroy 2803<dt> <b><tt>"</tt></b><dd>contexts, every operation 2804<dt><b><tt>^</tt></b><dd>reference counting 2805<dt><b><tt>_</tt></b><dd>high-level output 2806<dt><b><tt>|</tt></b><dd>(reserved for experimental code) 2807</dl> 2808 2809<p> 2810The following switch affects what is printed, but does not select specific 2811items for printing: 2812 2813<dl compact> 2814<dt><b><tt>/</tt></b><dd>include file name and line number on all trace output 2815</dl> 2816 2817<p> 2818These switches select debugging options other than what should be printed: 2819 2820<dl compact> 2821<dt><b><tt>$</tt></b><dd>set unused parts of object references to 2822identifiable garbage values 2823<dt><b><tt>+</tt></b><dd>use minimum-size stack blocks 2824<dt><b><tt>,</tt></b><dd>don't use path-based banding 2825<dt><b><tt>`</tt></b><dd>don't use high-level banded images 2826<dt><b><tt>.</tt></b><dd>use small-memory table sizes even on large-memory 2827machines 2828<dt><b><tt>?</tt></b><dd>validate pointers before, during and after garbage 2829collection, also before and after save and restore; also make other 2830allocator validity checks 2831<dt><b><tt>@</tt></b><dd>fill newly allocated, garbage-collected, and freed 2832storage with a marker (a1, c1, and f1 respectively) 2833</dl> 2834 2835<p> 2836<tr> <td valign=top><b><tt>-T</tt></b><em>xxx</em><br><b><tt>-T-</tt></b><em>xxx</em> 2837 <td> 2838 <td> 2839 <td> 2840 <td>Turn <a href="#Visual_trace">Visual Trace</a> on (off). Each of the <em>xxx</em> 2841 characters selects an option. Case is significant: "f" and 2842 "F" have different meanings. 2843 2844<dl compact> 2845<dt><b><tt>f</tt></b><dd>the filling algorithm with characters 2846<dt><b><tt>F</tt></b><dd>the filling algorithm with non-character paths 2847<dt><b><tt>h</tt></b><dd>the Type 1 hinter 2848<dt><b><tt>s</tt></b><dd>the shading algorithm 2849<dt><b><tt>S</tt></b><dd>the stroking algorithm 2850</dl> 2851</table> 2852 2853<h4><a name="Visual_trace"></a>Visual Trace</h4> 2854 2855<p> 2856Visual Trace allows to view internal Ghostscript data in a graphical form 2857while execution of C code. Special 2858<a href="Lib.htm#Visual_trace">instructions</a> to be inserted into 2859C code for generating the output. Client application 2860rasterizes it into a window. 2861 2862<p> 2863Currently the rasterization is implemented for Windows only, in clients 2864gswin32.exe and gswin32c.exe. They open Visual Trace window when graphical 2865debug output appears, <b><tt>-T</tt></b> <a href="#Debug_switches">switch</a> is set, 2866and Ghostscript was <a href="Make.htm#Debugging">built</a> with DEBUG option. 2867There are two important incompletenesses of the implementation : 2868 2869<p> 28701. The graphical output uses a hardcoded scale. An advanced client 2871would provide a scale option via user interface. 2872 2873<p> 28742. Breaks are not implemented in the client. If you need a step-by-step 2875view, you should use an interactive C debugger to delay execution at breakpoints. 2876 2877<p> 2878<hr> 2879 2880<h2><a name="Known_paper_sizes"></a>Appendix: Paper sizes known to Ghostscript</h2> 2881 2882<p> 2883The paper sizes known to Ghostscript are defined at the beginning of the 2884initialization file <b><tt>gs_statd.ps</tt></b>; see the comments there for 2885more details about the definitions. The table here lists them by name and 2886size. <b><tt>gs_statd.ps</tt></b> defines their sizes exactly in points, 2887and the dimensions in inches (at 72 points per inch) and centimeters shown 2888in the table are derived from those, rounded to the nearest 0.1 unit. A 2889guide to international paper sizes can be found at 2890 2891<blockquote> 2892<a href="http://www.twics.com/~eds/paper/index.html">http://www.twics.com/~eds/paper/</a> 2893</blockquote> 2894 2895<table cellpadding=0 cellspacing=0> 2896<tr><th colspan=13 bgcolor="#CCCC00"><hr><font size="+1">Paper sizes known to Ghostscript</font><hr> 2897<tr><th colspan=13>U.S. standard 2898<tr> <td> 2899 <td> 2900 <th colspan=3>Inches 2901 <td> 2902 <th colspan=3>mm 2903 <td> 2904 <th colspan=3>Points 2905 <td> 2906 <td> 2907<tr> <th align=left>Name 2908 <td> 2909 <th> W 2910 <td>× 2911 <th> H 2912 <td> 2913 <th> W 2914 <td>× 2915 <th> H 2916 <td> 2917 <th> W 2918 <td>× 2919 <th> H 2920 <td> 2921 <td> 2922<tr> <td colspan=13><hr> 2923<tr> <td>11x17 2924 <td> <td align=right>11.0<td> <td align=right>17.0<td> <td align=right>279<td> <td align=right>432<td> <td align=right>792<td> <td align=right>1224<td> <td>11×17in portrait 2925<tr> <td>ledger 2926 <td> <td align=right>17.0<td> <td align=right>11.0<td> <td align=right>432<td> <td align=right>279<td> <td align=right>1224<td> <td align=right>792<td> <td>11×17in landscape 2927<tr> <td>legal 2928 <td> <td align=right>8.5<td> <td align=right>14.0<td> <td align=right>216<td> <td align=right>356<td> <td align=right>612<td> <td align=right>1008<td> <td> 2929<tr> <td>letter 2930 <td> <td align=right>8.5<td> <td align=right>11.0<td> <td align=right>216<td> <td align=right>279<td> <td align=right>612<td> <td align=right>792<td> <td> 2931<tr> <td>lettersmall 2932 <td> <td align=right>8.5<td> <td align=right>11.0<td> <td align=right>216<td> <td align=right>279<td> <td align=right>612<td> <td align=right>792<td> <td> 2933<tr> <td>archE 2934 <td> <td align=right>36.0<td> <td align=right>48.0<td> <td align=right>914<td> <td align=right>1219<td> <td align=right>2592<td> <td align=right>3456<td> <td> 2935<tr> <td>archD 2936 <td> <td align=right>24.0<td> <td align=right>36.0<td> <td align=right>610<td> <td align=right>914<td> <td align=right>1728<td> <td align=right>2592<td> <td> 2937<tr> <td>archC 2938 <td> <td align=right>18.0<td> <td align=right>24.0<td> <td align=right>457<td> <td align=right>610<td> <td align=right>1296<td> <td align=right>1728<td> <td> 2939<tr> <td>archB 2940 <td> <td align=right>12.0<td> <td align=right>18.0<td> <td align=right>305<td> <td align=right>457<td> <td align=right>864<td> <td align=right>1296<td> <td> 2941<tr> <td>archA 2942 <td> <td align=right>9.0<td> <td align=right>12.0<td> <td align=right>229<td> <td align=right>305<td> <td align=right>648<td> <td align=right>864<td> <td> 2943<tr> <td colspan=13><hr> 2944<tr><th colspan=13>ISO standard 2945<tr> <td colspan=13><hr> 2946<tr> <td>a0 2947 <td> <td align=right>33.1<td> <td align=right>46.8<td> <td align=right>841<td> <td align=right>1189<td> <td align=right>2384<td> <td align=right>3370<td> <td> 2948<tr> <td>a1 2949 <td> <td align=right>23.4<td> <td align=right>33.1<td> <td align=right>594<td> <td align=right>841<td> <td align=right>1684<td> <td align=right>2384<td> <td> 2950<tr> <td>a2 2951 <td> <td align=right>16.5<td> <td align=right>23.4<td> <td align=right>420<td> <td align=right>594<td> <td align=right>1191<td> <td align=right>1684<td> <td> 2952<tr> <td>a3 2953 <td> <td align=right>11.7<td> <td align=right>16.5<td> <td align=right>297<td> <td align=right>420<td> <td align=right>842<td> <td align=right>1191<td> <td> 2954<tr> <td>a4 2955 <td> <td align=right>8.3<td> <td align=right>11.7<td> <td align=right>210<td> <td align=right>297<td> <td align=right>595<td> <td align=right>842<td> <td> 2956<tr> <td>a4small 2957 <td> <td align=right>8.3<td> <td align=right>11.7<td> <td align=right>210<td> <td align=right>297<td> <td align=right>595<td> <td align=right>842<td> <td> 2958<tr> <td>a5 2959 <td> <td align=right>5.8<td> <td align=right>8.3<td> <td align=right>148<td> <td align=right>210<td> <td align=right>420<td> <td align=right>595<td> <td> 2960<tr> <td>a6 2961 <td> <td align=right>4.1<td> <td align=right>5.8<td> <td align=right>105<td> <td align=right>148<td> <td align=right>297<td> <td align=right>420<td> <td> 2962<tr> <td>a7 2963 <td> <td align=right>2.9<td> <td align=right>4.1<td> <td align=right>74<td> <td align=right>105<td> <td align=right>210<td> <td align=right>297<td> <td> 2964<tr> <td>a8 2965 <td> <td align=right>2.1<td> <td align=right>2.9<td> <td align=right>52<td> <td align=right>74<td> <td align=right>148<td> <td align=right>210<td> <td> 2966<tr> <td>a9 2967 <td> <td align=right>1.5<td> <td align=right>2.1<td> <td align=right>37<td> <td align=right>52<td> <td align=right>105<td> <td align=right>148<td> <td> 2968<tr> <td>a10 2969 <td> <td align=right>1.0<td> <td align=right>1.5<td> <td align=right>26<td> <td align=right>37<td> <td align=right>73<td> <td align=right>105<td> <td> 2970<tr> <td>isob0 2971 <td> <td align=right>39.4<td> <td align=right>55.7<td> <td align=right>1000<td> <td align=right>1414<td> <td align=right>2835<td> <td align=right>4008<td> <td> 2972<tr> <td>isob1 2973 <td> <td align=right>27.8<td> <td align=right>39.4<td> <td align=right>707<td> <td align=right>1000<td> <td align=right>2004<td> <td align=right>2835<td> <td> 2974<tr> <td>isob2 2975 <td> <td align=right>19.7<td> <td align=right>27.8<td> <td align=right>500<td> <td align=right>707<td> <td align=right>1417<td> <td align=right>2004<td> <td> 2976<tr> <td>isob3 2977 <td> <td align=right>13.9<td> <td align=right>19.7<td> <td align=right>353<td> <td align=right>500<td> <td align=right>1001<td> <td align=right>1417<td> <td> 2978<tr> <td>isob4 2979 <td> <td align=right>9.8<td> <td align=right>13.9<td> <td align=right>250<td> <td align=right>353<td> <td align=right>709<td> <td align=right>1001<td> <td> 2980<tr> <td>isob5 2981 <td> <td align=right>6.9<td> <td align=right>9.8<td> <td align=right>176<td> <td align=right>250<td> <td align=right>499<td> <td align=right>709<td> <td> 2982<tr> <td>isob6 2983 <td> <td align=right>4.9<td> <td align=right>6.9<td> <td align=right>125<td> <td align=right>176<td> <td align=right>354<td> <td align=right>499<td> <td> 2984<tr> <td>c0 2985 <td> <td align=right>36.1<td> <td align=right>51.1<td> <td align=right>917<td> <td align=right>1297<td> <td align=right>2599<td> <td align=right>3677<td> <td> 2986<tr> <td>c1 2987 <td> <td align=right>25.5<td> <td align=right>36.1<td> <td align=right>648<td> <td align=right>917<td> <td align=right>1837<td> <td align=right>2599<td> <td> 2988<tr> <td>c2 2989 <td> <td align=right>18.0<td> <td align=right>25.5<td> <td align=right>458<td> <td align=right>648<td> <td align=right>1298<td> <td align=right>1837<td> <td> 2990<tr> <td>c3 2991 <td> <td align=right>12.8<td> <td align=right>18.0<td> <td align=right>324<td> <td align=right>458<td> <td align=right>918<td> <td align=right>1298<td> <td> 2992<tr> <td>c4 2993 <td> <td align=right>9.0<td> <td align=right>12.8<td> <td align=right>229<td> <td align=right>324<td> <td align=right>649<td> <td align=right>918<td> <td> 2994<tr> <td>c5 2995 <td> <td align=right>6.4<td> <td align=right>9.0<td> <td align=right>162<td> <td align=right>229<td> <td align=right>459<td> <td align=right>649<td> <td> 2996<tr> <td>c6 2997 <td> <td align=right>4.5<td> <td align=right>6.4<td> <td align=right>114<td> <td align=right>162<td> <td align=right>323<td> <td align=right>459<td> <td> 2998<tr> <td colspan=13><hr> 2999<tr><th colspan=13>JIS standard 3000<tr> <td colspan=13><hr> 3001<tr> <td>jisb0 3002 <td> <td align=right><td> <td align=right><td> <td align=right>1030<td> <td align=right>1456<td> <td align=right><td> <td align=right><td> <td> 3003<tr> <td>jisb1 3004 <td> <td align=right><td> <td align=right><td> <td align=right>728<td> <td align=right>1030<td> <td align=right><td> <td align=right><td> <td> 3005<tr> <td>jisb2 3006 <td> <td align=right><td> <td align=right><td> <td align=right>515<td> <td align=right>728<td> <td align=right><td> <td align=right><td> <td> 3007<tr> <td>jisb3 3008 <td> <td align=right><td> <td align=right><td> <td align=right>364<td> <td align=right>515<td> <td align=right><td> <td align=right><td> <td> 3009<tr> <td>jisb4 3010 <td> <td align=right><td> <td align=right><td> <td align=right>257<td> <td align=right>364<td> <td align=right><td> <td align=right><td> <td> 3011<tr> <td>jisb5 3012 <td> <td align=right><td> <td align=right><td> <td align=right>182<td> <td align=right>257<td> <td align=right><td> <td align=right><td> <td> 3013<tr> <td>jisb6 3014 <td> <td align=right><td> <td align=right><td> <td align=right>128<td> <td align=right>182<td> <td align=right><td> <td align=right><td> <td> 3015<tr> <td colspan=13><hr> 3016<tr><th colspan=13>ISO/JIS switchable 3017<tr> <td colspan=13><hr> 3018<tr> <td>b0 (see * below) 3019<tr> <td>b1 (see * below) 3020<tr> <td>b2 (see * below) 3021<tr> <td>b3 (see * below) 3022<tr> <td>b4 (see * below) 3023<tr> <td>b5 (see * below) 3024<tr> <td colspan=13><hr> 3025<tr><th colspan=13>Other 3026<tr> <td colspan=13><hr> 3027<tr> <td>flsa 3028 <td> <td align=right>8.5<td> <td align=right>13.0<td> <td align=right>216<td> <td align=right>330<td> <td align=right>612<td> <td align=right>936<td> <td>U.S. foolscap 3029<tr> <td>flse 3030 <td> <td align=right>8.5<td> <td align=right>13.0<td> <td align=right>216<td> <td align=right>330<td> <td align=right>612<td> <td align=right>936<td> <td>European foolscap 3031<tr> <td>halfletter 3032 <td> <td align=right>5.5<td> <td align=right>8.5<td> <td align=right>140<td> <td align=right>216<td> <td align=right>396<td> <td align=right>612<td> <td> 3033</table> 3034 3035<p> 3036*<em>Note:</em> Initially the B paper sizes are the ISO sizes, e.g., 3037<b><tt>b0</tt></b> is the same as <b><tt>isob0</tt></b>. Running the file 3038<b><tt>lib/jispaper.ps</tt></b> makes the B paper sizes be the JIS sizes, 3039e.g., <b><tt>b0</tt></b> becomes the same as <b><tt>jisb0</tt></b>. 3040 3041<hr> 3042 3043<h2><a name="X_font_mappings"></a>Appendix: X default font mappings</h2> 3044 3045<h3><a name="Standard_X_server_fonts"></a>Standard X servers</h3> 3046 3047<h4><a name="X_regular_fonts"></a>Regular fonts</h4> 3048 3049<pre> AvantGarde-Book: -Adobe-ITC Avant Garde Gothic-Book-R-Normal--\n\ 3050 AvantGarde-BookOblique: -Adobe-ITC Avant Garde Gothic-Book-O-Normal--\n\ 3051 AvantGarde-Demi: -Adobe-ITC Avant Garde Gothic-Demi-R-Normal--\n\ 3052 AvantGarde-DemiOblique: -Adobe-ITC Avant Garde Gothic-Demi-O-Normal--\n\ 3053 Bookman-Demi: -Adobe-ITC Bookman-Demi-R-Normal--\n\ 3054 Bookman-DemiItalic: -Adobe-ITC Bookman-Demi-I-Normal--\n\ 3055 Bookman-Light: -Adobe-ITC Bookman-Light-R-Normal--\n\ 3056 Bookman-LightItalic: -Adobe-ITC Bookman-Light-I-Normal--\n\ 3057 Courier: -Adobe-Courier-Medium-R-Normal--\n\ 3058 Courier-Bold: -Adobe-Courier-Bold-R-Normal--\n\ 3059 Courier-BoldOblique: -Adobe-Courier-Bold-O-Normal--\n\ 3060 Courier-Oblique: -Adobe-Courier-Medium-O-Normal--\n\ 3061 Helvetica: -Adobe-Helvetica-Medium-R-Normal--\n\ 3062 Helvetica-Bold: -Adobe-Helvetica-Bold-R-Normal--\n\ 3063 Helvetica-BoldOblique: -Adobe-Helvetica-Bold-O-Normal--\n\ 3064 Helvetica-Narrow: -Adobe-Helvetica-Medium-R-Narrow--\n\ 3065 Helvetica-Narrow-Bold: -Adobe-Helvetica-Bold-R-Narrow--\n\ 3066 Helvetica-Narrow-BoldOblique: -Adobe-Helvetica-Bold-O-Narrow--\n\ 3067 Helvetica-Narrow-Oblique: -Adobe-Helvetica-Medium-O-Narrow--\n\ 3068 Helvetica-Oblique: -Adobe-Helvetica-Medium-O-Normal--\n\ 3069 NewCenturySchlbk-Bold: -Adobe-New Century Schoolbook-Bold-R-Normal--\n\ 3070 NewCenturySchlbk-BoldItalic: -Adobe-New Century Schoolbook-Bold-I-Normal--\n\ 3071 NewCenturySchlbk-Italic: -Adobe-New Century Schoolbook-Medium-I-Normal--\n\ 3072 NewCenturySchlbk-Roman: -Adobe-New Century Schoolbook-Medium-R-Normal--\n\ 3073 Palatino-Bold: -Adobe-Palatino-Bold-R-Normal--\n\ 3074 Palatino-BoldItalic: -Adobe-Palatino-Bold-I-Normal--\n\ 3075 Palatino-Italic: -Adobe-Palatino-Medium-I-Normal--\n\ 3076 Palatino-Roman: -Adobe-Palatino-Medium-R-Normal--\n\ 3077 Times-Bold: -Adobe-Times-Bold-R-Normal--\n\ 3078 Times-BoldItalic: -Adobe-Times-Bold-I-Normal--\n\ 3079 Times-Italic: -Adobe-Times-Medium-I-Normal--\n\ 3080 Times-Roman: -Adobe-Times-Medium-R-Normal--\n\ 3081 ZapfChancery-MediumItalic: -Adobe-ITC Zapf Chancery-Medium-I-Normal-- 3082</pre> 3083 3084<h4><a name="X_symbol_fonts"></a>Symbol fonts</h4> 3085 3086<pre> Symbol: -Adobe-Symbol-Medium-R-Normal-- 3087</pre> 3088 3089<h4><a name="X_dingbat_fonts"></a>Dingbat fonts</h4> 3090 3091<pre> ZapfDingbats: -Adobe-ITC Zapf Dingbats-Medium-R-Normal-- 3092</pre> 3093 3094<h3><a name="OpenWindows_fonts"></a>Sun OpenWindows</h3> 3095 3096<p> 3097For Sun's X11/NeWS one can use the OpenWindows scalable fonts instead, 3098which gives good output for any point size. In this environment, the 3099relevant section of the resource file should look like this: 3100 3101<pre>Ghostscript.regularFonts: \ 3102 AvantGarde-Book: -itc-avantgarde-book-r-normal-- \n\ 3103 AvantGarde-BookOblique: -itc-avantgarde-book-o-normal-- \n\ 3104 AvantGarde-Demi: -itc-avantgarde-demi-r-normal-- \n\ 3105 AvantGarde-DemiOblique: -itc-avantgarde-demi-o-normal-- \n\ 3106 Bembo: -monotype-bembo-medium-r-normal-- \n\ 3107 Bembo-Bold: -monotype-bembo-bold-r-normal-- \n\ 3108 Bembo-BoldItalic: -monotype-bembo-bold-i-normal-- \n\ 3109 Bembo-Italic: -monotype-bembo-medium-i-normal-- \n\ 3110 Bookman-Demi: -itc-bookman-demi-r-normal-- \n\ 3111 Bookman-DemiItalic: -itc-bookman-demi-i-normal-- \n\ 3112 Bookman-Light: -itc-bookman-light-r-normal-- \n\ 3113 Bookman-LightItalic: -itc-bookman-light-i-normal-- \n\ 3114 Courier: -itc-courier-medium-r-normal-- \n\ 3115 Courier-Bold: -itc-courier-bold-r-normal-- \n\ 3116 Courier-BoldOblique: -itc-courier-bold-o-normal-- \n\ 3117 Courier-Oblique: -itc-courier-medium-o-normal-- \n\ 3118 GillSans: -monotype-gill-medium-r-normal-sans- \n\ 3119 GillSans-Bold: -monotype-gill-bold-r-normal-sans- \n\ 3120 GillSans-BoldItalic: -monotype-gill-bold-i-normal-sans- \n\ 3121 GillSans-Italic: -monotype-gill-normal-i-normal-sans- \n\ 3122 Helvetica: -linotype-helvetica-medium-r-normal-- \n\ 3123 Helvetica-Bold: -linotype-helvetica-bold-r-normal-- \n\ 3124 Helvetica-BoldOblique: -linotype-helvetica-bold-o-normal-- \n\ 3125 Helvetica-Narrow: -linotype-helvetica-medium-r-narrow-- \n\ 3126 Helvetica-Narrow-Bold: -linotype-helvetica-bold-r-narrow-- \n\ 3127 Helvetica-Narrow-BoldOblique: -linotype-helvetica-bold-o-narrow-- \n\ 3128 Helvetica-Narrow-Oblique: -linotype-helvetica-medium-o-narrow-- \n\ 3129 Helvetica-Oblique: -linotype-helvetica-medium-o-normal-- \n\ 3130 LucidaBright: -b&h-lucidabright-medium-r-normal-- \n\ 3131 LucidaBright-Demi: -b&h-lucidabright-demibold-r-normal-- \n\ 3132 LucidaBright-DemiItalic: -b&h-lucidabright-demibold-i-normal-- \n\ 3133 LucidaBright-Italic: -b&h-lucidabright-medium-i-normal-- \n\ 3134 LucidaSans: -b&h-lucida-medium-r-normal-sans- \n\ 3135 LucidaSans-Bold: -b&h-lucida-bold-r-normal-sans- \n\ 3136 LucidaSans-BoldItalic: -b&h-lucida-bold-i-normal-sans- \n\ 3137 LucidaSans-Italic: -b&h-lucida-medium-i-normal-sans- \n\ 3138 LucidaSans-Typewriter: -b&h-lucidatypewriter-medium-r-normal-sans- \n\ 3139 LucidaSans-TypewriterBold: -b&h-lucidatypewriter-bold-r-normal-sans- \n\ 3140 NewCenturySchlbk-BoldItalic: -linotype-new century schoolbook-bold-i-normal-- \n\ 3141 NewCenturySchlbk-Bold: -linotype-new century schoolbook-bold-r-normal-- \n\ 3142 NewCenturySchlbk-Italic: -linotype-new century schoolbook-medium-i-normal-- \n\ 3143 NewCenturySchlbk-Roman: -linotype-new century schoolbook-medium-r-normal-- \n\ 3144 Palatino-Bold: -linotype-palatino-bold-r-normal-- \n\ 3145 Palatino-BoldItalic: -linotype-palatino-bold-i-normal-- \n\ 3146 Palatino-Italic: -linotype-palatino-medium-i-normal-- \n\ 3147 Palatino-Roman: -linotype-palatino-medium-r-normal-- \n\ 3148 Rockwell: -monotype-rockwell-medium-r-normal-- \n\ 3149 Rockwell-Bold: -monotype-rockwell-bold-r-normal-- \n\ 3150 Rockwell-BoldItalic: -monotype-rockwell-bold-i-normal-- \n\ 3151 Rockwell-Italic: -monotype-rockwell-medium-i-normal-- \n\ 3152 Times-Bold: -linotype-times-bold-r-normal-- \n\ 3153 Times-BoldItalic: -linotype-times-bold-i-normal-- \n\ 3154 Times-Italic: -linotype-times-medium-i-normal-- \n\ 3155 Times-Roman: -linotype-times-medium-r-normal-- \n\ 3156 Utopia-Bold: -adobe-utopia-bold-r-normal-- \n\ 3157 Utopia-BoldItalic: -adobe-utopia-bold-i-normal-- \n\ 3158 Utopia-Italic: -adobe-utopia-regular-i-normal-- \n\ 3159 Utopia-Regular: -adobe-utopia-regular-r-normal-- \n\ 3160 ZapfChancery-MediumItalic: -itc-zapfchancery-medium-i-normal-- \n 3161Ghostscript.dingbatFonts: \ 3162 ZapfDingbats: -itc-zapfdingbats-medium-r-normal-- 3163Ghostscript.symbolFonts: \ 3164 Symbol: --symbol-medium-r-normal-- 3165</pre> 3166 3167 3168<h2><a name="FAPI_run"></a>Running Ghostscript with 3d party font renderers</h2> 3169 3170<p> 3171Font API (FAPI) is a new feature which allows to attach 3d party font renderers to Ghostscript. 3172This section explains how to run Ghostscript with 3d party font renderers, 3173such as Agfa UFST or Free Type. 3174 3175<p> 3176<em>Note: To run Ghostscript with Agfa UFST you need a license from Agfa. 3177Please ignore issues about UFST if you haven't got it. 3178</em> 3179 3180<p> 3181<em> 3182Important note: Third-party font renderers are incompatible 3183with devices that can embed fonts in their output (such as pdfwrite), 3184because such renderers store fonts in a form from which Ghostscript cannot 3185get the necessary information for embedding. Ghostscript disables such 3186renderers when such device is being used. In particular, UFST and Free Type are 3187disabled while running Ghostscript with the <b><tt>pdfwrite</tt></b> 3188device. 3189</em> 3190 3191<p> 3192To run Ghostscript with Free Type, you first need to build Ghostscript 3193with the Free Type bridge. Refer <a href="Make.htm#FT_build">How to build Ghostscript with Free Type</a>. 3194<p> 3195To run Ghostscript with UFST, you first need to build Ghostscript 3196with the UFST bridge. Refer <a href="Make.htm#UFST_build">How to build Ghostscript with UFST</a>. 3197Both bridges may run together. 3198<p> 3199 3200<p> 3201Then you need to obtain the Decoding resources from Artifex Software Inc. and install them with Ghostscript. 3202Just copy the files to the <b><tt>Resource/Decoding</tt></b> directory (or to the subdirectory 3203<b><tt>Decoding</tt></b> of a directory, which is specified in <b><tt>GenericResourcePath</tt></b>). 3204 3205 3206<p> 3207There are 2 ways to handle fonts with a 3d party font renderer (FAPI). First, you can substitute 3208any FAPI-handled font to a PostScript font, using special map files. 3209Second, you can redirect PostScript fonts to FAPI, setting 3210entries in <b><tt>lib/FAPIconfig</tt></b> file. 3211 3212<p> 3213The file <b><tt>lib/FAPIfontmap</tt></b> defines a map table for FAPI-handled fonts. 3214The format of <b><tt>lib/FAPIfontmap</tt></b> is explained below. 3215 3216<p> 3217Font files being handled with FAPI may reside in any directory in your hard disk. 3218Paths to them to be specified in <b><tt>lib/FAPIfontmap</tt></b>. The path may be either 3219absolute or relative. Relative ones are being resolved from the path, 3220which is specified in <b><tt>lib/FAPIconfig</tt></b> file. 3221 3222<p> 3223The file <b><tt>lib/FAPIfontmap</tt></b> is actually special PostScript code. 3224It contains records for each font being rendered with FAPI. 3225Records must end with semicolon. Each record is a pair. 3226The first element of the pair is the font name (the name that PostScript 3227documents use to access the font, which may differ 3228from real name of the font which the font file defines). 3229The second element is a dictionary with entries : 3230 3231<table cellpadding=0 cellspacing=10> 3232 3233<tr> <th>Key 3234 <th>Type 3235 <th>Description 3236<tr> <td>Path 3237 <td>string 3238 <td>Absolute path to font file, or relative path to font file from the FontPath value, 3239 being specified in <b><tt>lib/FAPIconfig</tt></b>. 3240<tr> <td>FontType 3241 <td>interger 3242 <td>PostScript type for this font. Only 1 and 42 are currently allowed. 3243 Note that this is unrelated to the real type of the font file - 3244 the bridge will perform a format conversion. 3245<tr> <td>FAPI 3246 <td>name 3247 <td>Name of the renderer to be used with the font. 3248 Only <b><tt>/AgfaUFST</tt></b> and <b><tt>/FreeType</tt></b> are now allowed. 3249<tr> <td>SubfontId 3250 <td>integer 3251 <td>(optional) Index of the font in font collection, such as FCO or TTC. 3252 It is being ignored if Path doesn't specify a collection. 3253 Note that Free Type can't handle FCO. 3254 Default value is 0. 3255<tr> <td>Decoding 3256 <td>name 3257 <td>(optional) The name of a Decoding resource to be used with the font. 3258 If specified, <b><tt>lib/xlatmap</tt></b> (see below) doesn't work for this font. 3259</table> 3260 3261<p> 3262Example of FAPI font map record : 3263<blockquote> 3264<b><tt> 3265/FCO1 << /Path (/AFPL/Agfa/fontdata/MTFONTS/PCLPS3/MT1/PCLP3__F.fco) /FontType 1 /FAPI /AgfaUFST >> ; 3266</tt></b> 3267</blockquote> 3268 3269<p> 3270Note that <b><tt>lib/FAPIfontmap</tt></b> specifies only instances of 3271Font category. CID fonts to be listed in another map file. 3272 3273<p> 3274The file <b><tt>lib/FAPIcidfmap</tt></b> defines a mapping table for 3275CIDFont resources. It contains records for each CID font being rendered with FAPI. 3276The format is similar to <b><tt>lib/FAPIfontmap</tt></b>, 3277but dictionaries must contain few different entries : 3278 3279<table cellpadding=0 cellspacing=10> 3280 3281<tr> <th>Key 3282 <th>Type 3283 <th>Description 3284<tr> <td>Path 3285 <td>string 3286 <td>Absolute path to font file, or relative path to font file from the CIDFontPath value, 3287 being specified in <b><tt>lib/FAPIconfig</tt></b>. 3288<tr> <td>CIDFontType 3289 <td>interger 3290 <td>PostScript type for this CID font. Only 0, 1 and 2 are currently allowed. 3291 Note that this is unrelated to the real type of the font file - 3292 the bridge will perform format conversion. 3293<tr> <td>FAPI 3294 <td>name 3295 <td>Name of the renderer to be used with the font. 3296 Only <b><tt>/AgfaUFST</tt></b> and <b><tt>/FreeType</tt></b> are now allowed. 3297<tr> <td>SubfontId 3298 <td>integer 3299 <td>(optional) Index of the font in font collection, such as FCO or TTC. 3300 It is being ignored if Path doesn't specify a collection. 3301 Default value is 0. 3302<tr> <td>CSI 3303 <td>array of 2 elements 3304 <td>(required) Information for building <b><tt>CIDSystemInfo</tt></b>. 3305 The first element is a string, which specifies <b><tt>Ordering</tt></b>. 3306 The second element is a number, which specifies <b><tt>Supplement</tt></b>. 3307</table> 3308 3309<p> 3310Example of FAPI CID font map record : 3311<blockquote> 3312<b><tt> 3313/HeiseiKakuGo-W5 << /Path (/WIN2000/Fonts/PMINGLIU.TTF) /CIDFontType 0 /FAPI /AgfaUFST /CSI [(Japan1) 2] >> ; 3314</tt></b> 3315</blockquote> 3316 3317 3318 3319 3320<p> 3321The control file <b><tt>lib/FAPIconfig</tt></b> defines 4 entries : 3322 3323<table cellpadding=0 cellspacing=10> 3324<tr> <th>Key 3325 <th>Type 3326 <th>Description 3327<tr> <td>FontPath 3328 <td>string 3329 <td>Absolute path to a directory, which contains fonts. Used to resolve 3330 relative paths in <b><tt>lib/FAPIfontmap</tt></b>. 3331<tr> <td>CIDFontPath 3332 <td>string 3333 <td>Absolute path to a directory, which contains fonts to substitute to CID fonts. 3334 Used to resolve relative paths in <b><tt>lib/FAPIcidfmap</tt></b>. 3335 It may be same or different than FontPath. 3336<tr> <td>HookDiskFonts 3337 <td>array of integers. 3338 <td>List of PS font types to be handled with FAPI. 3339 This controls other fonts that ones listed in <b><tt>lib/FAPIfontmap</tt></b> 3340 and <b><tt>lib/FAPIcidfmap</tt></b> - such ones are PS fonts installed to 3341 Ghostscript with <b><tt>lib/fontmap</tt></b> or with <b><tt>GS_FONTPATH</tt></b>, 3342 or regular CID font resources. Unlisted font types will be 3343 rendered with the native Ghostscript font renderer. 3344 Only allowed values now are 1,9,11,42. Note that 9 and 11 3345 correspond to CIDFontType 0 and 2. 3346<tr> <td>HookEmbeddedFonts 3347 <td>array of integers. 3348 <td>List of PS font types to be handled with FAPI. 3349 This controls fonts being embedded into a document - 3350 either fonts or CID font resources. Unlisted font types will be 3351 rendered with the native Ghostscript font renderer. 3352 Only allowed values now are 1,9,11,42. Note that 9 and 11 3353 correspond to CIDFontType 0 and 2. 3354 3355</table> 3356 3357<p> 3358You may need to customize the file <b><tt>lib/xlatmap</tt></b>. Follow instructions in it. 3359 3360<p> 3361Note that UFST and Free Type cannot handle some Ghostscript fonts because 3362they does not include a PostScript interpreter and therefore has stronger restrictions on 3363font formats than Ghostscript itself does. 3364If their font types are listed in HookDiskFonts or in HookEmbeddedFonts, 3365Ghostscript interpret them as PS files, then serializes font data into a RAM buffer and 3366passes it to FAPI as PCLEOs. 3367 3368<p> 3369 3370 3371 3372<!-- [2.0 end contents] ==================================================== --> 3373 3374<!-- [3.0 begin visible trailer] =========================================== --> 3375<hr> 3376 3377<p> 3378<small>Copyright © 1996-2002 artofcode LLC. All rights reserved.</small> 3379 3380<p> 3381This software is provided AS-IS with no warranty, either express or 3382implied. 3383 3384This software is distributed under license and may not be copied, 3385modified or distributed except as expressly authorized under the terms 3386of the license contained in the file LICENSE in this distribution. 3387 3388For more information about licensing, please refer to 3389http://www.ghostscript.com/licensing/. For information on 3390commercial licensing, go to http://www.artifex.com/licensing/ or 3391contact Artifex Software, Inc., 101 Lucas Valley Road #110, 3392San Rafael, CA 94903, U.S.A., +1(415)492-9861. 3393 3394<p> 3395<small>Ghostscript version 8.53, 20 October 2005 3396 3397<!-- [3.0 end visible trailer] ============================================= --> 3398 3399</small></h3></body> 3400</html> 3401
