\Header{postscript}{PostScript Graphics}
\alias{.PostScript.Options}{postscript}
\alias{ps.options}{postscript}
\keyword{device}{postscript}
\begin{Description}\relax
\code{postscript} starts the graphics device driver for producing
PostScript graphics.

The auxiliary function \code{ps.options} can be used to set and view
(if called without arguments)
default values for the arguments to \code{postscript}.\end{Description}
\begin{Usage}
\begin{verbatim}
postscript(file = ifelse(onefile, "Rplots.ps", "Rplot
           onefile = TRUE,
           paper, family, bg, fg, width, height, horizontal, pointsize,
           pagecentre, print.it, command))

ps.options(paper, horizontal, width, height, family, pointsize, bg, fg,
           onefile = TRUE, print.it = FALSE, append = FALSE,
           reset = FALSE, override.check = FALSE)
.PostScript.Options
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{file}] a character string giving the name of the file.  If it is
\code{""}, the output is piped to the command given by
the argument \code{command}.
If it is \code{"|cmd"}, the output is piped to the command given
by \file{cmd}.

For use with \code{onefile=FALSE} give a
\code{printf} format such as \code{"Rplot\%d.fig"} (the default in that
case).

\item[\code{...}] further options for \code{postscript()} :
\item[\code{paper}] the size of paper in the printer.  The choices are
\code{"a4"}, \code{"letter"}, \code{"legal"} and
\code{"executive"} (and these can be capitalized).
Also, \code{"special"} can be used, when the \code{width}
and \code{height} specify the paper size.  A further choice is
\code{"default"}, which is the default.  If this is selected, the
papersize is taken from the option \code{"papersize"}
if that is set and to \code{"a4"} if it is unset or empty.
\item[\code{horizontal}] the orientation of the printed image, a
logical. Defaults to true, that is landscape orientation.
\item[\code{width, height}] the width and height of the graphics region in inches.
The default is to use the entire page less a 0.25 inch border.
\item[\code{family}] the font family to be used.
This must be one of \code{"AvantGarde"},
\code{"Bookman"}, \code{"Courier"}, \code{"Helvetica"},
\code{"Helvetica-Narrow"}, \code{"NewCenturySchoolbook"},
\code{"Palatino"} or \code{"Times"}.
\item[\code{pointsize}] the default point size to be used.
\item[\code{bg}] the default background color to be used.
\item[\code{fg}] the default foreground color to be used.
\item[\code{onefile}] logical: if true (the default) allow multiple figures
in one file. If false, generate a
file number containing the page number and give EPSF header
and no \code{DocumentMedia} comment.
\item[\code{pagecentre}] logical: should the device region be centred on the page:
defaults to true.
\item[\code{print.it}] logical: should the file be printed when the device is
closed?  (This only applies if \code{file} is a real file name.)
\item[\code{command}] the command to be used for ``printing''. Defaults to
option \code{"printcmd"}; this can also be selected as \code{"default"}.
\item[\code{append}] logical; currently \bold{disregarded}; just there for
compatibility reasons.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
\code{postscript(..)} opens the file \code{file} and the PostScript
commands needed to plot any graphics requested are stored in that file.
This file can then be printed on a suitable device to obtain hard
copy.

A postscript plot can be printed via \code{postscript} in two ways.
\Enumerate{
\item Setting \code{print.it = TRUE} causes the command given in
argument \code{command} to be called with argument \code{"file"}
when the device is closed.
Note that the plot file is not deleted unless command arranges to
delete it.

\item \code{file=""} or \code{file="|cmd"} can be used to print
using a pipe on systems that support \file{popen}.
}

The postscript produced by \R{} is EPS (\emph{Encapsulated PostScript})
compatible, and can be included into other documents, e.g. into LaTeX,
using \code{\\includegraphics\{<filename>\}}. For use in this way you will
probably want to set \code{horizontal=FALSE, onefile=FALSE, paper="special"}.\end{Details}
\begin{SeeAlso}\relax
\code{\Link{Devices}},
{\code{\Link{check.options}} which is called from both
\code{ps.options} and \code{postscript}}.\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}

# open the file "foo.ps" for graphics output
postscript("foo.ps")
# produce the desired graph(s)
dev.off()              # turn off the postscript device
postscript("|lp -dlw")
# produce the desired graph(s)
dev.off()              # plot will appear on printer



stopifnot(unlist(ps.options()) == unlist(.PostScript.Options))
ps.options(bg = "pink")
str(ps.options(reset = TRUE))

### --- error checking of arguments: ----
ps.options(width=0:12, onefile=0, bg=pi)
# override the check for 'onefile', but not the others:
str(ps.options(width=0:12, onefile=1, bg=pi, override.check = c(F,T,F)))
\end{ExampleCode}
\end{Examples}

