images

Formatter Command Summary

This appendix is divided into ten subsections, each covering a different facet of the nroff/troff formatting system. These sections are:

  • nrof/troff command-line syntax
  • nroff/troff requests
  • escape sequences
  • predefined number registers
  • special characters
  • the ms macro package
  • the mm macro package
  • the tbl preprocessor
  • the eqn preprocessor
  • the pic preprocessor

In the following sections, italics are used for values that you supply. Optional arguments to requests or macros are enclosed in brackets.

▪   nroff/troff Command-Line Syntax   ▪

nroff [options] [files]

-c name Prepend /usr/lib/macros/cmp.n. [dt] .name to files (old versions of nroff only).
-e Space words equally on the line instead of in full multiples of the space character.
-h Use tabs in large spaces.
-i Read standard input after files are processed.
-k name Compact macros and output to [dt].name (old versions of nroff only).
-m name Prepend /usr/lib/tmac/tmac .name to files.
-n n Number first page n.
-o list Print only pages contained in list. Individual pages in list should be separated by commas; a page range is specified by nm; n–indicates from page n to the end.
-q Invoke simultaneous input/output of .rd requests.
-r an Set register a to n.
-s n Stop every n pages.
-T name Output is for device type name. Values are shown in Table B-l. (Check your manual for other devices, especially those supported by the mm command.)
-u n Embolden characters by overstriking n times.
- z Throw away output except messages from .tm request.

images

troff Options

troff [options] [files]

-a Send printable ASCII approximation to standard output. otroff sends its output directly to a connected typesetter unless the -t or -a option is specified, in which case it is sent to standard output, ditroff always writes to standard output.
-b Report phototypesetter status (otroff only).
-c name Prepend /usr/lib/raacros/cmp . t. [dt] .name to files (otroff only).
-f Do not stop the phototypesetter when the formatting run is done (otroff only).
-F dir Format output for device name using the font tables in directory dir instead of /usr/lib/font (ditroff only).
-i Read standard input after files.
-k name Compact macros and output to [dt].name (otroff only).
-m name Prepend /usr/lib/tmac/tmac .name to files.
-n n Number first page n.
-olist Print only pages contained in list. Individual pages in list should be separated by commas. A page range is specified by nm; n–indicates from page n to the end.
-p n Print all characters in point size n, but retain motions for sizes specified in document (otroff only).
-q Do not echo . rd requests.
-ran Assign value n to register a.
-sn Stop every n pages.
-t Send output to standard output instead of directly to the phototypesetter (otroff only).
-T name Format output for device name using the device description and font width tables in /usr/lib/font/devname (ditroff only).
-w If the phototypesetter is busy, wait until it is free (otroff only).

▪   nroff/troff Requests   ▪

.ab [text] Abort and print text as message. If text is not specified, the message User Abort is printed.
.ad [c] Adjust one or both margins if filling is in effect (see .fi). c can be:
images
.af rc Assign format c to register r. c can be:
images
.am xx yy Append to macro xx; end append at call of yy (default yy = . .).
.am xx yy Append to string xx.
.bd fn Overstrike characters in font f, n times.
.bd fsn Overstrike special font s, n times when font f is in effect.
.bp [n] Begin new page. Number next page n.
.br Break to a new line (output partial lines).
.c2 c Set no-break control character to c (default ').
.cc c Set control character to c (default .).
.cf file Copy contents of file into output, uninterpreted (ditroff only).
.ce [n] Center next n lines; if n is 0, stop centering (default n = 1).
.ch xx [n] Change trap position for macro xx to n. If n is absent, remove the trap.
.cs fnm Use constant character spacing for font f of n36 ems. If m is given, the em is taken to be m points.
.cu [n] Continuous underline (including interword spaces) on next n lines. If n is 0, stop underlining. Italicize in troff. (See .ul.)
.da [xx] Divert following text, appending it to macro xx. If no argument, end diversion.
.de xx [yy] Define macro xx. End definition at .yy (default .yy = . .).
.di [xx] Divert following text to newly defined macro xx. If no argument, end diversion.
.ds xx string. Define xx to contain string.
.dt n xx Install diversion trap to invoke macro xx at position n.
.ec [c] Set escape character to c (default \).
.el anything Else portion of if-else. See .ie.
.em xx Set end macro to xx.
.eo Turn escape character mechanism off. See .ec.
.ev [n] Change environment to n. If no argument, restore previous environment (0≤n≤2 = initial value 0).
.ex Exit from formatter.
.f cab Set field delimiter to a and pad character to b.
.fi Turn on fill mode (default: fill is on).
.fl Flush output buffer.
.fp nf Assign font f to position n.
.ft f Change font to f.
.hc[c] Change font to f
.hc [c] Change hyphenation-indication character used with .hw to c (default -).
.hw words Specify hyphenation points for words (e.g., .hw spe-ci-fy).
.hy n Turn hyphenation on (n≥1) or off (n=0).
images
.ie c anything If portion of if-else. See .el.
.if !c anything If condition c is false, do anything.
.if n anything If expression n >0, do anything.
.if !n anything If expression n ≤0, do anything.
.if 'string1' string2' anything If string 1 and string2 are identical, do anything.
-if !'stringl' string2 ' anything If string1 and string2 are not identical, do anything.
.ig yy Ignore following text, up to line beginning with .yy.
.in [±][n] Set indent to n or increment indent by ±n. If no argument, restore previous indent.
.it n xx Set input line count trap to invoke macro xx after n lines of input text have been read.
.lc c Set leader repetition character to c. (See .tc.) Leaders are invoked by \a.
.lg n Turn ligature mode on if n is absent or nonzero.
.ll [±][n] Set line length to n or increment line length by ±n. If no argument, restore previous line length (default 6.5 inches).
.ls n Set line spacing to n. If no argument, restore previous line spacing (initial value 1).
.lt n Set title length to n. If no argument, restore previous value.
.me [c] [n] Set margin character to c, and place it n spaces to the right of margin. If c is missing, turn margin character off. Default for n is 0.2 inches in nroff and 1 em in troff.
.mk [r] Mark current vertical place in register r. Return to mark with .rt, or .sp|\nr.
.na Do not adjust margins. (See .ad.)
.ne n If n lines do not remain on this page, start new page.
.nf No fdling or adjusting of output lines. (See .ad and .fi.)
.nh Turn hyphenation off. (See .hy.)
.nm [n m s i] Number output lines (n≥0) or turn numbering off (n=0).±n sets initial line number; m sets numbering interval; s sets separation of numbers and text; i sets indent of text.
.nn n Do not number next n lines, but keep track of numbering sequence, which can be resumed with .nm+ 0.
.nr r n [m] Assign the value n to number register r and optionally set autoincrement to m.
.ns Turn no-space mode on. (See .rs.)
.nx file Switch to file and do not return to current file.(See .so.)
.os Output saved space specified in previous .sv request.
.pc c Set page number character to c.
.pi cmd Pipe output of troff to cmd instead of to standard out-put.
.pl [±][n] Set page length to n or increment page length by ±n. If no argument, restore default (default 11 inches).
.pm Print names and sizes of all defined macros.
.pn [±][n] Set next page number to n, or increment page number by ±n.
.po [±][n] Offset text a distance of n from left edge of page, or increment the current offset by ±n. If no argument, restore previous offset.
.ps n Set point size to n (troff only).(Default 10 points.)
.rd [prompt] Read input from terminal, after printing optional prompt.
.rm xx Remove macro or string xx.
.rn xx yy Rename request, macro, or string xx to yy.
.rr r Remove register r.
.rs xx yy Restore spacing. (Turn no-space mode off; see .ns.)
.rtn] Return (upward only) to marked vertical place, or to ±n from top of page or diversion.(See .mk.)
.so file Switch out to file, then return to current file. (See .nx.)
.sp n Leave n blank lines (default 1).
.ss n Space character size set to n/36 em (no effect in nroff).
.sv n Save n lines of space; output such space with .os.
.sy cmd [args] Execute UNIX command cmd with optional arguments (ditroff only).
.ta n[t] m[t] Set tab stop at positions n, m, etc. If t is not given, tab is left adjusting; if t is:
     R     Right adjust
     C     Center
.tc c Define tab character as c (e.g., .tc. will draw a string of dots to tab position).
.ti [±][n] Indent next output line n spaces, or increment the current indent by ±n for the next output line.
.tl 'l'c'r' Specify left (l), centered (c), right (r) title.
.tm text Terminal message. (Print text on standard error.)
.tr ab Translate character a to b.
.uf f Underline font set to f (to be switched to by .ul).
.ul [n] Underline (italicize in troff) next n input lines. Do not underline interword spaces.
.VS [n] Set vertical line spacing to n. If no argument, restore previous spacing (default 1/6 inch in nroff, 12 points in troff).
.wh n xx When position n is reached, execute macro xx; negative values of n are with respect to page bottom.

▪   Escape Sequences   ▪

\ To prevent or delay the interpretation of \ .
\e Printable version of the current escape character.
\' ' (acute accent); equivalent to \(aa.
\' ' (grave accent); equivalent to \(ga.
\- – Minus sign in the current font.
\. Period (dot). (See de.)
\ (space) Unpaddable space-size space character.
\0 Digit width space.
\| 1/6-em narrow space character (zero width in nroff).
\^ 1/12-em half-narrow space character (zero width in nroff).
\& Nonprinting, zero-width character.
\! Transparent line indicator.
\" Beginning of comment.
\\$N Interpolate argument 1≤N≤9.
\% Default optional hyphenation character.
\ (xx Character named xx.
\*x, \* (xx Interpolate string x or xx.
\a Noninterpreted leader character for use in macros.
\b 'abc...' Bracket building function—stack abc... vertically.
\c Interrupt text processing.
\d Downward 1/2-em vertical motion (1/2 line in nroff).
\D 'l x,y' Draw a line from current position to coordinates x,y (ditroff only).
\D ' c d' Draw circle of diameter d with left edge at current position (ditroff only).
\D'e d1 d2' Draw ellipse with horizontal diameter d1 and vertical diameter d2, with left edge at current position (ditr-off only).
\D' a x1 y1 x2 y2' Draw arc counterclockwise from current position, with center at x1,y1 and endpoint at x1+x2,y1+y2 (ditroff only).
\ D' ~ x1 y1 x2 yx..' Draw spline from current position through the specified coordinates (ditroff only).
\fx,\f (xx,\fN Change to font named x or xx or to position N.
\h'N' Local horizontal motion; move right N (negative left).
\H 'n' Set character height to n points, without changing width (ditroff only).
\jx Mark horizontal place on output line in register x.
\kx Mark horizontal place on input line in register x.
\l'Nc' Horizontal line drawing function (optionally with c, default _ ).
\L'Nc' Vertical line drawing function (optionally with c, default l).
\nx, \n (xx Interpolate number register x or xx.
\o 'abc...' Overstrike characters a, b, c...
\P Break and spread output line.
\r Reverse 1-em vertical motion (reverse line in nroff).
\sN,\s±N Point-size change function.
\S 'n' Slant output n degrees to the right (ditroff only). Negative values slant to the left. A value of zero turns off slanting.
\t Noninterpreted horizontal tab.
\u Reverse (up) 1/2-em vertical motion (1/2 line in nroff).
\v 'N' Local vertical motion; move down N (negative up).
\w 'string' Interpolate width of string.
\x'N' Extra line-space function (negative before, positive after).
\ zc Print c with zero width (without spacing).
\{ Begin conditional input.
\} End conditional input.
\(newline) Concealed (ignored) newline.
\X X, any character not listed above.

▪   Predefined Number Registers   ▪

Read-Only Registers

.$ Number of arguments available at the current macro level.
.$$ Process ID of troff process (ditroff only).
.A Set to 1 in troff, if –a option used; always 1 in nroff.
.H Available horizontal resolution in basic units.
.T In nroff, set to 1 if -T option used; in troff, always 0; in ditroff, you can print the value of -T with the string \ * (.T.
.V Available vertical resolution in basic units.
.a Extra line space most recently utilized using \x'N'.
.c Number of lines read from current input file.
.d Current vertical place in current diversion; equal to nl if no diversion.
.f Current font as physical quadrant (1 to 4 in otroff; no limit in ditroff).
.h Text baseline high-water mark on current page or diversion.
.i Current indent.
.j Current adjustment type (0=.adl or .na; 1=.adb; 3=.adb; 3=.adc; 5=.adr).
.l Current line length.
.n Length of text portion on previous output line.
.o Current page offset.
.P Current page length.
.s Current point size.
.t Distance to the next trap.
.u Equal to 1 in fill mode and 0 in no-fill mode.
.V Current vertical line spacing.
.w Width of previous character.
.X Reserved version-dependent register.
.y Reserved version-dependent register.
.z Name of current diversion.

Read/Write Registers

% Current page number.
ct Character type (set by width function).
dl Width (maximum) of last completed diversion.
dn Height (vertical size) of last completed diversion.
dw Current day of the week (1 to 7).
dy Current day of the month (1 to 31).
hp Current horizontal place on input line.
ln Output line number.
mo Current month (1 to 12).
nl Vertical position of last printed text baseline.
sb Depth of string below baseline (generated by width function).
st Height of string above baseline (generated by width function).
yr Last two digits of current year.

▪   Special Characters   ▪

On the Standard Fonts

The following special characters are usually found on the standard fonts:

' ' close quote
' ' open quote
\(em 3/4 em dash
- \ hyphen
- \ (hy hyphen
- \- current font minus sign
\ (bu bullet
\ (sq square
- \ (ru rule
1/4 \ (14 1/4
1/2 \ (12 1/2
3/4 \ (34 3/4
fi \ (fi fi ligature
fl \ (fl fl ligature
ff \ (ff ff ligature
ffi \ (Fi ffi ligature
ffl \ (Fl ffl ligature
o \ (de degree
\ (dg dagger
' \ (fm foot mark
¢ \ (ct cent sign
\ (rg registered trademark
© \ (co copyright

On the Special Font

The following characters are usually found on the special font except for the uppercase Greek letter names followed by † which are mapped into uppercase English letters in whatever font is mounted on font position one (default is Times Roman).

Miscellaneous Characters

§ \ (sc section
' \ (aa acute accent
' \ (ga grave accent
\ (ul underrule
\ (-> right arrow
\ (<- left arrow
\ (ua up arrow
\ (da down arrow
| \ (br box rule
\ (dd double dagger
images \ (rh right hand
images \ (lh left hand
\ (ci circle

Mathematic Symbols

+ \ (pl math plus
\ (mi math minus
= \ (eq math equals
* \ (** math star
/ \ (sl slash (matching backslash)
images \ (sr square root
\ (rn root en extender
\ (>= greater than or equal to
\ (<= less than or equal to
\(== identically equal
\(~= approx equal
~ \ (ap approximates
\(! = not equal
× \ (mu multiply
÷ \ (di divide
± \ (+- plus-minus
\ (cu cup (union)
\ (ca cap (intersection)
images \ (sb subset of
images \ (sp superset of
images \ (ib improper subset
images \ (ip improper superset
\ (if infinity
images \ (pd partial derivative
\ (gr gradient
images \ (no not
\ (is integral sign
\ (pt proportional to
Ø \ (es empty set
images \ (mo member of
| \ (or or

Bracket Building Symbols

images \ (It
\ (lk
\ (lb
\ (rt
\ (rk
\ (rb
\ (lc
\ (bv
\ (lf
\ (rc
\ (rf
left top of large curly bracket
left center of large curly bracket
left bottom of large curly bracket
right top of large curly bracket
right center of large curly bracket
right bottom of large curly bracket
left ceiling (top) of large square bracket
bold vertical
left floor (bottom) of large square bracket
right ceiling (top) of large square bracket
right floor (bottom) of large square bracket

Greek Characters

α \ (*a alpha
β \ (*b beta
γ \ (*g gamma
δ \ (*d delta
ε \ (*e epsilon
ζ \ (*z Zetat
η \ (*y eta
θ \ *h theta
ι \ (*i iota
κ \ (*k kappa
λ \ (*l lambda
μ \ (*m mu
ν \ (*n nu
ξ \ (*c xi
Ό \ (*o omicron
π \ (*p pi
ρ \ (*r rho
σ \ (*s sigma
ς \ (ts terminal sigma
τ \ (*t tau
υ \ (*u upsilon
Φ \ (*f phi
χ \ (*x chi
ψ \ (*q Psi
ω \ (*w omega
Α \ (*A Alpha†
Β \ (*B Beta†
Γ \ (*G Gamma
Δ \ (*D Delta
Ε \ (*E Epsilon†
Ζ \ (*Z Zeta†
Η \ (*Y Eta†
Θ \ (*H Theta
Ι \ (*I Iota†
κ \ (*K Kappa†
Λ \ (*L Lambda
Μ \ (*M Mu†
Ν \ (*N Nu†
Ξ \ (*C Xi
Ο \ (*O Omicron†
Π \ (*P Pi
Ρ \ (*R Rho†
Σ \ (*S Sigma
Τ \ (*T Tau†
Υ \ (*U Upsilon
Φ \ (*F Phi
Χ \ (*X Chi†
Ψ \ (*Q Psi
Ω \ (*W Omega

▪   The ms Macros   ▪

Summary of ms Macros

.1C Return to single-column format.
.2C Start two-column format.
.AB Begin abstract.
.AE End abstract.
.AI name Name of author-s institution (used in cover sheet).
.AU name Author-s name (used in cover sheet).
.B [text] Print text in boldface. If text is missing, equivalent to .ft 3.
.B1 Enclose following text in a box.
.B2 End boxed text.
.BX word Surround word in a box.
.DA Print date on each page.
.DS Start displayed text.
.DSB Start left-justified block, centered.
.DSC Start centered display.
.DSL Start left-centered display.
.DE End displayed text.
.EQ Begin equation.
.EN End equation.
.FS Start footnote.
.FE End footnote.
.I [text] Print text in italics. If text is missing, equivalent to .ft 2.
.IP label n Indent paragraph n spaces with hanging label.
.KS Start keep.
.KE End of keep or floating keep.
.KF Begin floating keep.
.LG Increase type size by two points (troff only).
.LP Start block paragraph.
.ND Change or omit date.
.NH n Numbered section heading, level n.
.NL Restore default type size (troff only).
.PP Start indented paragraph.
.R [text] Print text in roman. If text is missing, equivalent to .ft 1.
.RP Initiate title page for a “released paper.”
.RS Increase relative indent one level. Use with .IP.
.RE End one level of relative indent.
.SG Signature line.
.SH Unnumbered section heading.
.SM Decrease type size by two points (troff only).
.TL Title line.
.TS [H] Start table. H will put table header on all pages. Use this option with following .TH.
.TH Table header ends. Must be used with .TS H.
.TE End table.
.UL Underline following text, even in troff.

Internal Macros Worth Knowing About

.IZ Basic initialization; executed automatically before any text is processed. It is then removed, and cannot be invoked again.
.RT Reset. Invoked by all paragraph macros, plus .RS, .RE, .TS, .TE, .SH, and .NH.Resets various values to defaults stored in number registers listed below.
.BG Prints cover sheet, if any. Also performs some special first page initialization. Invoked once by the very first .RT in a document.
.NP New page. Invoked at the top of each page. Performs various page top resets, and calls .PT.
.PT Page titles. Contains running headers. Can be redefined. Invoked by .NP at \n (HMu from the top of the page.
.BT Bottom titles. Continuous running footers. Invoked by trap at \n (FMu/2u from the bottom of the page.
.FO Footer. The bottom of the text on the page. Invoked by trap at \n (FMu.

Number Registers Containing Page Layout Defaults

CW Column width (default 7/15 of line length).
FL Footnote length (default 11/12 of line length).
FM Bottom margin (default 1 inch).
GW Intercolumn gap width for multiple columns (default 1/15 of line length).
HM Top margin (default 1 inch).
LL Line length (default 6 inches).
LT Title length (default 6 inches).
PD Paragraph spacing (default 0.3 of vertical spacing).
PI Paragraph indent (default 5 ens).
PO Page offset (default 26/27 inches).
PS Point size (default 10 points).
VS Vertical line spacing (default 12 points).

Predefined and User-Definable Strings

DY The current date.
LH Left header, printed by .tl '\\*(LH'\\*CH'\\*(RH' in PT macro. Null unless user-defined.
CH Center header, printed by .tl '\\*(LH'\\*CH'\\*(RH' in PT macro. Null unless user-defined.
RH Right header, printed by .tl '\\*(LH'\\*CH'\\*(RH' in PT macro. Null unless user-defined.
LF Left footer, printed by .tl '\\*(LH'\\*CH'\\(RH' in BT macro. Null unless user-defined.
CF Center footer, printed by .tl '\\*(LH'\\*CH'\\RH' in BT macro. Contains PN by default.
RF Right footer, printed by .tl '\\*(LH'\\*CH'\\RH' in BT macro. Contains PN by default.

Reserved Macro and String Names

The following macro and string names are used by the ms package. Avoid using these names for compatibility with the existing macros. An italicized n means that the name contains a numeral (generally the interpolated value of a number register).

images

The following number register names are used by the ms package. An italicized n means that the name contains a numeral (generally the interpolated value of another number register).

images

Note that with the exception of [c and [o, none of the number register, macro, or string names contain lowercase letters, so lowercase or mixed case names are a safe bet when you’re writing your own macros.

▪   The mm Macros   ▪

Summary of mm Macros

.1C Return to single-column format.
.2C Start two-column format.
.AS [x][n] Start abstract type x, indent n spaces. (Used with .TM and .RP only.) (Types: 1=abstract on cover sheet and first page; 2=abstract only on cover sheet; 3=abstract only on Memorandum for File cover sheet.) End with .AE.
.AE End abstract. Begin with .AS.
.AF [company name]
Alternate format for first page. Change first page “Subject/Date/From” format. If argument is given, other headings are not affected. No argument suppresses company name and headings.
.AL [x][n] Start list type x (1, A, a, I, or i), indent n spaces. If third argument is 1, don’t put a blank line between items. Default is numbered listing, indented 5 spaces.
.AT title Author’s title follows.
.AU name Author’s name and other information follows.
.AV name Approval signature line for name.
.B [w][x]... Set w in bold (underline in nroff) and x in previous font; up to six arguments.
.BS Begin block of text to be printed at bottom of page, after footnotes (if any), but before footer.
.BE End bottom block and print after footnotes (if any), but before footer.
.BI [w] [x] Set w in bold (underline in nroff) and x in italics; up to 6 arguments.
.BL [n] [1] Start bullet list and indent text n spaces. If second argument is 1, don’t put a blank line between items.
.BR [w] [x] Set w in bold (underline in nroff) and x in roman; up to six arguments.
.CS [pgs] [other] [tot] [figs] [tbls] [ref]
Cover sheet numbering information.
.DF [x] [y] Start floating display of type x and mode y, with indent n. (Default is no indent, no-fill mode.) End with .DE. x is: L (no indent), I (indent standard amount), C (center each line individually), or CB (center as a block), y is: N (no-fill mode) or F (fill mode).
.DS Start floating or static display of type x and mode y, with indent n. Type and mode are as in .DF. End with .DE.
.DE End floating or static display started with .DS or .DF.
.DL [n] [I] Start dashed list and indent text n spaces. If second argument is 1, no space between items.
.EC [caption] [n] [f]
Equation caption. Arguments optionally override default numbering, where flag f determines use of number n. If f=0 (default), n is a prefix to number; if f=1, n is a suffix; if f=2, n replaces number.
.EF [text] Print text as the footer on all even pages. text has the format: ’left’ center ’right’.
.EH [text] Print text as the heading on all even pages. text has the format: ’left’ center ’right’.
.EQ [text] Start equation display using text as label.
.EN End equation display.
.EX [caption] [n] [f]
Exhibit caption. Arguments optionally override default numbering, where flag f determines use of number n. If f=0 (default), n is a prefix to number; if f=1, n is a suffix; if f=2, n replaces number.
.FC [text] Use text for formal closing.
.FD [0-11] Setup default footnote format.
.FS [c] Start footnote using c for indicator. Default is numbered footnote.
.FE End footnote.
.FG [title] Figure title follows.
.Hn [heading] Numbered heading level n follows.
.HC [c] Use c as hyphenation indicator.
.HM [mark] Heading mark style follows arabic (1 or 001), roman (i or I), or alphabetic (a or A).
.HU heading Unnumbered heading follows.
.HX User-supplied exit macro before printing heading.
.HY User-supplied exit macro in middle of printing heading.
.HZ User-supplied macro after heading.
.I [w] [x] Set w in italics (underline in nroff) and x in previous font. Up to six arguments.
.IB [w] [x] Set w in italics (underline in nroff) and x in bold. Up to six arguments.
.IR [w] [x] Set w in italics (underline in nroff) and x in roman.
.LB n m pad type [mark] [LI-space] [LB-space]
List beginning. Allows complete control over list format. It takes the following arguments:

n — Text indent.

m — Mark indent.

pad — Padding associated with mark.

type — If 0, use the specified mark. If nonzero, and mark is 1, A, a, I, i, list will be automatically numbered or alphabetically numbered or alphabetically sequenced. In this case, type controls how the mark will be displayed. For example, if mark is 1, type will have the following results:

images

mark — The symbol or text that will be used to start each list entry. mark can be null (creates hanging indent), a text string, or 1, A, a, I, or i to create an automatically numbered or lettered list. Format of the mark will be affected by type.

LI-space — The number of blank lines to be output between each following .LI macro (default 1).

LB-space — The number of blank lines to be output by the LB macro itself (default 0).

.LC [n] Clear list level n.
.LE End list.
.LI [mark] Item in list and specify mark.
.ML mark [n] [I]
Start marked list, indent n spaces. If third argument is 1, no space between items in list.
.MT [type] [title]
Specify memorandum type and title. type is:

" " = No type

0 = No type

1 = Memorandum for file (default)

2 = Programmer’s notes

3 = Engineer’s notes

4 = Released paper

5 = External letter

string = string is printed.

title is user-supplied text prefixed to page number.
.ND date New date. Change date to date.
.nP Double-line indent on paragraph start.
.NS [type] Notation start. Specify notation type. type is:

" " = Copy to

0 = Copy to

1 = Copy (with att.) to

2 = Copy (no att.) to

3 = Att.

4 = Atts.

5 = Enc.

6 = Encs.

7 = Under Separate Cover

8 = Letter to

9 = Memorandum to

10 = Copy (with atts.) to

11= Copy (without atts.) to

12= Abstract Only to

13= Complete Memorandum to

string = Copy string to

.NE Notation end.
.OF [text] Print text as the footer on all odd pages, text has the format: ’left’ center ’right’.
.OH [text] Print text as the heading on all odd pages. text has the format: ’left’ center ’right’.
.OK [topic] Other keywords. Specify topic for TM cover sheet.
.OP Force an odd page.
.P [type] Start paragraph type, type is: 0 = left justified (default), 1 = indented, 2 = indented except after .H, .LC, .DE.
.PF [text] Print text as the page footer on all pages. text has the format: ’left’ center ’right’.
.PH [text] Print text as the page heading on all pages. text has the format: ’left’ center ’right’.
.PM [type] Proprietary marking on each page (type: P=PRIVATE; N=NOTICE).
.PX Page-heading user exit.
.R Return to roman font (end underlining in nroff).
.RB [w] [x] Set w in roman and x in bold.
.RD [input] Read input from terminal.
.RI [w] [x] Set w in roman and x in italics.
.RS [arg] Start automatically numbered reference. arg manually specified reference number.
.RF End of reference text.
.RL [n] [1] Start reference listing, indent text n spaces. If second argument is 1, no space between list items.
.RP Produce reference page.
.S [n] [m] Set point size to n and vertical spacing to m (troff only) (defaults: 10 or 12). Alternatively, either argument can be specified as ±n/m to increment/decrement current value, D to use default, C to use current value, P to use previous value.
.SA [n] Set right margin justification to n. n is: 0 = no justification or 1 = justification. (Defaults: no justification for nroff, justification for troff.)
.SG [name] Use name for signature line.
.SK n Skip n pages.
.SM x[y][z] Reduce string x by one point. If strings x, y, and z are specified, y is reduced by one point.
.SP [n] Leave n blank vertical spaces.
.TB [title][n][f] Supply table title. Arguments optionally override default numbering, where flag f determines use of number n. If f=0 (default), n is a prefix to number; if f=1, n is a suffix; if f=2, n replaces number.
.TS [H] Start table. H will put table header on all pages. Use this option with following .TH.
.TH N Table header ends. Must be used with .TS H. N = only print table headers on new page.
.TE End table.
.TC [level] [level] [tab] [head1]...
Generate table of contents.
.TL Title of memorandum follows on next line.
.TM [n] Number a technical memorandum n. (Up to nine may be specified.)
.TP Top-of-page macro.
.TX User-supplied exit for table-of-contents titles.
.TY User-supplied exit for table-of-contents header.
.VL n [m] [I] Start variable item list. Indent text n spaces and mark m spaces. If third argument is 1, no space between list items.
.VM [n] [m] Add n lines to top margin and m lines to bottom.
.WC [x] Change column or footnote width to x. x is:

images

Predefined String Names

BU Bullet; same as \ (bu.
Ci List of indents for table of contents levels.
DT Current date, unless overridden. Month, day, year (e.g., July 28, 1986).
EM Em dash string (em dash in troff and a double hyphen in nroff).
F Footnote number generator.
HF Fonts used for each level of heading (1=roman, 2=italic, 3=bold).
HP Point size used for each level of heading.
Le Title set for List Of Equations.
Lf Title set for List Of Figures.
Lt Title set for List Of Tables.
Lx Title set for List Of Exhibits.
RE SCCS Release and Level of mm.
Rf Reference number generator.
Rp Title for references.
TM Trademark string. Places the letters TM one-half line above the text that it follows.

Number Registers Used in mm

A dagger () next to a register name indicates that the register can only be set from the command line or before the nun macro definitions are read by the formatter. Any register that has a single-character name can be set from the command line.

A† If set to 1, omits technical memorandum headings and provides spaces appropriate for letterhead. See .AF macro.
Au Inhibits author information on first page. See .AU macro.
C† Flag indicating type of copy (original, draft, etc.).
Cl Level of headings saved for table of contents (default 2). See .TC macro.
Cp If set to 1, list of figures and tables appear on same page as table of contents. Otherwise, they start on a new page. (Default is 1.)
D† If set to 1, sets debug mode (default 0). If set, mm will continue even when it encounters normally fatal errors.
De If set to 1, ejects page after each floating display. (Default is 0.)
Df Format of floating displays. See .DF macro.
Ds Sets the pre- and post-space used for static displays.
E† Font for the Subject/Date/From: 0=bold; 1=roman. (Default is 0.)
Ec Equation counter, incremented for each .EC macro.
Ej Heading level for page eject before headings. (Default is 0, no eject.)
Eq If set to 1, places equation label at left margin. (Default is 0.)
Ex Exhibit counter, incremented for each .EX macro.
Fg Figure counter, incremented for each .FG macro.
Fs Vertical spacing between footnotes.
H1-H7 Heading counters for levels 1-7, incremented by the .H macro of corresponding level or the .HU macro if at level given by the Hu register. The H2-H7 registers are reset to 0 by any .H (or .HU) macro at a lower-numbered level.
Hb Level of heading for which break occurs before output of body text (default 2 lines).
Hc Level of heading for which centering occurs (default 0).
Hi Indent type after heading. (Default 1=paragraph indent.) Legal values are: 0 left justified, 1 indented, 2 indented except after .H, .LC, .DE. (Default is 0.)
Hs Level of heading for which space after heading occurs. (Default = 2; .H2.)
Ht Numbering type of heading: single (1) or concatenated (0). (Default is 0.)
Hu Sets level of numbered heading that unnumbered heading resembles. (Default =2; .H2.)
Hy Sets hyphenation. If set to 1, Hy enables hyphenation. (Default is 0.)
L† Sets length of page. (Default is 66v.)
Le Flag for list of equations following table of contents. 0 = do not print; 1 = print. (Default is 0.)
Lf Flag for list of figures following table of contents. 0 = do not print; 1 = print. (Default is 0.)
Li Default indent of lists. (Default is 5.)
Ls List spacing between items by level. (Default = 6, spacing between all levels of list.)
Lt Flag for list of tables following table of contents. 0 = do not print; 1 = print (Default is 0.)
Lx Flag for list of exhibits following table of contents. 0 = do not print; 1 = print (Default is 0.)
N† Page numbering style. 0=header on all pages; 1=header printed as footer on page 1; 2=no header on page 1; 3=section page as footer; 4=no header unless .PH defined; 5=section page and section figure as footer. (Default is 0.)
Np Numbering style for paragraphs. 0 = unnumbered; 1 = numbered.
O Offset of page. For nroff, this value is an unsealed number representing character positions. Default is 9 (7.5i). For troff, this value is scaled. Default is .5i.
Oc Table of contents page numbering style. 0=lowercase roman; 1=arabic. (Default is 0.)
Of Figure caption style. 0=period separator; 1=hyphen separator. (Default is 0.)
P Current page number.
Pi Amount of indent for paragraph. (Default is 5 for nroff, 3 for troff.)
Ps Amount of spacing between paragraphs. (Default is 3v.)
Pt Paragraph type. Legal values are: 0 left justified, 1 indented, 2 indented except after .H, .LC, .DE. (Default is 0.)
Pv Inhibits “PRIVATE” header. See .PV macro for values.
Rf Reference counter, incremented for each .RS.
S† Default point size for troff. Default is 10. (Vertical spacing is \n5+2.)
Si Standard indent for displays. (Default is 5 for nroff, 3 for troff.)
T† Type of nroff output device. Causes register settings for specific devices.
Tb Table counter, incremented for each .TB.
U* Underlying style (nroff) for .H and .HU. If not set, use continuous underline; otherwise, don’t underline punctuation and white space. (Default is 0.)
w† Width of page (line and title length). (Default is 6i.)

Other Reserved Macro and String Names

In mm, the only macro and string names you can safely use are names consisting of a single lowercase letter, or two character names whose first character is a lowercase letter and whose second character is anything but a lowercase letter. Of these, c2 and nP are already used.

▪   tbl Command Characters and Words   ▪

.TS Start table.
.TE End table.
.TS H Used when the table will continue onto more than one page.
Used with .TH to define a header that will print on every page.
.TH With .TS H, ends the header portion of the table.
.T& Continue table after changing format line.

Options

Options affect the entire table. The options should be separated by commas, and the option line must be terminated by a semicolon.

center Center with current margins.
expand Flush with current right and left margins.
(blank) Flush with current left margin (default).
box Enclose table in a box.
doublebox Enclose table in two boxes.
allbox Enclose each table entry in a box.
tab (x) Define the tab symbol as x.
linesize (n) Set lines or rules (e.g., from box) to n point type.
delim (xy) Recognize x and y as the eqn delimiters.

Format

The format line affects the layout of individual columns and rows of the table. Each line contains a key letter for each column of the table. The column entries should be separated by spaces, and the format section must be terminated by a period. Each line of format corresponds to one line of the table, except for the last, which corresponds to all following lines up to the next .T&, if any.

Key letters

c Center.
l Left justify.
r Right justify.
n Align numerical entries.
a Align alphabetic subcolumns.
s Horizontally span previous column entry across this column.
^ Vertically continue entry from previous row down through this row.

Other choices (must follow a key letter)

b Boldface. Must be followed by a space.
i Italics. Must be followed by a space.
pn Point size n.
t Begin any corresponding vertically spanned table entry at the top line of its range.
e Equal width columns.
w(n) Minimum column width. Also used with text blocks, n can be given in any acceptable troff units.
vn Vertical line spacing. Used only with text blocks.
n Amount of separation between columns (default is 3n).
| Single vertical line. Typed between key letters.
|| Double vertical line. Typed between key letters.
- Single horizontal line. Used in place of a key letter.
= Double horizontal line. Used in place of a key letter.

Data

The data portion includes both the heading and text of the table. Each table entry must be separated by a tab symbol.

.xx troff commands may be used (such as .sp # and .ce #). Do not use macros, unless you know what you’re doing.
\ As last character in a line, combine following line with current line (\ is hidden).
\^ Vertically spanned table entry. Span table entry immediately above over this row.
_ or = As the only character in a line, extend a single or double horizontal line the full width of the table.
\$_ or \$ = Extend a single or double horizontal line the full width of the column.
\_ Extend a single horizontal line the width of the contents of the column.
\Rx Print x’s as wide as the contents of the column.
...T{ Start text block as a table entry. Must be used with wn, column width option.
...T} End text block.

▪   eqn Command Characters   ▪

.EQ Start typesetting mathematics
.EN End typesetting mathematics

Character Translations

The following character sequences are recognized and translated as shown.

> = approx
< = nothing
= = cdot .
! = times ×
+ − ± del
− > grad
< − ... ...
<< , . . . , , . . . ,
>> sum Σ
inf int
partial prod
half ½ union
prime inter

Digits, parentheses, brackets, punctuation marks, and the following words are converted to roman font when encountered:

sin cos tan sinh cosh tanh arc
max min lin log ln exp
Re Im and if for det

Greek letters can be printed in uppercase or lowercase. To obtain Greek letters, simply spell them out in the case you want:

alpha α sigma σ
beta β tau τ
gamma γ upsilon υ
delta δ phi Φ
epsilon ε chi χ
zeta ζ psi Ψ
eta η omega ω
theta θ GAMMA Γ
iota ι DELTA Δ
kappa κ THETA Θ
lambda λ LAMBDA Λ
mu μ XI Ξ
nu ν PI Π
xi ξ SIGMA Σ
omicron Ο UPSILON Υ
Pi π PHI Φ
rho ρ PSI Ψ
OMEGA Ω

The following words translate to marks on the tops of characters.

x dot Images x vec Images
x dotdot Images x dyad Images
x hat Images x bar Images
x tilde Images x under Images

Words Recognized By eqn

above Separate the pieces of a pile or matrix column.
back n Move backwards horizontally n 1/100’s of an em.
bold Change to bold font.
ccol Center a column of a matrix.
col??? Used with a preceding l or r to left or right adjust the columns of the matrix.
cpile Make a centered pile (same as pile).
define Create a name for a frequently used string.
delim Define two characters to mark the left and right ends of an eqn equation to be printed in line.
down n Move down n 1/100’s of an em.
fat Widen the current font by overstriking it.
font x Change to font x, where x is the one-character name or the number of a font.
from Used in summations, integrals, and similar constructions to signify the lower limit.
fwd n Move forward horizontally n 1/100’s of an em.
gfont x Set a global font x for all equations.
gsize n Set a global size for all equations.
up n Move up n 1/100’s of an em.
italic Change to italic font.
lcol Left justify a column of a matrix.
left Create large brackets, braces, bars, etc.
lineup Line up marks in equations on different lines.
lpile Left justify the elements of a pile.
mark Remember the horizontal position in an equation. Used with lineup.
matrix Create a matrix.
ndefine Create a definition which only takes effect when neqn is running.
over Make a fraction.
pile Make a vertical pile with elements centered above one another.
rcol Right adjust a column of a matrix.
right Create large brackets, braces, bars, etc.
roman Change to roman font.
rpile Right justify the elements of a pile.
size n Change the size of the font to n.
sqrt Draw a square root sign.
sub Start a subscript.
sup Start a superscript.
tdefine Make a definition that will apply only for eqn.
to Used in summations, integrals, and similar constructions to signify the upper limit.
~ Force extra space into the output.
^ Force a space one half the size of the space forced by ~.
{ } Force eqn to treat an element as a unit.
". . ." A string within quotation marks is not subject to alterations by eqn.

Precedence

If you don’t use braces, eqn will do operations in the order shown in the following list.

dyad vec under bar tilde hat dot dotdot
fwd  back  down  up
fat  roman  italic  bold  size
sub  sup  sqrt  over
from  to

These operations group to the left:

over  sqrt  left  right

All others group to the right.

▪   The pic Preprocessor   ▪

In pic there are often dozens of ways to draw a picture, not only because of the many permissible abbreviations, but because pic combines the language of geometry with English. You can specify a line, for example, with direction, magnitude, and starting point, yet often achieve the same effect by simply stating, “from there to there.”

Full descriptions of primitive objects in pic can be ended by starting another line, or by the semicolon character (;). A single primitive description can be continued on the next line, however, by ending the first with a backslash character (\). Comments may be placed on lines beginning with #.

pic Macros

The following macros are used to delimit pic input from the body of the source file. Only text within these macros will be processed by pic.

.PS [h [w]] Start pic description, h and w, if specified, are the desired height and width of the picture; the full picture will expand or contract to fill this space.
.PS <file Read contents of file in place of current line.
.PE End pic description.
.PF End pic description and return to vertical position before matching PS.

Declarations

At the beginning of a pic description, you may declare a new scale, and declare any number of variables.

pic assumes you want a 1-to-1 scale, with 1 = one inch. You can declare a different scale, say 1 = one-nth of an inch, by declaring, scale = n.

pic takes variable substitutions for numbers used in the description. Instead of specifying, line right n, you may use a lowercase character as a variable, for example, a, by declaring at the top of the description:

a = n

You may then write line right a.

Primitives

Primitives may be followed by relevant options. Options are discussed later in this section.

arc [cw] [options] [“text”]

A fraction of a circle. (Default = 1/4 of a circle.) The cw option specifies a clockwise arc; default is counterclockwise.

arrow [options] [“text”] [then . . . ]

Draw an arrow. Essentially the same as line −>.

box [options] [“text”]

Draw a box.

circle [options] [“text”]

Draw a circle.

ellipse [options] [“text”]

Draw an ellipse.

line [options] [“text”] [then . . .]

Draw a line.

move [options] [“text”]

A move of position in the drawing. (Essentially, an invisible line.)

spline [options] [“text”] [then . . .]

A line, with the feature that a “then” results in a gradual (sloped) change in direction.

text

Text centered at current point.

Options

right [n] Specifies direction of primitive; default is direction in which
left [n] the previous description had been heading. Diagonals result by
up [n] using two directions on the option line. Each direction can be
down [n] followed by a specified length n.
rad n diam n Specifies a primitive to have radius n (or diameter n).
ht n Specifies the height or width of the primitive to be n. For an
wid n arrow, line, or spline, refers to size of arrowhead.
same Specifies a primitive of the same dimensions of the most recent matching primitive.
at point Specifies primitive to be centered at point.
with .position at point
Specifies the designated position of the primitive to be at point.
from point 1 to point2
Specifies the primitive to be drawn from point 1 to point2. Points may be expressed as Cartesian coordinates or in respect to previous objects.
− > Specify the arrowhead to be directed forwards.
<− Specify the arrowhead to be directed backwards.
<−> Specify the arrowhead to be directed both ways.
chop n m Chop off n from beginning of primitive, and m from end. With only one argument, the same value will be chopped from both ends.
dotted Specifies the primitive to be drawn dotted, dashed, or to be
dashed invis invisible. Default is solid line.
then... Continue primitive in a new direction. Relevant only to lines, splines, moves, and arrows.

Text

Place text within quotation marks. To break the line, break into two (or more) sets of quotation marks. Text always appears centered within the object, unless given one of the following arguments:

l just Text appears left justified to the center.
r just Text appears right justified to the center.
above Text appears above the center.
below Text appears below the center.

Object Blocks

A complex object that is the combination of several primitives (for example, an octagon) can be treated as a single object by declaring it as a block:

Object:[
 description
   .
   .
   .
]

Brackets are used as delimiters. Note that the object is declared as a proper noun, hence it should begin with a capital letter.

Macros

The same sequence of commands can be repeated by using macros. The syntax is:

define sequence %
   description
     .
     .
     .
   %

In this example, we have used the percent sign (%) as the delimiter, but any character that is not in the description may be used.

Macros can take variables, expressed in the definition as “$1” through “$9”. Invoke the macro with the syntax: sequence(value1,value2,...)

Positioning

In a pic description, the first action will begin at (0,0), unless otherwise specified with coordinates. Thus, the point (0,0) will move down and right on the drawing, as objects are placed above and to the left of the first object.

All points are ultimately translated by the formatter into x- and y-coordinates. You may therefore refer to a specific point in the picture by incrementing or decrementing by coordinates, i.e., 2nd ellipse - (3,1).

You may refer to the x- and y-coordinates of an object by placing .x or .y at the end. For example, last box.x will refer to the x-coordinate of the most recent box drawn. Some of the physical attributes of the object may also be referred to similarly, as follows:

.x X-coordinate of object’s center.
.y Y-coordinate of object’s center.
.ht Height of object.
.wid Width of object.
.rad Radius of object.

Unless otherwise positioned, each object will begin at the point where the last object left off. If a command (or sequence of commands) is set off by braces ({ }), however, pic will then return to the point before the first brace.

Positioning between Objects

When referring to a previous object, you must use proper names. This can be done two ways:

Images   By referring to it by order, e.g., 1st box, 3rd box, last box, 2nd last box, etc.

Images   By declaring it with a name, in initial caps, on its declaration line, e.g., Line1: line 1.5 right from last box.sw

To refer to a point between two objects, or between two points on the same object, you may write: fraction of the way between first.position and second.position or (abbreviated) fraction<first.position,second.position>

Corners

When you refer to a previous object, pic will assume that you mean the center of the object, unless you use a corner to specify a particular point on the object. The syntax is:

.corner of object

for example, .sw of last box. You can also use an abbreviated syntax:

object.corner

for example, last box.sw.

These corners may be:

n North (same as t)
s South (same as b)
e East (same as r)
w West (same as l)
ne Northeast
nw Northwest
se Southeast
sw Southwest
t Top (same as n)
b Bottom (same as s)
r Right (same as e)
l Left (same as w)
start Point where drawing of object began
end Point where drawing of object ended

You may also refer to the upper right, upper left, lower right, and lower left of an object.

Numerical Operators

Several operators are functional in pic. These are:

+ Addition
Subtraction
* Multiplication
/ Division
% Modulo

Default Values

arcrad 0.25 ellipsewid 0.75
arrowwid 0.05 linewid 0.5
arrowht 0.1 lineht 0.5
boxwid 0.75 movewid 0.5
boxht 0.5 moveht 0.5
circlerad 0.25 scale 1
dashwid 0.05 textht 0
ellipseht 0.5 textwid 0

Get UNIX° TEXT PROCESSING now with O’Reilly online learning.

O’Reilly members experience live online training, plus books, videos, and digital content from 200+ publishers.