DragonFly On-Line Manual Pages

MPICTURES(7)                    Macro Packages                    MPICTURES(7)

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.  This argument
                     is interpreted as a value in inches unless it ends with a
                     `u' scale indicator.
              width  Horizontal size of the frame, current line length by
                     default.  This argument is interpreted as a value in
                     inches unless it ends with a `u' scale indicator.
              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.  This argument is interpreted as a value in
                     inches unless it ends with a `u' scale indicator.
              yoffset
                     Offset the frame from the current baseline, measuring
                     positive downward, default 0i.  This argument is
                     interpreted as a value in inches unless it ends with a
                     `u' scale indicator.

       .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.5x11-inch page.  Nothing prevents the picture from
       being placed off the page.

       The `.psbb' troff request can be used to read the %%BoundingBox comment
       for further processing, as in

              .psbb picture.eps
              .nr scale 4
              .nr y (\n[ury]p-\n[lly]p)/\n[scale]
              .nr x (\n[urx]p-\n[llx]p)/\n[scale]
              .PI picture.eps "\nyu,\nxu"
              .sp \nyu
              picture description

SEE ALSO
       troff(1)

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

NOTES
       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.

Heirloom Documentation Tools        2/2/07                        MPICTURES(7)