MPICTURES(5)

NAME
mpictures - picture inclusion macros

SYNOPSIS
troff -mpictures [ options ] file ...

DESCRIPTION
A macro package used to include PostScript pictures in troff documents. The package is compatible with many existing troff macro packages and includes the following three macros:

.BP file height width position offset flags label
    Places the picture file in the space set aside by height, width, position, and offset, which together define and position the picture frame. The macro arguments are:

    file
        Pathname of a PostScript picture file. Appending (n) to file selects page number n from a multipage picture file. By default the first page in file is selected.

    height
        Vertical extent of the frame. The default is 3.0i.

    width
        Horizontal extent of the frame. The default is the current length of a line of text.

    position
        One of l, c, or r used to align the left, center, or right of the frame with the corresponding position on the current line of text. The default is l.

    offset
        Moves the frame right (positive) or left (negative) from the selected position. The default is 0i.

    flags
        A string built from one or more of the following:
        a[d]
            rotate the picture clockwise d degrees. If d is omitted 90 degrees is added to the current angle, which starts at zero.
        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   attach picture to the left
        r   right
        t   top
        b   or bottom of the frame

    label
        Place label 1.5 vertical units below the frame.

    If there's room .BP fills text around the frame. Everything destined for either side of the frame first goes into a diversion and only reappears when the accumulated text sweeps past the trap set by .BP or when the diversion is explicitly closed by the .EP macro (below).

    Null arguments, represented by "", are replaced by the defaults as noted above.

.PI file height,width,yoffset,xoffset flags
    A low level macro used by .BP. It can help if you're trying to do things that .BP won't allow or doesn't do well. The two arguments not already described are:

    xoffset
        Moves the frame right (positive) or left (negative) from the left margin. The default is 0i.

    yoffset
        Moves the frame down (positive) or up (negative) from the current baseline. The default is 0i.

    The second argument is a comma separated list of four numbers, and although defaults are available, supplying values for all four numbers is recommended.

.EP Ends a picture started by .BP. An explicit .EP call is not often required. Instead .EP is usually called by springing the trap set by .BP at the bottom of each frame.

Much of what's done depends on file structuring comments commonly found in PostScript files. If the comments needed to isolate a particular page are missing the entire file is included. If a %%BoundingBox comment is missing the picture is assumed to fill an 8.5x11 inch page. A picture file that can't be read when the troff postprocessor runs is replaced by white space. Nothing done in .BP or .PI guarantees the picture hasn't been placed off the page. All dimensions should be explicitly given in inches.

FILES
/usr/lib/tmac/tmac.pictures

SEE ALSO
troff(1), dpost(1), picpack(1)

BUGS

A picture and associated text can silently disappear if the diversion trap set by .BP isn't reached. Including a call to .EP at the end of the paper should recover whatever appears to be missing.

Macros in other packages occasionally break the adjustments made to the line length and indent when text is being placed around a picture.

A missing or improper %%BoundingBox comment often explains why a picture doesn't properly fill the space that's been set aside.