sys/man/1/gs

   1 .TH GS 1
   2 .\" This file is an edited version of /sys/src/cmd/gs/man/gs.1, to
   3 .\" document the local installation and remove needless background.
   4 .de TQ
   5 .br
   6 .ns
   7 .TP \\$1
   8 ..
   9 .SH NAME
  10 gs \- Aladdin Ghostscript (PostScript and PDF language interpreter)
  11 .SH SYNOPSIS
  12 .B gs
  13 [
  14 .I options
  15 ] [
  16 .I files
  17 ] ...
  18 .br
  19 .SH DESCRIPTION
  20 Ghostscript is a programming language similar to Adobe Systems'
  21 PostScript and PDF languages, which are in turn similar to Forth.
  22 .I Gs
  23 reads
  24 .I files
  25 in sequence and executes them as Ghostscript programs.
  26 After doing this, it reads further input from the standard input.
  27 If the
  28 .I file
  29 .B -
  30 is named, however, it represents the standard input, which is read
  31 in order and not after the files on the command line.
  32 Each line is interpreted separately.
  33 The `quit' command, or end-of-file, exits the interpreter.
  34 .PP
  35 The interpreter recognizes several switches described below, which may appear
  36 anywhere in the command line and apply to all files thereafter.
  37 .PP
  38 The
  39 .B -h
  40 or
  41 .B -?
  42 options give help and list the available devices; the default is
  43 .BR plan9 ,
  44 which produces compressed image files suitable for viewing with
  45 .IR page (1)
  46 (but note that
  47 .IR page (1)
  48 will invoke
  49 .I gs
  50 automatically; see its manual).
  51 .PP
  52 Ghostscript may be built with multiple output devices.  Ghostscript
  53 normally opens the first one and directs output to it.  To use device xyz
  54 as the initial output device, include the switch
  55 .EX
  56         -sDEVICE=xyz
  57 .EE
  58 in the command line.  This switch must precede the first PostScript
  59 file and only its first invocation has any effect.
  60 Output devices can also be selected by the word
  61 .B selectdevice
  62 in the input language, or by setting the environment variable
  63 .BR GS_DEVICE .
  64 The order of precedence for
  65 these alternatives, highest to lowest, is:
  66 .EX
  67         selectdevice
  68         \f1(command line)\fP
  69         GS_DEVICE
  70         plan9
  71 .EE
  72 .PP
  73 Normally, output goes
  74 directly to a scratch file.
  75 To send the output to a series of files
  76 .BR foo1.xyz ,
  77 .BR foo2.xyz ,
  78 etc., use the switch
  79 .EX
  80         -sOutputFile=foo%d.xyz
  81 .EE
  82 The %d may be any
  83 .I printf
  84 (see
  85 .IR fprintf (2))
  86 format specification.  Each file will receive one page of output.
  87 If the file name begins with a pipe character,
  88 the output will be sent as standard input to the following pipeline.
  89 For example,
  90 .EX
  91         -sOutputFile=|lp
  92 .EE
  93 Specifying the file
  94 .B -
  95 will send the files to standard output; this also requires enabling the
  96 .B -q
  97 option.
  98 .SS "Initialization files"
  99 When looking for the initialization files
 100 .RB ( gs_*.ps ),
 101 the files related
 102 to fonts, or the file for the
 103 .B run
 104 operator, Ghostscript first looks for the file (if
 105 it doesn't start with a slash) in the current directory, then in these
 106 directories in the following order:
 107 .TP
 108 1.
 109 Any directories specified by
 110 .B -I
 111 switches in the command
 112 line (see below);
 113 .TP
 114 2.
 115 Any directories specified by the
 116 .B GS_LIB
 117 environment variable;
 118 .TP
 119 3.
 120 The directories
 121 .BR /sys/lib/ghostscript ,
 122 .BR /sys/lib/ghostscript/font ,
 123 and
 124 .BR /sys/lib/postscript/font .
 125 .PP
 126 The
 127 .B GS_LIB
 128 or
 129 .B -I
 130 parameters may be
 131 a single directory or a colon-separated list.
 132 .SS Options
 133 .TP
 134 .BI -- " filename arg1 ..."
 135 Take the next argument as a file name as usual, but take all
 136 remaining arguments (even if they have the syntactic form of switches)
 137 and define the name ARGUMENTS in userdict (not systemdict) as an
 138 array of those strings,
 139 .I before
 140 running the file.  When Ghostscript
 141 finishes executing the file, it exits back to the shell.
 142 .TP
 143 .BI -D name = token
 144 .TQ
 145 .BI -d name = token
 146 Define a name in systemdict with the given definition.  The token must
 147 be exactly one token (as defined by the `token' operator) and must not
 148 contain any white space.
 149 .TP
 150 .BI -D name
 151 .TQ
 152 .BI -d name
 153 Define a name in systemdict with value=null.
 154 .TP
 155 .BI -S name = string
 156 .TQ
 157 .BI -s name = string
 158 Define a name in systemdict with a given string as value.  This is
 159 different from
 160 .BR  -d .
 161 For example,
 162 .B -dname=35
 163 is equivalent to the
 164 program fragment
 165 .EX
 166         /name 35 def
 167 .EE
 168 whereas
 169 .B -sname=35
 170 is equivalent to
 171 .EX
 172         /name (35) def
 173 .EE
 174 .TP
 175 .B -q
 176 Quiet startup: suppress normal startup messages, and also do the
 177 equivalent of
 178 .BR -dQUIET .
 179 .TP
 180 .BI -g number1 x number2
 181 Equivalent to
 182 .BI -dDEVICEWIDTH= number1
 183 and
 184 .BI -dDEVICEHEIGHT= number2\f1.
 185 This is for the benefit of devices, such as windows,
 186 that allow width and height to be specified.
 187 .TP
 188 .BI -r number
 189 .TQ
 190 .BI -r number1 x number2
 191 Equivalent to
 192 .BI -dDEVICEXRESOLUTION= number1
 193 and
 194 \fL-dDEVICE\%YRESOLUTION= \f2\%number2\f1.
 195 This is for the benefit of devices, such as printers,
 196 that support multiple X and Y resolutions.
 197 If only one number is given, it is used for both X and Y resolutions.
 198 .TP
 199 .BI -I directories
 200 Adds the designated list of directories at the head of the
 201 search path for library files.
 202 .PP
 203 Note that gs_init.ps makes systemdict read-only, so the values of names
 204 defined with -D/d/S/s cannot be changed (although, of course, they can be
 205 superseded by definitions in userdict or other dictionaries.)
 206 .SS "Special names"
 207 .TP
 208 .B -dBATCH
 209 Exit after the last file has been processed.
 210 This is equivalent to listing
 211 .I quit.ps
 212 at the end of the list of files.
 213 .TP
 214 .B -dDISKFONTS
 215 Causes individual character outlines to be loaded from the disk
 216 the first time they are encountered.  (Normally Ghostscript loads all the
 217 character outlines when it loads a font.)  This may allow loading more
 218 fonts into RAM, at the expense of slower rendering.
 219 .TP
 220 .B -dNOCACHE
 221 Disables character caching.  Only useful for debugging.
 222 .TP
 223 .B -dNOBIND
 224 Disables the `bind' operator.  Only useful for debugging.
 225 .TP
 226 .B -dNODISPLAY
 227 Suppresses the normal initialization of the output device.
 228 This may be useful when debugging.
 229 .TP
 230 .B -dNOPAUSE
 231 Disables the prompt and pause at the end of each page.
 232 This may be desirable for applications where another program
 233 (e.g.
 234 .IR page (1))
 235 is
 236 `driving' Ghostscript.
 237 .TP
 238 .B -dSAFER
 239 Disables the
 240 .B deletefile
 241 and
 242 .B renamefile
 243 operators, and the
 244 ability to open files in any mode other than read-only.  This may be
 245 desirable for spoolers or other sensitive environments.
 246 Files in the
 247 .B /fd
 248 directory may still be opened for writing.
 249 .TP
 250 .B -dWRITESYSTEMDICT
 251 Leaves systemdict writable.  This is necessary when running
 252 special utility programs such as font2c and pcharstr, which must bypass
 253 normal PostScript access protection.
 254 .TP
 255 .BI -sDEVICE= device
 256 Selects an alternate initial output device, as described above.
 257 .TP
 258 .BI -sOutputFile= filename
 259 Selects an alternate output file (or pipe) for the initial output
 260 device, as described above.
 261 .SH FILES
 262 .TP
 263 .B /sys/lib/ghostscript/*
 264 Startup-files, utilities, examples, and basic font definitions.
 265 .TP
 266 .B /sys/lib/ghostscript/fonts/*
 267 Additional font definitions.
 268 .SH SOURCE
 269 .B /sys/src/cmd/gs
 270 .SH "SEE ALSO"
 271 .IR page (1),
 272 .IR ps2pdf (1)
 273 .br
 274 The Ghostscript document files in
 275 .B doc
 276 and
 277 .B man
 278 subdirectories of the source directory.
 279 .SH BUGS
 280 The treatment of standard input is non-standard.