Copyright (C) 1989, 1995, 1996 Aladdin Enterprises.  All rights reserved.
  
  This file is part of Aladdin Ghostscript.
  
  Aladdin Ghostscript is distributed with NO WARRANTY OF ANY KIND.  No author
  or distributor accepts any responsibility for the consequences of using it,
  or for whether it serves any particular purpose or works at all, unless he
  or she says so in writing.  Refer to the Aladdin Ghostscript Free Public
  License (the "License") for full details.
  
  Every copy of Aladdin Ghostscript must include a copy of the License,
  normally in a plain ASCII text file named PUBLIC.  The License grants you
  the right to copy, modify and redistribute Aladdin Ghostscript, but only
  under certain conditions described in the License.  Among other things, the
  License requires that the copyright notice and this notice be preserved on
  all copies.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

This file, use.txt, describes how to use the Ghostscript language
interpreter.

For an overview of Ghostscript and a list of the documentation files, see
README.  

********
******** Installing Ghostscript
********

Please read the documentation file install.txt for information on installing
Ghostscript.

********
******** Shell scripts for Ghostscript
********

The Ghostscript distribution includes several Unix shell scripts for
driving Ghostscript in different environments.  These are all
user-contributed code: please contact the user identified in the file, not
Aladdin Enterprises, if you have questions.

> pv.sh - preview a specified page of a dvi file in an X window.

> sysvlp.sh - System V 3.2 lp interface for parallel printer.

> pj-gs.sh - printing on an H-P PaintJet under HP-UX.

> unix-lpr.sh - queue filter for lpr under Unix.
> lprsetup.sh - setup for unix-lpr.sh.

If one of these serves your needs, you may be able to skip most of
the rest of this document.

********
******** How to use Ghostscript ********
********

To invoke the interpreter, give the command
	gs <filename1> ... <filenameN>
The interpreter will read in the files in sequence (using the method
described under "File searching" below to find the files) and execute them.
After doing this, it reads further input from the primary input stream
(normally the keyboard).  Each line (i.e. characters up to a <return>) is
interpreted separately.  To exit from the interpreter, type quit<return>.
The interpreter also exits gracefully if it encounters end-of-file.  Typing
the interrupt character, e.g., control-C, is also safe.

The interpreter recognizes several switches described below, which may appear
anywhere in the command line and apply to all files thereafter.

You can get a brief help message by invoking Ghostscript with
	gs -h
or
	gs -?
This message also lists the available devices.  For a little more
information about available devices, a one-line description of each device
appears near the beginning of the file devs.mak.

Choosing the output device
--------------------------

Ghostscript may be built with multiple output devices.  Ghostscript
normally opens the first one and directs output to it.  To use device xyz
as the initial output device, include the switch
	-sDEVICE=xyz
in the command line.  Note that this switch must precede the first .ps
file, and only its first invocation has any effect.  For example, for
printer output in a normal configuration that includes an Epson printer
driver, you might use the shell command
	gs -sDEVICE=epson myfile.ps
instead of just
	gs myfile.ps
Alternatively, once you are inside Ghostscript, you can type
	(epson) selectdevice
	(myfile.ps) run
All output then goes to the printer instead of the display until further
notice.  You can switch devices at any time by using the selectdevice
procedure, e.g.,
	(vga) selectdevice
or
	(epson) selectdevice
As yet a third alternative, you can define an environment variable
GS_DEVICE as the desired default device name.  The order of precedence for
these alternatives, highest to lowest, is:
	selectdevice
	(command line)
	GS_DEVICE
	(first device in build list)

To select the resolution on a printer, use the shell command
	gs -sDEVICE=<device> -r<xres>x<yres>
For example, on a 9-pin Epson-compatible printer, you can get the
lowest-resolution (fastest) mode with
	gs -sDEVICE=epson -r60x72
and the highest-resolution mode with
	gs -sDEVICE=epson -r240x72.
On a 24-pin printer, the lowest resolution is
	gs -sDEVICE=epson -r60x60
and the highest-resolution 24-pin mode is
	gs -sDEVICE=epson -r360x180

If you select a printer as the output device, Ghostscript also allows you
to control where the device sends its output.  Normally, output goes
directly to the printer (PRN) on MS-DOS systems, and to a scratch file on
Unix or VMS systems.  To send the output to a series of files foo1.xyz,
foo2.xyz, ..., use the switch
	-sOutputFile=foo%d.xyz
(For compatibility with older versions of Ghostscript, -sOUTPUTFILE=
also works.)  The %d is a printf format specification; you can use
other formats like %02d.  Each file will receive one page of output.
Alternatively, to send the output to a single file foo.xyz, with all
the pages concatenated, use the switch
	-sOutputFile=foo.xyz

On Unix systems, you can send the output directly to a pipe.  For
example, to pipe the output to the command `lpr' (which, on many Unix
systems, is the command that spools output for a printer), use the
switch
	-sOutputFile=\|lpr
You can also send output to stdout for piping with the switch
	-sOutputFile=-
In this case you must also use the -q switch, to prevent Ghostscript from
writing messages to stdout.

File formats like PCX and PBM are also 'devices'.  When you select a file
format as the 'device', you must also specify an output file, e.g.,
	gs -sDEVICE=pcxmono -sOutputFile=xyz.pcx

To find out what devices are available, type
	devicenames ==
after starting up Ghostscript.  Alternatively you can use the -h or
-? switch in the command line, as described above.

Choosing paper size
-------------------

Ghostscript is normally configured to expect U.S. letter paper.  To select
a different paper size as the default, find the line in gs_init.ps that
says

	% Optionally choose a default paper size other than U.S. letter.

The next line begins

	% (a4)

To select A4 as the default paper size, remove the % but do not change
anything else.  To select a different default paper size, remove the % and
replace the word a4 with the name of the desired paper size.  You can use
any paper size listed in the table at the beginning of gs_statd.ps.
(Individual documents can also specify a paper size, which will take
precedence over the one specified on the command line.)

Alternatively, to select a different paper size for a single invocation of
Ghostscript, you can use the command line switch
	-sPAPERSIZE=a_known_paper_size
e.g.,
	-sPAPERSIZE=a4
or
	-sPAPERSIZE=legal

Finally, most (but not all) of Ghostscript's printer drivers can be
configured at compile time to use A4 paper as the default by including
-DA4 in the CFLAGS switches in the makefile.  See make.txt for more
details.

File searching
--------------

When looking for initialization files (gs_*.ps, pdf_*.ps), font files, the
Fontmap file, and files named on the command line, Ghostscript first checks
whether the file name specifies an explicit directory or drive (i.e.,
doesn't begin with '/' on Unix systems; doesn't begin with a '/' or '\' or
contain ':' as the second character on MS-DOS systems; doesn't contain a ':'
or a square bracket on VMS systems).  If it does, Ghostscript simply tries
to open the file using the given name.  Otherwise, Ghostscript will try
directories in the following order:

	- The current directory (unless disabled by the -P- switch);

	- The directory/ies specified by the -I switch(es) in the command
	  line (see below), if any;

	- The directory/ies specified by the GS_LIB environment variable,
	  if any;

	- The directory/ies specified by the GS_LIB_DEFAULT macro in the
	  Ghostscript makefile, if any.

Each of these (GS_LIB_DEFAULT, GS_LIB, and -I parameter) may be either a
single directory, or a list of directories separated by a character
appropriate for the operating system (':' on Unix systems, ';' on VMS
systems, ';' on MS-DOS systems).  We think that trying the current directory
first is a very bad idea -- it opens serious security loopholes and can lead
to very confusing errors if one has more than one version of Ghostscript in
one's environment -- but when we attempted to change it, users insisted that
we change it back.  You can disable looking in the current directory first
using the -P- switch described below.

Note that Ghostscript does not use this file searching algorithm for the
'run' or 'file' operators: for these operators, it simply opens the file
with the given name.  To run a file using the searching algorithm, use
'runlibfile' instead of 'run'.

When Ghostscript can't find a font in any Fontmap file in the search path,
it looks at the GS_FONTPATH environment variable (or the value provided with
the -sFONTPATH= switch, if present), which is also a list of directories.
It goes to those directories, one by one, and looks for all files that
appear to contain PostScript fonts; it then effectively adds all those files
and fonts to its internal copy of the Fontmap (the catalog of fonts and the
files that contain them).  If you are using one of the following types of
computer, you may wish to set GS_FONTPATH to the indicated value so that
Ghostscript will automatically acquire all the installed Type 1 fonts:

	System type		GS_FONTPATH
	-----------		-----------
	DEC OSF/1		/usr/lib/X11/fonts/Type1Adobe
	DEC Ultrix		/usr/lib/DPS/outline/decwin
	HP-UX 9			/usr/lib/X11/fonts/type1.st/typefaces
	IBM AIX			/usr/lpp/DPS/fonts/outlines
	  "			/usr/lpp/X11/lib/X11/fonts/Type1
	  "			/usr/lpp/X11/lib/X11/fonts/Type1/DPS
	NeXT			/NextLibrary/Fonts/outline
	SGI IRIX		/usr/lib/DPS/outline/base
	  "			/usr/lib/X11/fonts/Type1
	Sun SunOS 4.x		/usr/openwin/lib/X11/fonts/Type1/outline
	  " (NeWSprint only)
   newsprint_2.5/SUNWsteNP/reloc/$BASEDIR/NeWSprint/small_openwin/lib/fonts
	Sun Solaris 2		/usr/openwin/lib/X11/fonts/Type1/outline
	VMS			SYS$COMMON:[SYSFONT.XDPS.OUTLINE]

These paths may not be exactly right for your installation; if the
indicated directory doesn't contain files whose names are familiar font
names like Courier and Helvetica, you may wish to ask your system
administrator where to find these fonts.

NOTE: On Solaris systems simply setting GS_FONTPATH may not work, because
for some reason some versions of Ghostscript can't seem to find any of the
Type1 fonts in /usr/openwin/lib/X11/fonts/Type1/outline. It says: "15 files,
15 scanned, 0 new fonts". See Fontmap.Solaris instead.

Temporary files
---------------

By default, Ghostscript creates temporary files named _temp_XX.XXX in the
current directory on MS-DOS and VMS systems, gsXXXXXX in the current
directory on OS/2 systems, and gs_XXXXX in the /tmp directory on Unix
systems.  You can change the directory in which Ghostscript will create
these files by setting the TEMP environment variable to the name of the
directory.

Ghostscript currently doesn't do a very good job of deleting temporary
files when it exits; you may have to delete them manually from time to
time.

Environment variable summary
----------------------------

GS_DEVICE
	Defines the default output device.  Described above.

GS_FONTPATH
	Specifies a list of directories that should be scanned for fonts
at startup.  Described above.

GS_LIB
	Provides a search path for initialization files and fonts.
Described above.

GS_OPTIONS
	Defines a list of command line arguments to be processed before
the ones actually specified on the command line.  For example, setting
GS_DEVICE to xxx is equivalent to setting GS_OPTIONS to -sDEVICE=xxx.  The
contents of GS_OPTIONS are not limited to switches; they may include
actual file names or even @file arguments.

TEMP
	Defines a directory name for temporary files.  Described above.

********
******** Using Ghostscript and Ghostview with PDF files
********

Ghostscript is normally configured (except on 16-bit MS-DOS platforms) so
that it can interpret both PostScript and PDF files (the latter are
sometimes incorrectly called "Acrobat files").  It examines each file to
determine automatically whether it is a PDF file or a PostScript file.  All
the normal switches and procedures for interpreting PostScript files also
apply to PDF files, with a few exceptions noted below.  In addition, there
is a shell script

		pdf2ps input.pdf output.ps

that converts PDF to (Level 2) PostScript.

Switches not applicable to PDF files
------------------------------------

You cannot use the `-' switch to provide PDF input from stdin or a pipe.
The PDF language, unlike the PostScript language, inherently requires random
access to the file.

Added switches for PDF files
----------------------------

	-dFirstPage=pagenumber
		Starts interpreting on the given page of the document.

	-dLastPage=pagenumber
		Stops interpreting after the given page of the document.

	-sPSfile=filename
		Writes the PostScript equivalent of the PDF input on the
		given file.

Ghostview and PDF files
-----------------------

Since Ghostview pipes PostScript files to Ghostscript, you cannot view PDF
files with Ghostview just by saying
		ghostview file.pdf
Instead there are two options:

   1. Tanmoy Bhattacharya has written some patches for Ghostview 1.5
   that allow it to read and display PDF files.  These are available
   from:
       ftp://gita.lanl.gov/people/tanmoy/hypertex/gv1.5gs3.33hack.tar.gz

   2. Start Ghostview as follows:
          ghostview -arguments file.pdf quit.ps
   This will allow you to display a PDF file, but you won't be able
   to jump to particular pages.  Use Tanmoy's code if you want that
   facility.

********
******** Notes on specific platforms ********
********

VMS
---

On VMS systems, the last character of each "directory" name indicates what
sort of entity the "directory" references.  If the "directory" name ends
with a colon, it is taken as referring to a logical device, e.g.:
	$ DEFINE GHOSTSCRIPT_DEVICE DUA1:[GHOSTSCRIPT_14]
	$ DEFINE GS_LIB GHOSTSCRIPT_DEVICE:
If the "directory" name ends with a closing square bracket, it is taken as
referring to a real directory, e.g.:
	$ DEFINE GS_LIB DUA1:[GHOSTSCRIPT]

To run Ghostscript with switches, you must type a command like

	$ gs "-dNODISPLAY"

because the C run time library will convert the command