Graphics Device for PostScript Printers

DESCRIPTION:

Allows graphics to be produced for a PostScript printer.

USAGE:

postscript(file = "", width = <<see below>>,  
           height=<<see below>>, append=F,  
           onefile=T, print.it=<<see below>>,
           color.p=F,  ..., old.style=F) 

OPTIONAL ARGUMENTS:

file
character string naming a file where the PostScript commands are to go.
width
width of the device surface in inches. width refers to the x axis dimension. The default values for width and height are determined by ps.options()$region.
height
height of the device surface in inches. height refers to the y axis dimension. See the User's Manual sections on "Controlling Graphics Regions" and "Printing with PostScript Printers" for a more thorough discussion.
append
logical flag: if TRUE, PostScript output is appended to file if it already exists. In addition to appending the new graphics to the file, the file is modified to ensure that it remains compliant with the PostScript Document Structuring Conventions. If FALSE, the PostScript output generated by this device overwrites file, destroying its previous contents. This option is ignored if onefile is FALSE, since that causes individual files to be generated for each plot. If the options affecting the PostScript setup are different than they were when the file was originally generated, the new settings may have no effect on the appended plots. This is because several options are set up in a file header section. The PostScript code in this header section is not changed when appending. The "setup" section is affected by many of the options specified here and via the ps.options function, including the fonts, colors, region, width, height, preamble and other options.
onefile
if TRUE, all plots are accumulated into a single file as given by the file argument. If FALSE, each plot is written to a temporary file as given by the ps.options()$tempfile setting. Use onefile=FALSE together with print.it=FALSE to generate Encapsulated PostScript files. Setting onefile=TRUE may lead to multiple pages of output in a single file. Be careful when setting onefile to FALSE; when you specify a filename with the file argument, setting onefile=FALSE forces each plot to be output as it is completed, thus overwriting the single file specified by file for each plot. Further, the print.it argument defaults to TRUE when onefile=FALSE, and the default print command on many systems causes the temporary file to be deleted.
print.it
if TRUE and the ps.options()$command setting is not an empty string, then the output will be sent to the command. If print.it is FALSE, then no command will be run regardless of the values for ps.options()$command and the file argument to this function. The default for this argument is determined by the file, onefile and ps.options()$command settings. If onefile is FALSE, then the default is to print the output. Otherwise, the default is to print the output if file is set to an empty string.
color.p
a logical value; if TRUE, color PostScript will be generated, if FALSE, (the default), grayscale PostScript will be produced.
If either use.device.palette(TRUE) or use.legacy.graphics(TRUE) has been called, the color maps used are based on pdf.colors and pdf.grays. These color maps have been selected to work well with both ordinary and Trellis style plots. This argument is ignored if the ... contains a colors value or if old.style=TRUE.
...
other options are passed through to the printer drivers used by . Refer to for the list of valid commands for the PostScript driver. Each PostScript option should be prefixed with ps. in order to be passed through and recognized as a PostScript driver option. Note that the LaserJet driver has not yet been updated to use this scheme. For this driver, the ps. prefix is optional.
old.style
a logical value; if TRUE, the color.p argument is ignored and the pre-S-PLUS 7.0 default colors and settings are used.

SIDE EFFECTS:

initializes a graphics device which produces a file of PostScript graphics commands. Several varieties of laser printers understand the PostScript language. The device remains open until it is closed (e.g., with dev.off or by q()), and all graphics functions ( plot, par, etc.) will be directed to it until it is closed or another device becomes current (see dev.cur).

DETAILS:

Refer to the help on the ps.options function for a discussion of various PostScript control options. The ps.options function is used to set PostScript output options that are common among all the methods of generating PostScript graphics device output (the postscript and printgraph functions and the "print button" in the windowed graphics devices).

This command will always generate output to a file. If all output is going to one file (i.e. onefile=TRUE) and the file argument has been specified, then output will go to the specified file. Otherwise, a filename will be generated using the ps.options()$tempfile setting. If the output is to be printed using the ps.options()$command string, the filename will be appended to the command string separated by a space. The resulting command will be executed.

This driver follows the Adobe Document Structuring Convention Specifications Version 3. The first line of a PostScript file following the convention is:

%!PS-Adobe-3.0

A subset of this convention is Encapsulated PostScript; the first line of an Encapsulated PostScript file is:

%!PS-Adobe-3.0 EPSF-3.0

Encapsulated PostScript also insists that the file represents only one page. The postscript driver uses the header for Encapsulated PostScript when onefile=FALSE , and the other header when onefile=TRUE. This is a best guess strategy, as there can be more than one page of graphics produced with one call to a graphics function. Some programs that use Encapsulated PostScript may still accept a file with the non-Encapsulated header as long as it is a file for only one page.

This driver supports variable character sizes, general string and character rotations and ten line styles. Line width is specified by the lwd parameter, and is interpreted in units of 1/36 inches, hence the default lwd=1 line is 2 points wide. A line width of 0 gives the thinnest possible line on the device. Fonts that are normally filled (all but the Courier family) may be outlined by specifying the font as a negative number. The pch graphical parameter will select plotting characters from the Standard Encoding vector of PostScript (see the PostScript Language Reference Manual). When plotted these characters are always centered.

If you are creating small figures, you may want to specify a point.size smaller than the default value of 14, particularly if you get a message indicating that the computed plot does not fit. See help(ps.options) and Example 5 below.

By default, Spotfire S+ uses a global color palette and global image color palette to map color indices to specific colors. Color arguments can have integer values that map into the color palette, or they can be specified by RGB (or RGBA) values or color names. In order to use device specific color schemes, make one of these calls before calling postscript:

    use.device.palette(TRUE)
    use.legacy.graphics(TRUE)

For more information on color specification, see the chapter "Graphics Enhancements" in the Guide to Graphics.

NOTE:

The default value for some of the arguments in the definition of this function is -1. The -1 means that the value will be set elsewhere - possibly by an environment variable, or by a default deeper in the code.

WARNING:

The pscript function is included for backward compatibility. This function is deprecated; use postscript instead.

Do not allow two different instances of a graphics device to write to the same file. The file will become corrupted if this happens. It is possible to generate this problem if both file and onefile=FALSE are specified. See above warnings for the onefile argument.

Some PostScript printers impose a limit on the number of vertices there can be in a polygon. The postscript driver will output an outline for most of a polygon, if there are too many vertices. This limit can be controlled via the ps.options(max.vertices=n) command.

REFERENCES:

Adobe Systems, Inc. (1985). PostScript Language Tutorial and Cookbook. Addison-Wesley, Reading, Massachusetts.

Adobe Systems, Inc. (1990). PostScript Language Reference Manual, second edition. Addison-Wesley, Reading, Massachusetts.

SEE ALSO:

See the chapter "Spotfire S+ Graphic Device Support" in the Guide to Graphics. , , , , .

EXAMPLES:

# Example 1 
postscript() 
tsplot(hstart, log="y") 
dev.off() 

# Example 2 - The Behavior of onefile 
postscript("plots.ps") # onefile = T 
# plots will accumulate in plots.ps (one per page) 
plot(corn.rain) 
plot(corn.yield) 
dev.off() 
# File is not printed automatically, user must  
# explicitly print it. 
# File is not encapsulated, i.e., not suitable for  
# inclusion in other documents 

postscript("fig1.eps", onefile=F)  
plot(corn.rain) 
plot(corn.yield) 
# Get message like: Starting to make postscript file. 
#     Finished postscript file, executing command "lp fig1.eps &". 
# First figure has just printed 
dev.off() 
# Get another message like: Starting to make postscript file. 
#     Finished postscript file, executing command "lp fig1.eps &". 
# Both plots have printed, but fig1.eps contains only the second plot! 

postscript("fig1.eps", onefile=F, print.it=F) 
plot(corn.rain) 
plot(corn.yield) 
dev.off() 
# fig1.eps contains only the second plot! No plots have printed
# in either of the above two cases. fig1.eps can be included in 
# other documents as a figure using an appropriate package for 
# including postscript files 

# Example 3 
# Use ps.options variables within the postscript command 
sun.sp <- spectrum(sunspots, spans=c(19, 19, 19), plot=F) 
postscript(horizontal=T)   # ps.options variable creates landscape plot
spec.plot(sun.sp)
dev.off() 

# Example 4 - Varying Line Types
plot(1:8, axes=F, type="n", ylab="lty", xlab="") 
abline(h=1:8, lty=1:8) 
axis(2, at=1:8) 
box() 

# Example 5 - Small Figures
postscript(height=2, width=2, pointsize=9)
plot(1:5)
dev.off()
postscript(height=2, width=2, pointsize=9)
par(mar=c(4.1, 4.1, 3.1, 0.1))
plot(1:5)
dev.off()