Some manpage cleanup and simplification.

git-svn-id: http://svn.ghostscript.com/ghostscript/trunk@3305 a1074d23-0009-0410-80fe-cf8c14f379e6

1 files changed, 100 insertions, 161 deletions

diff --git a/gs/man/gs.1 b/gs/man/gs.1
index ddebc201c..1257e9778 100644
--- a/gs/man/gs.1
+++ b/gs/man/gs.1
@@ -5,11 +5,9 @@ gs \- Ghostscript (PostScript and PDF language interpreter and previewer)
 .SH SYNOPSIS
 \fBgs\fR [ \fIoptions\fR ] [ \fIfiles\fR ] ... \fB(Unix, VMS)\fR
 .br
-\fBgswin32\fR [ \fIoptions\fR ] [ \fIfiles\fR ] ... \fB(MS Windows)\fR
-.br
 \fBgswin32c\fR [ \fIoptions\fR ] [ \fIfiles\fR ] ... \fB(MS Windows)\fR
 .br
-\fBgs386\fR [ \fIoptions\fR ] [ \fIfiles\fR ] ... \fB(DOS for PC)\fR
+\fBgswin32\fR [ \fIoptions\fR ] [ \fIfiles\fR ] ... \fB(MS Windows 3.1)\fR
 .br
 \fBgsos2\fR [ \fIoptions\fR ] [ \fIfiles\fR ] ... \fB(OS/2)\fR
 .de TQ
@@ -18,25 +16,26 @@ gs \- Ghostscript (PostScript and PDF language interpreter and previewer)
 .TP \\$1
 ..
 .SH DESCRIPTION
-The \fBgs\fR (\fBgswin32\fR, \fBgswin32c\fR, \fBgs386\fR, \fBgsos2\fR)
+The \fBgs\fR (\fBgswin32c\fR, \fBgswin32\fR, \fBgsos2\fR)
 command invokes \fBGhostscript\fR, an interpreter of Adobe Systems'
 \fBPostScript\fR(tm) and \fBPortable Document Format\fR (PDF) languages.
 \fBgs\fR reads "files" in sequence and executes them as Ghostscript
-programs.  After doing this, it reads further input from the standard input
-stream (normally the keyboard), interpreting each line separately.  The
-interpreter quits gracefully when it encounters the "quit" command (either
+programs. After doing this, it reads further input from the standard input
+stream (normally the keyboard), interpreting each line separately. The
+interpreter exits gracefully when it encounters the "quit" command (either
 in a file or from the keyboard), at end-of-file, or at an interrupt signal
 (such as Control-C at the keyboard).
 .PP
-The interpreter recognizes several switches described below, which may
-appear anywhere in the command line and apply to all files thereafter.
+The interpreter recognizes many option switches, some of which are described
+below. Please see the usage documenation for complete information. Switches
+may appear anywhere in the command line and apply to all files thereafter.
 Invoking Ghostscript with the \fB\-h\fR or \fB\-?\fR switch produces a
 message which shows several useful switches, all the devices known to
 that executable, and the search path for fonts; on Unix it also shows the
 location of detailed documentation.
 .PP
-Ghostscript may be built able to use many different output devices.  To see
-which devices your executable can use, run "\fBgs -h\fR".  Unless you
+Ghostscript may be built to use many different output devices.  To see
+which devices your executable includes, run "\fBgs -h\fR".  Unless you
 specify a particular device, Ghostscript normally opens the first one of
 those and directs output to it, so if the first one in the list is the one
 you want to use, just issue the command
@@ -67,38 +66,14 @@ For example, for output to an Epson printer you might use the command
 .fi
 .PP
 The "\-sDEVICE=" switch must precede the first mention of a file to print,
-and only the switch's first use has any effect.  Alternatively, in
-Ghostscript you can type
-.PP
-.nf
-	(epson) selectdevice
-	(myfile.ps) run
-.fi
-.PP
-All output then goes to the printer until you select another device with
-the "selectdevice" procedure in the PostScript program stream, for example
-.PP
-.nf
-	(vga) selectdevice
-.fi
-or
-.nf
-	(x11) selectdevice
-.fi
+and only the switch's first use has any effect.
 .PP
 Finally, you can specify a default device in the environment variable
 \fBGS_DEVICE\fR.  The order of precedence for these alternatives from
 highest to lowest (Ghostscript uses the device defined highest in the list)
 is:
 .PP
-.nf
-	selectdevice
-	(command line)
-	GS_DEVICE
-	(first device in build list)
-.fi
-.PP
-Some printers can print at different resolutions (densities).  To specify
+Some devices can support different resolutions (densities).  To specify
 the resolution on such a printer, use the "\-r" switch:
 .PP
 .nf
@@ -139,19 +114,26 @@ Each resulting file receives one page of output, and the files are numbered
 in sequence.  "%d" is a printf format specification; you can also use a
 variant like "%02d".
 .PP
-On Unix systems you can also send output to a pipe.  For example, to
+On Unix and MS Windows systems you can also send output to a pipe.  For example, to
 pipe output to the "\fBlpr\fR" command (which, on many Unix systems,
-directs it to a printer), use the switch
+directs it to a printer), use the option
 .PP
 .nf
-	\-sOutputFile=\\|lpr
+	\-sOutputFile=%pipe%lpr
 .fi
 .PP
-You can also send output to standard output for piping with the switch
+Note that the '%' characters need to be doubled on MS Windows to avoid 
+mangling by the command interpreter.
+.PP
+You can also send output to standard output:
 .PP
 .nf
 	\-sOutputFile=\-
 .fi
+or
+.nf
+	\-sOutputFile=%stdout%
+.fi
 .PP
 In this case you must also use the \fB\-q\fR switch, to prevent Ghostscript
 from writing messages to standard output.
@@ -159,7 +141,7 @@ from writing messages to standard output.
 To select a specific paper size, use the command line switch
 .PP
 .nf
-	-sPAPERSIZE=a_known_paper_size
+	-sPAPERSIZE=<paper_size>
 .fi
 .PP
 for instance
@@ -172,57 +154,13 @@ or
 	-sPAPERSIZE=legal
 .fi
 .PP
-At this time, the known paper sizes, defined in the initialization
-file "gs_statd.ps", are:
-.TS
-tab(>);
-l l l l l.
-.sp
-PAPERSIZE>X inches>Y inches>X cm>Y cm
-_
-a0>33.0556>46.7778>83.9611>118.816
-a1>23.3889>33.0556>59.4078>83.9611
-a2>16.5278>23.3889>41.9806>59.4078
-a3>11.6944>16.5278>29.7039>41.9806
-a4>8.26389>11.6944>20.9903>29.7039
-a5>5.84722>8.26389>14.8519>20.9903
-a6>4.125>5.84722>10.4775>14.8519
-a7>2.91667>4.125>7.40833>10.4775
-a8>2.05556>2.91667>5.22111>7.40833
-a9>1.45833>2.05556>3.70417>5.22111
-a10>1.02778>1.45833>2.61056>3.70417
-b0>39.3889>55.6667>100.048>141.393
-b1>27.8333>39.3889>70.6967>100.048
-b2>19.6944>27.8333>50.0239>70.6967
-b3>13.9167>19.6944>35.3483>50.0239
-b4>9.84722>13.9167>25.0119>35.3483
-b5>6.95833>9.84722>17.6742>25.0119
-archA>9>12>22.86>30.48
-archB>12>18>30.48>45.72
-archC>18>24>45.72>60.96
-archD>24>36>60.96>91.44
-archE>36>48>91.44>121.92
-flsa>8.5>13>21.59>33.02
-flse>8.5>13>21.59>33.02
-halfletter>5.5>8.5>13.97>21.59
-note>7.5>10>19.05>25.4
-letter>8.5>11>21.59>27.94
-legal>8.5>14>21.59>35.56
-11x17>11>17>27.94>43.18
-ledger>17>11>43.18>27.94
-.TE
-.PP
-Note that the B paper sizes are ISO sizes: for information about using
-JIS B sizes, see \fBUse.htm\fR.
+Most ISO and US paper sizes are recognized. See the usage documenatation for
+a full list, or the definitions in the initialization file "gs_statd.ps".
 .PP
 Ghostscript can do many things other than print or view PostScript and
 PDF files.  For example, if you want to know the bounding box of a
 PostScript (or EPS) file, Ghostscript provides a special "device" that
-just prints out this information:
-.PP
-.nf
-	gs \-sDEVICE=bbox myfile.ps
-.fi
+just prints out this information.
 .PP
 For example, using one of the example files distributed with Ghostscript,
 .PP
@@ -236,74 +174,7 @@ prints out
 	%%BoundingBox: 0 25 583 732
 	%%HiResBoundingBox: 0.808497 25.009496 582.994503 731.809445
 .fi
-.SH "INITIALIZATION FILES"
-When looking for the initialization files "gs_*.ps", the files related to
-fonts, or the file for the "run" operator, Ghostscript first tries to open
-the file with the name as given, using the current working directory if no
-directory is specified.  If this fails, and the file name doesn't specify
-an explicit directory or drive (for instance, doesn't contain "/" on Unix
-systems or "\\" on DOS systems), Ghostscript tries directories in this
-order:
-.TP 4
-1.
-the directories specified by the \fB\-I\fR switches in the command
-line (see below), if any;
-.TP
-2.
-the directories specified by the \fBGS_LIB\fR environment variable,
-if any;
-.TP
-3.
-the directories specified by the \fBGS_LIB_DEFAULT\fR macro in the
-Ghostscript makefile when the executable was built.  When \fBgs\fR is built
-on Unix, \fBGS_LIB_DEFAULT\fR is usually
-"/usr/local/share/ghostscript/#.##:/usr/local/share/ghostscript/fonts"
-where "#.##" represents the Ghostscript version number.
-.PP
-Each of these (\fBGS_LIB_DEFAULT\fR, \fBGS_LIB\fR, and \fB\-I\fR parameter)
-may be either a single directory or a list of directories separated by
-":".
-.SH X RESOURCES
-Ghostscript looks for the following resources under the program name
-"Ghostscript":
-.TP
-.B borderWidth
-The border width in pixels (default = 1).
-.TP
-.B borderColor
-The name of the border color (default = black).
-.TP
-.B geometry
-The window size and placement, WxH+X+Y (default is NULL).
-.TP
-.B xResolution
-The number of x pixels per inch (default is computed from \fBWidthOfScreen\fR
-and \fBWidthMMOfScreen\fR).
-.TP
-.B yResolution
-The number of y pixels per inch (default is computed from
-\fBHeightOfScreen\fR and \fBHeightMMOfScreen\fR).
-.TP
-.B useBackingPixmap
-Determines whether backing store is to be used for saving display window
-(default = true).
-.PP
-See the usage document for a more complete list of resources.  To set these
-resources on Unix, put them in a file such as "~/.Xresources" in the
-following form:
-.PP
-.nf
-	Ghostscript*geometry:	 612x792\-0+0
-	Ghostscript*xResolution: 72
-	Ghostscript*yResolution: 72
-.fi
-.PP
-Then merge these resources into the X server's resource database:
-.PP
-.nf
-	% xrdb \-merge ~/.Xresources
-.fi
-.SH SWITCHES
+.SH OPTIONS
 .TP
 .BI \-\- " filename arg1 ..."
 Takes the next argument as a file name as usual, but takes all remaining
@@ -395,14 +266,15 @@ desirable for applications where another program is driving Ghostscript.
 .TP
 .B \-dNOPLATFONTS
 Disables the use of fonts supplied by the underlying platform (for instance
-X Windows).  This may be needed if the platform fonts look undesirably
+X Windows). This may be needed if the platform fonts look undesirably
 different from the scalable fonts.
 .TP
 .B \-dSAFER
 Disables the "deletefile" and "renamefile" operators and the ability to
-open files in any mode other than read-only.  This may be desirable for
-spoolers or other sensitive environments where a badly written or malicious
-PostScript program must be prevented from changing important files.
+open files in any mode other than read-only.  This strongly recommended for
+spoolers, conversion scripts or other sensitive environments where a badly 
+written or malicious PostScript program code must be prevented from changing
+important files.
 .TP
 .B \-dWRITESYSTEMDICT
 Leaves "systemdict" writable.  This is necessary when running special
@@ -436,6 +308,33 @@ Ghostscript demonstration files
 .TP
 .B /usr/local/share/ghostscript/#.##/doc/*
 Diverse document files
+.SH "INITIALIZATION FILES"
+When looking for the initialization files "gs_*.ps", the files related to
+fonts, or the file for the "run" operator, Ghostscript first tries to open
+the file with the name as given, using the current working directory if no
+directory is specified.  If this fails, and the file name doesn't specify
+an explicit directory or drive (for instance, doesn't contain "/" on Unix
+systems or "\\" on MS Windows systems), Ghostscript tries directories in this
+order:
+.TP 4
+1.
+the directories specified by the \fB\-I\fR switches in the command
+line (see below), if any;
+.TP
+2.
+the directories specified by the \fBGS_LIB\fR environment variable,
+if any;
+.TP
+3.
+the directories specified by the \fBGS_LIB_DEFAULT\fR macro in the
+Ghostscript makefile when the executable was built.  When \fBgs\fR is built
+on Unix, \fBGS_LIB_DEFAULT\fR is usually
+"/usr/local/share/ghostscript/#.##:/usr/local/share/ghostscript/fonts"
+where "#.##" represents the Ghostscript version number.
+.PP
+Each of these (\fBGS_LIB_DEFAULT\fR, \fBGS_LIB\fR, and \fB\-I\fR parameter)
+may be either a single directory or a list of directories separated by
+":".
 .SH ENVIRONMENT
 .TP
 .B GS_OPTIONS
@@ -452,6 +351,46 @@ Path names for initialization files and fonts
 .TP
 .B  TEMP
 Where temporary files are made
+.SH X RESOURCES
+Ghostscript, or more properly the X11 display device, looks for the 
+following resources under the program name "Ghostscript":
+.TP
+.B borderWidth
+The border width in pixels (default = 1).
+.TP
+.B borderColor
+The name of the border color (default = black).
+.TP
+.B geometry
+The window size and placement, WxH+X+Y (default is NULL).
+.TP
+.B xResolution
+The number of x pixels per inch (default is computed from \fBWidthOfScreen\fR
+and \fBWidthMMOfScreen\fR).
+.TP
+.B yResolution
+The number of y pixels per inch (default is computed from
+\fBHeightOfScreen\fR and \fBHeightMMOfScreen\fR).
+.TP
+.B useBackingPixmap
+Determines whether backing store is to be used for saving display window
+(default = true).
+.PP
+See the usage document for a more complete list of resources.  To set these
+resources on Unix, put them in a file such as "~/.Xresources" in the
+following form:
+.PP
+.nf
+	Ghostscript*geometry:	 612x792\-0+0
+	Ghostscript*xResolution: 72
+	Ghostscript*yResolution: 72
+.fi
+.PP
+Then merge these resources into the X server's resource database:
+.PP
+.nf
+	% xrdb \-merge ~/.Xresources
+.fi
 .SH SEE ALSO
 The various Ghostscript document files (above), especially \fBUse.htm\fR.
 .SH BUGS