MPICTURES(6)                                         MPICTURES(6)

     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 argu-
               ments, represented by "", are interpreted as defaults.
               The arguments are:

               source
                    Name of a PostScript picture file, optionally suf-
                    fixed 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, cen-
                    ter, 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 pic-
                         ture.
                    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 diver-
               sion is explicitly closed by .EP.

     MPICTURES(6)                                         MPICTURES(6)

          .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, mea-
                    suring 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.5x11-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 postpro-
          cessor is replaced by white space.

     BUGS
          A picture and associated text silently disappear if a diver-
          sion 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.