PSFIG(1)

NAME
psfig - a troff preprocessor for PostScript figures

SYNTAX
psfig [ -D<search-dir> ] [ -d<draft-level> ] [ file ... ]

DESCRIPTION
Psfig is a preprocessor for ditroff(1) that permits direct inclusion of PostScript figures and special effects into a document. The input files are copied to the standard output, except for lines between .F+ and .F- commands, which are assumed to contain psfig commands. If no input files are given, psfig reads the standard input, so it may be used as part of a pipe to ditroff. The -D<dir> option specifies a directory in which to search for files. Any number of these may be specified, and they will be searched in turn. The current directory is always searched first.

The -mpsfig argument must be given to ditroff, whose output is passed to psdit, the ditroff to postscript conversion program supplied with the Transcript package, which produces the final output.

Psfig commands are enclosed between `.F+' and `.F-' macros in your document. The simplest psfig command is the word `figure', followed by the name of a PostScript file. For example,

    .F+
    figure image.ps
    .F-

would include the figure in `image.ps' into your document as a centered display. Psfig uses bounding box information from the PostScript file to decide where the figure is normally printed on the page, then performs the appropriate translation to move the figure to the current spot on the ditroff page. The proper amount of space is reserved so that the figure doesn't conflict with anything else on the page. Adding an `L' argument to `.F+' would force the figure to be flush left.

Several options may be specified on the `figure' command, including `height' or `width' followed by a troff value, which would shrink or enlarge the figure to the specified measurement. If either a height and a width is specified, but not both, then the figure is scaled equally so that the shape of the figure is maintained. For example

    .F+
    figure image.ps height 1i
    .F-

would include `image.ps' scaled so that it has a vertical edge of one inch.

Delimiting characters for in-line figures may be specified using the `delim <char><char>' command. Any sequence of psfig commands may be enclosed between the delimter characters and the resulting figures will appear in-line rather than broken out in the document. Using delim without argument, as in `delim ; ', will diable in-line processing.

For psfig to properly scale and move a figure, it must be able to tell what it's natural size and position on the page are. This is usually specified by the bounding box comment in the PostScript file. Unfortunately, some applications (including MacDraw) do not provide this information. In this case you can add the clause `bounds llx lly urx ury' to the figure command, manually specifying the bounding box of the figure. The four coordinates are, respectively, the lower left x coordinate, the lower left y coordinate, the upper right x coordinate, and the upper right y coordinate of the figure's bounding box, all specified in points relative to an origin in the lower left corner of the page.

DRAFT MODE

If a figure is very expensive to print (say a 100K image) it can be set in draft mode, printing just an outline box and the name of the file, for all but the final version of the document. Each psfig figure has a level associated with it; the default is 10, but this may be superseeded with a `level n' clause on the figure command. -d<level> flag specifies the draft level for psfig to run at. If the level of a figure exceeds the draft level, the figure is printed in draft mode (just an outline box.) The default draft level is 100, and the default level of a figure is 10. If just a -d is specified with no level, zero is assumed. In full draft mode, psfig is quite flexible. Plain-vanilla troff (or even nroff) and any generic output device will suffice, so that you can write a paper on a non-PostScript system in draft mode, then print the final copy on a PostScript system.

SEE ALSO

ditroff(1), transcript(8), psdit(1)
N. Batchelder and T. Darrell, Psfig - A New Ditroff Preprocessor