NAME

mpictures − picture inclusion macros

SYNOPSIS

­troff -mpictures [ ­options ] ­file ... 

DESCRIPTION

­Mpictures macros insert PostScript pictures into troff(1) documents. The macros are:

.BP source height width position offset flags label
Define a frame and place a picture in it. Null arguments, represented by "", are interpreted as defaults.  The arguments are:

­source Name of a PostScript picture file, optionally suffixed with (n) to select page number ­n from the file (first page by default). 

­height Vertical size of the frame, default 3.0i. 

­width Horizontal size of the frame, current line length by default. 

­position
­l (default), c, or ­r to left-justify, center, or right-justify the frame. 

­offset Move the frame horizontally from the original ­position by this amount, default 0i. 

­flags One or more of:

ad Rotate the picture clockwise ­d degrees, default d=90.

­o Outline the picture with a box. 

­s Freely scale both picture dimensions. 

­w White out the area to be occupied by the picture. 

l,r,t,b
Attach the picture to the left right, top, or bottom of the frame.

­label Place ­label at distance ­1.5v below the frame. 

If there’s room, ­.BP fills text around the frame.  Everything destined for either side of the frame goes into a diversion to be retrieved when the accumulated text sweeps past the trap set by ­.BP or when the diversion is explicitly closed by .EP. 

.PI source height,width,yoffset,xoffset flags. 
This low-level macro, used by .BP, can help do more complex things.  The two arguments not already described are:

­xoffset Offset the frame from the left margin by this amount, default 0i. 

­yoffset Offset the frame from the current baseline, measuring positive downward, default 0i. 

­.EP End a picture started by .BP; ­.EP is usually called implicitly by a trap at frame bottom. 

If a PostScript file lacks page-delimiting comments, the entire file is included.  If no ­%%BoundingBox comment is present, the picture is assumed to fill an 8.5×11-inch page.  Nothing prevents the picture from being placed off the page. 

SEE ALSO

troff(1)

DIAGNOSTICS

A picture file that can’t be read by the PostScript postprocessor is replaced by white space. 

BUGS

A picture and associated text silently disappear if a diversion trap set by ­.BP isn’t reached.  Call ­.EP at the end of the document to retrieve it. 
Macros in other packages may break the adjustments made to the line length and indent when text is being placed around a picture.
A missing or improper ­%%BoundingBox comment may cause the frame to be filled incorrectly. 

Plan 9  —  December 11, 1999