S-PLUS help

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>>, ...)

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.
...:: other options are passed through to the printer drivers used by printgraph. Refer to ps.options 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.

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. 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 backwards compatibility and should be considered deprecated. Use of the postscript function is recommended instead. Do not allow two different instances of a graphics device 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. Current models of Apple LaserWriters, for instance, have a limit of about 1500 vertices. 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: Devices , hplj , printgraph , ps.options . EXAMPLES: # Example 1 postscript() tsplot(hstart, log="y") dev.off() Finished postscript file, executing command "lp ps.out.0004.ps &". # 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() Generated postscript file "plots.ps". # 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) Starting to make postscript file. Finished postscript file, executing command "lp fig1.eps &". #first figure has just printed dev.off() 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) Starting to make postscript file. Generated postscript file "fig1.eps". dev.off() Starting to make postscript file. Generated postscript file "fig1.eps". #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 spec.plot(sun.sp) #landscape plot dev.off() # Example 4 # the example plot is produced by plot(1:8, axes=F, type="n", ylab="lty", xlab="") for (i in 1:8) abline(h=i, lty=i) axis(2, at=1:8) box()