Set or Return PostScript Options
DESCRIPTION:
Provides a means to control some of the behavior of the PostScript printer driver embedded in many of the graphics devices. The options contained here are those that are common between the postscript function and PostScript driver embedded in other drivers.
USAGE: 
ps.options (..., reset=F)
OPTIONAL ARGUMENTS:
...:
a list may be given as the only argument, or a vector of character strings given as the only argument, or any number of arguments may be in the name=value form, or no argument at all may be given. See the VALUE and SIDE EFFECTS sections for explanations.
reset:
a logical flag controlling whether or not the option values are reset to their "original" values before making the requested changes (if any). If TRUE, the copy of the options list stored on the session database (frame 0) will be removed. That copy of the options list is made whenever ps.options is used to set the value of a component of the options list. Removing that copy has the effect of resetting the options list to its default value (as stored in the default search() list). The default for this option is FALSE.

FREQUENTLY USED OPTIONS:
What follows is a listing of frequently used options. For a complete listing of all available options, refer to the ps.options.send help file.

background:
numeric object specifying a background color to use. If background is a single positive integer, it is treated as an index into the colors argument. If it is a negative number, then there is no background. Otherwise, it is assumed to be a single explicit color specification as in the colors argument. The default is -1 (no background).
colors:
numeric object giving an assignment of colors to color numbers. Using the default setcolor specification, there are two possibilities. If colors is a vector, it is used to define gray levels (0=black to 1=white) beginning with color number 1. If colors is a 3-column matrix, it is used to define colors in the RGB model (see the PostScript Language Reference Manual), one per row, beginning with color number 1.

The matrix ps.colors.rgb can be subsetted to provide a value for this argument. Also, the function ps.hsb2rgb can be used to convert colors from the HSB model to the RGB model equivalents. See the examples section below.

command:
character string containing a UNIX command that will be performed on the PostScript output. The default command is specified by the environment variable S_POSTSCRIPT_PRINT_COMMAND. The name of the file containing the PostScript output will be appended to the command string. If command is an empty string, printing will be disabled.
dsc:
number denoting the version of Adobe's Document Structuring Conventions(DSC) to use. This argument is primarily used to force an older version of the DSC headers to accomodate older software that may need to interpret those headers. It's use is not generally recommended.
font:
number giving the default font for text (see component fonts). A negative number will select the font in its outline form. The default value is 1 to pick the 1st font in fonts.
fonts:
character object enumerating the fonts you want available in PostScript. Font number i will be the i-th font named in this vector.
height:
height of plotting region in inches. height refers to the y axis dimension.
horizontal:
logical flag: if TRUE, plots are in landscape mode (x axis is along the longer edge of the paper). Otherwise, plots are in portrait mode.
image.colors:
numeric objects giving an assignment of colors to color numbers. These colors are used as fill colors for use with the image function. Refer to the colors component for specification details.
maximize:
logical flag: if TRUE, the page is used to the fullest (reasonable) extent. If FALSE, the PostScript output will try to match the actual size of the plot. The aspect ratio (or relative proportions) of the plot is maintained in either case.
paper:
character string indicating the size of the paper loaded into the PostScript printer. Some values accepted for paper are "letter", "legal" or "a4". Most standard ANSI and ISO paper sizes are accepted. This is used to determine the "imageable region" area of the paper. This argument, along with the ps.paper.regions dataset, will determine the default value for the region argument. The default for this may be either "letter" or "a4" depending on the local setup.
pointsize:
base size of text, in points (one point = 1/72 inches). If the graphical parameter cex is equal to 1, text will appear in this size. The default value is 14 points.
rasters:
number of plotting units per inch. The default is the typical laser printer device resolution of 300 units per inch.
region:
numeric vector of length 4 giving the coordinates of the lower left and upper right corners of the imageable region for the printer, in default PostScript coordinates. The default is determined by the paper argument and the ps.paper.regions dataset.

See the ps.paper.regions documentation for a way to discover the imageable region of your printer.

setfont:
character object containing the PostScript procedure for setting the current font. The procedure will be called with an integer font number by the PostScript program. This may be used to reencode the font with a different encoding vector (e.g. ISOLatin1Encoding). Typical values for this are contained in the ps.setfont.std and ps.setfont.latin1 datasets. The default is to use the ps.setfont.std dataset.
tempfile:
character string to be used as a template for naming a file where the PostScript commands are to go. The first sequence of "#" characters will be replaced with a number in the generated filenames. For instance, the first file generated using the default value of "ps.out.####.ps" will be "ps.out.0001.ps".
title:
character string that will be used for the %%Title: header in the PostScript output. The default value is the string "S-PLUS Graphics". This can be used to help keep track of what is contained within each PostScript output file.
width:
width of the plotting region in inches. width refers to the x axis dimension. The default values for width and height are determined by region, and need to be smaller than the width and height of the imageable region described by region.
SIDE EFFECTS:
When options are set, ps.options changes a list named .PostScript.Options in the session database (frame 0). The components of .PostScript.Options are all the currently defined options. The .PostScript.Options dataset is placed on frame 0 the first time a value is set via ps.options. The copy of the dataset on frame 0 can be removed with the reset argument.

If ps.options is called with either a list as the single argument, or with one or more arguments in the name=value form, then options specified by the names in the argument(s) are changed or created.

DETAILS:
This function is also used by devices supporting printgraph to get the current options for their embedded PostScript printer driver on startup. When its values are needed for use during device initialization, the command lapply(ps.options(),eval) is used to get the current values. This allows for the use of dynamically determined expressions in the ps.options list (e.g. get the value of an environment variable).
WARNING:
Note that there are several options in the ps.options list that are not intended to be changed unless you understand the workings of the devices and PostScript. All available options are documented in ps.options.send, but changing some of them can be hazardous to your output and/or printer setup.

Some printer driving software may have an option to reverse the order of the pages being output to the printer. In that case, the software needs to understand the DSC headers that are present in the PostScript output. Some older software may not properly understand the headers at the default value for the dsc option. Using a ps.options(dsc=2) may resolve such problems. Evidence of this sort of problem may be in a log file for the specific printer in the form of an error message sent back from the printer. The message would probably be complaining about the usage of an undefined command.

SEE ALSO:
ps.options , printgraph , postscript , ps.setfont.std, ps.setfont.latin1 , ps.paper.regions , ps.colors.rgb, rgb2matrix , hsb2rgb , getenv , xgetrgb
EXAMPLES: 
# Use these colors for PostScript on the next device startup.
ps.options (colors=ps.colors.rgb[c("red", "green", "blue"),],
            background=ps.colors.rgb[c("gray"),])


# Use existing HSB color model specifications
ps.options.send (colors=ps.hsb2rgb(my.hsb.ps.colors))
ps.options.send (colors=my.hsb.ps.colors, setcolor=ps.setcolor.hsb)


# Set colors for the image() function as shades of red
ps.options (image.colors=cbind(0:127/127, rep(0,128), rep(0,128)),
            title="Figure 1.1 [image data]")


# Setup for European usage.
ps.options (paper="A4", setfont=ps.setfont.latin1)


# Reset to S-PLUS default values.
ps.options (reset=T)