MPICTURES(7)

MPICTURES(7) — picture inclusion macros 🦋

okay so bestie, this is the Miscellaneous Information Manual page for mpictures, aka the picture inclusion macros. We're inserting PostScript pictures into troff(1) documents and honestly? it's giving main-character energy. iconic. 💅✨

---

NAME 💖

mpictures — picture inclusion macros. That's the name, no cap. periodt.

SYNOPSIS ✨

troff -mpictures [ options ] file ...

DESCRIPTION 🦋

Mpictures macros insert PostScript pictures into troff(1) documents. The macros are literally right here:

• .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 (so if you leave a blank, the default vibe steps in). 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 — (default), or 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 — lowkey the backstage pass. 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. automatic-ish, iykyk.

If a PostScript file lacks page-delimiting comments, the entire file is included — the whole thing, bestie. 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, so yeah, off-page is absolutely possible. 🙈

SEE ALSO 🔥

• troff(1) — the reference, the icon, the only SEE ALSO entry. periodt.

DIAGNOSTICS 🩺

A picture file that can't be read by the PostScript postprocessor is replaced by white space. not the glow-up you wanted, but that's the diagnostic. 💀

BUGS 💀

okay bestie, this is the cautionary-tales section — read it, don't skip it, fr fr:

• A picture and associated text silently disappear if a diversion trap set by .BP isn't reached — literally ghosting you. 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. other packages? lowkey messy.
• A missing or improper %%BoundingBox comment may cause the frame to be filled incorrectly. the frame said "not today." 😭

---

that's a wrap on MPICTURES(7), bestie — the footer is just MPICTURES(7), no extra version/date drama. mwah 💋✨