1groff_ms(7) Miscellaneous Information Manual groff_ms(7)
2
6 groff_ms - GNU roff manuscript macro package for formatting documents
7
9 groff -ms [option ...] [file ...]
10 groff -m ms [option ...] [file ...]
11
13 The GNU implementation of the ms macro package is part of the groff
14 document formatting system. The ms package is suitable for the compo‐
15 sition of letters, memoranda, reports, and books.
16 These groff macros support cover page and table of contents generation,
18 automatically numbered headings, several paragraph styles, a variety of
19 text styling options, footnotes, and multi-column page layouts. ms
20 supports the tbl(1), eqn(1), pic(1), and refer(1) preprocessors for in‐
21 clusion of tables, mathematical equations, diagrams, and standardized
22 bibliographic citations.
23 This implementation is mostly compatible with the documented interface
25 and behavior of AT&T Unix Version 7 ms. Many extensions from 4.2BSD
26 (Berkeley) and Tenth Edition Research Unix have been recreated.
27
29 The ms macro package expects a certain amount of structure: a well-
30 formed document contains at least one paragraphing or heading macro
31 call. To compose a simple document from scratch, begin it by calling
32 .LP or .PP. Longer documents have a structure as follows.
33 Document type
35 Calling the RP macro at the beginning of your document puts the
36 document description (see below) on a cover page. Otherwise, ms
37 places this information on the first page, followed immediately
38 by the body text. Some document types found in other ms imple‐
39 mentations are specific to AT&T or Berkeley, and are not sup‐
40 ported in groff ms.
41 Format and layout
43 By setting registers and strings, you can configure your docu‐
44 ment's typeface, margins, spacing, headers and footers, and
45 footnote arrangement. See subsection “Document control set‐
46 tings” below.
47 Document description
49 A document description consists of any of: a title, one or more
50 authors' names and affiliated institutions, an abstract, and a
51 date or other identifier. See subsection “Document description
52 macros” below.
53 Body text
55 The main matter of your document follows its description (if
56 any). ms supports highly structured text consisting of para‐
57 graphs interspersed with multi-level headings (chapters, sec‐
58 tions, subsections, and so forth) and augmented by lists, foot‐
59 notes, tables, diagrams, and similar material. The preponder‐
60 ance of subsections below covers these matters.
61 Table of contents
63 Macros enable the collection of entries for a table of contents
64 (or index) as the material they discuss appears in the document.
65 You then call a macro to emit the table of contents at the end
66 of your document. The table of contents must necessarily follow
67 the rest of the text since GNU troff is a single-pass formatter;
68 it thus cannot determine the page number of a division of the
69 text until it has been set and output. Since ms output was de‐
70 signed for the production of hard copy, the traditional proce‐
71 dure was to manually relocate the pages containing the table of
72 contents between the cover page and the body text. Today, page
73 resequencing is more often done in the digital domain. An index
74 works similarly, but because it typically needs to be sorted af‐
75 ter collection, its preparation requires separate processing.
76 Document control settings
78 The following tables list the document control registers, strings, and
79 special characters. For any parameter whose default is unsatisfactory,
80 define it before calling any ms macro other than RP.
81 Margin settings
83 Parameter Definition Effective Default
84 ────────────────────────────────────────────────────────────────────────
85 \n[PO] Page offset (left margin) next page 1i (0)
86 \n[LL] Line length next paragraph 6.5i (65n)
87 \n[LT] Title line length next paragraph 6.5i (65n)
88 \n[HM] Top (header) margin next page 1i
89 \n[FM] Bottom (footer) margin next page 1i
90 ────────────────────────────────────────────────────────────────────────
91 Titles (headers, footers)
93 Parameter Definition Effective Default
94 ────────────────────────────────────────────────────────────────────────
95 \*[LH] Left header text next header empty
96 \*[CH] Center header text next header -\n[%]-
97 \*[RH] Right header text next header empty
98 \*[LF] Left footer text next footer empty
99 \*[CF] Center footer text next footer empty
100 \*[RF] Right footer text next footer empty
101 ────────────────────────────────────────────────────────────────────────
102 Text settings
104 Parameter Definition Effective Default
105 ────────────────────────────────────────────────────────────────────────
106 \n[PS] Point size next paragraph 10p
107 \n[VS] Vertical spacing (leading) next paragraph 12p
108 \n[HY] Hyphenation mode next paragraph 6
109 \*[FAM] Font family next paragraph T
110 ────────────────────────────────────────────────────────────────────────
111 Paragraph settings
113 Parameter Definition Effective Default
114 ────────────────────────────────────────────────────────────────────────
115 \n[PI] Indentation next paragraph 5n
116 \n[PD] Paragraph distance (spacing) next paragraph 0.3v (1v)
117 \n[QI] Quotation indentation next paragraph 5n
118 \n[PORPHANS] # of initial lines kept next paragraph 1
119 ────────────────────────────────────────────────────────────────────────
120 Heading settings
122 Parameter Definition Effective Default
123 ────────────────────────────────────────────────────────────────────────
124 \n[PSINCR] Point size increment next heading 1p
125 \n[GROWPS] Size increase depth limit next heading 0
126 \n[HORPHANS] # of following lines kept next heading 1
127 \*[SN-STYLE] Numbering style (alias) next heading \*[SN-DOT]
128 ────────────────────────────────────────────────────────────────────────
129 \*[SN-STYLE] can alternatively be made an alias of \*[SN-NO-DOT] with
131 the als request.
132 Footnote settings
134 Parameter Definition Effective Default
135 ────────────────────────────────────────────────────────────────────────
136 \n[FI] Indentation next footnote 2n
137 \n[FF] Format next footnote 0
138 \n[FPS] Point size next footnote \n[PS]-2p
139 \n[FVS] Vertical spacing (leading) next footnote \n[FPS]+2p
140 \n[FPD] Paragraph distance (spacing) next footnote \n[PD]/2
141 \*[FR] Line length ratio special 11/12
142 ────────────────────────────────────────────────────────────────────────
143 Display settings
145 Parameter Definition Effective Default
146 ────────────────────────────────────────────────────────────────────────
147 \n[DD] Display distance (spacing) special 0.5v (1v)
148 \n[DI] Display indentation special 0.5i
149 ────────────────────────────────────────────────────────────────────────
150 Other settings
152 Parameter Definition Effective Default
153 ────────────────────────────────────────────────────────────────────────
154 \n[MINGW] Minimum gutter width next page 2n
155 \n[TC-MARGIN] TOC page number margin width next PX call \w'000'
156 \[TC-LEADER] TOC leader character next PX call .\h'1m'
157 ────────────────────────────────────────────────────────────────────────
158 For entries marked “special” in the “Effective” column, see the discus‐
160 sion in the applicable section below. The PO, LL, and LT register de‐
161 faults vary by output device and paper format; the values shown are for
162 typesetters using U.S. letter paper, and then terminals. See section
163 “Paper format” of groff(1). The PD and DD registers use the larger
164 value if the vertical motion quantum of the output device is too coarse
165 for the smaller one; usually, this is the case only for output to ter‐
166 minals and emulators thereof. The “gutter” affected by \n[MINGW] is
167 the gap between columns in multiple-column page arrangements. The
168 TC-MARGIN register and TC-LEADER special character affect the format‐
169 ting of tables of contents assembled by the XS, XA, and XE macros.
170 Document description macros
172 Define information describing the document by calling the macros below
173 in the order shown; .DA or .ND can be called to set the document date
174 (or other identifier) at any time before (a) the abstract, if present,
175 or (b) its information is required in a header or footer. Use of these
176 macros is optional, except that .TL is mandatory if any of .RP, .AU,
177 .AI, or .AB is called, and .AE is mandatory if .AB is called.
178 .RP [no-repeat-info] [no-renumber]
180 Use the “report” (AT&T: “released paper”) format for your docu‐
181 ment, creating a separate cover page. The default arrangement
182 is to place most of the document description (title, author
183 names and institutions, and abstract, but not the date) at the
184 top of the first page. If the optional no-repeat-info argument
185 is given, ms produces a cover page but does not repeat any of
186 its information on subsequently (but see the DA macro below re‐
187 garding the date). Normally, .RP sets the page number following
188 the cover page to 1. Specifying the optional no-renumber argu‐
189 ment suppresses this alteration. Optional arguments can occur
190 in any order. “no” is recognized as a synonym of no-repeat-info
191 for AT&T compatibility.
192 .TL Specify the document title. ms collects text on input lines
194 following this call into the title until reaching .AU, .AB, or a
195 heading or paragraphing macro call.
196 .AU Specify an author's name. ms collects text on input lines fol‐
198 lowing this call into the author's name until reaching .AI, .AB,
199 another .AU, or a heading or paragraphing macro call. Call it
200 repeatedly to specify multiple authors.
201 .AI Specify the preceding author's institution. An .AU call is use‐
203 fully followed by at most one .AI call; if there are more, the
204 last .AI call controls. ms collects text on input lines follow‐
205 ing this call into the author's institution until reaching .AU,
206 .AB, or a heading or paragraphing macro call.
207 .DA [x ...]
209 Typeset the current date, or any arguments x, in the center
210 footer, and, if .RP is also called, left-aligned at the end of
211 the document description on the cover page.
212 .ND [x ...]
214 Typeset the current date, or any arguments x, if .RP is also
215 called, left-aligned at the end of the document description on
216 the cover page. This is groff ms's default.
217 .AB [no]
219 Begin the abstract. ms collects text on input lines following
220 this call into the abstract until reaching an .AE call. By de‐
221 fault, ms places the word “ABSTRACT” centered and in italics
222 above the text of the abstract. The optional argument “no” sup‐
223 presses this heading.
224 .AE End the abstract.
226 Text settings
228 The FAM string, a GNU extension, sets the font family for body text;
229 the default is “T”. The PS and VS registers set the type size and ver‐
230 tical spacing (distance between text baselines), respectively. The
231 font family and type size are ignored on terminal devices. Setting
232 these parameters before the first call of a heading, paragraphing, or
233 (non-date) document description macro also applies them to headers,
234 footers, and (for FAM) footnotes.
235 The HY register defines the automatic hyphenation mode used with the hy
237 request. Setting \n[HY] to 0 is equivalent to using the nh request.
238 This is a Tenth Edition Research Unix extension.
239 Typographical symbols
241 ms provides a few strings to obtain typographical symbols not easily
242 entered with the keyboard. These and many others are available as spe‐
243 cial character escape sequences—see groff_char(7).
244 \*[-] Interpolate an em dash.
246 \*[Q]
248 \*[U] Interpolate typographer's quotation marks where available, and
249 neutral double quotes otherwise. \*[Q] is the left quote and
250 \*[U] the right.
251 Paragraphs
253 Paragraphing macros break, or terminate, any pending output line so
254 that a new paragraph can begin. Several paragraph types are available,
255 differing in how indentation applies to them: to left, right, or both
256 margins; to the first output line of the paragraph, all output lines,
257 or all but the first. All paragraphing macro calls cause the insertion
258 of vertical space in the amount stored in the PD register, except at
259 page or column breaks, or adjacent to displays.
260 The PORPHANS register defines the minimum number of initial lines of
262 any paragraph that must be kept together to avoid isolated lines at the
263 bottom of a page. If a new paragraph is started close to the bottom of
264 a page, and there is insufficient space to accommodate \n[PORPHANS]
265 lines before an automatic page break, then a page break is forced be‐
266 fore the start of the paragraph. This is a GNU extension.
267 .LP Set a paragraph without any (additional) indentation.
269 .PP Set a paragraph with a first-line left indentation in the amount
271 stored in the PI register.
272 .IP [marker [width]]
274 Set a paragraph with a left indentation. The optional marker is
275 not indented and is empty by default. width overrides the in‐
276 dentation amount in \n[PI]; its default unit is “n”. Once spec‐
277 ified, width applies to further .IP calls until specified again
278 or a heading or different paragraphing macro is called.
279 .QP Set a paragraph indented from both left and right margins by
281 \n[QI].
282 .QS
284 .QE Begin (QS) and end (QE) a region where each paragraph is in‐
285 dented from both margins by \n[QI]. The text between .QS and
286 .QE can be structured further by use of other paragraphing
287 macros.
288 .XP Set an “exdented” paragraph—one with a left indentation of
290 \n[PI] on every line except the first (also known as a hanging
291 indent). This is a Berkeley extension.
292 Headings
294 Use headings to create a hierarchical structure for your document. The
295 ms macros print headings in bold using the same font family and, by de‐
296 fault, type size as the body text. Headings are available with and
297 without automatic numbering. Text on input lines following the macro
298 call becomes the heading's title. Call a paragraphing macro to end the
299 heading text and start the section's content.
300 .NH [depth]
302 Set an automatically numbered heading. ms produces a numbered
303 heading in the form a.b.c..., to any level desired, with the
304 numbering of each depth increasing automatically and being reset
305 to zero when a more significant depth is increased. “1” is the
306 most significant or coarsest division of the document. Only
307 non-zero values are output. If depth is omitted, it is taken to
308 be 1. If you specify depth such that an ascending gap occurs
309 relative to the previous NH call—that is, you “skip a depth”, as
310 by “.NH 1” and then “.NH 3”, groff ms emits a warning on the
311 standard error stream.
312 .NH S heading-depth-index ...
314 Alternatively, you can give NH a first argument of “S”, followed
315 by integers to number the heading depths explicitly. Further
316 automatic numbering, if used, resumes using the specified in‐
317 dices as their predecessors. This feature is a Berkeley exten‐
318 sion.
319 After .NH is called, the assigned number is made available in the
321 strings SN-DOT (as it appears in a printed heading with default format‐
322 ting, followed by a terminating period) and SN-NO-DOT (with the termi‐
323 nating period omitted). These are GNU extensions.
324 You can control the style used to print numbered headings by defining
326 an appropriate alias for the string SN-STYLE. By default, \*[SN-STYLE]
327 is aliased to \*[SN-DOT]. If you prefer to omit the terminating period
328 from numbers appearing in numbered headings, you may alias it to
329 \*[SN-NO-DOT]. Any such change in numbering style becomes effective
330 from the next use of .NH following redefinition of the alias for
331 \*[SN-STYLE]. The formatted number of the current heading is available
332 in \*[SN] (a feature first documented by Berkeley); this string facili‐
333 tates its inclusion in, for example, table captions, equation labels,
334 and .XS/.XA/.XE table of contents entries.
335 .SH [depth]
337 Set an unnumbered heading. The optional depth argument is a GNU
338 extension indicating the heading depth corresponding to the
339 depth argument of .NH. It matches the type size at which the
340 heading is set to that of a numbered heading at the same depth
341 when the \n[GROWPS] and \n[PSINCR] heading size adjustment mech‐
342 anism is in effect.
343 The PSINCR register defines an increment in type size to be applied to
345 a heading at a lesser depth than that specified in \n[GROWPS]. The
346 value of \n[PSINCR] should be specified in points with the “p” scaling
347 unit and may include a fractional component.
348 The GROWPS register defines the heading depth above which the type size
350 increment set by \n[PSINCR] becomes effective. For each heading depth
351 less than the value of \n[GROWPS], the type size is increased by
352 \n[PSINCR]. Setting \n[GROWPS] to a value less than 2 disables the in‐
353 cremental heading size feature.
354 In other words, if the value of GROWPS register is greater than the
356 depth argument to a .NH or .SH call, the type size of a heading pro‐
357 duced by these macros increases by \n[PSINCR] units over \n[PS] multi‐
358 plied by the difference of \n[GROWPS] and depth.
359 The \n[HORPHANS] register operates in conjunction with the NH and SH
361 macros to inhibit the printing of isolated headings at the bottom of a
362 page; it specifies the minimum number of lines of the subsequent para‐
363 graph that must be kept on the same page as the heading. If insuffi‐
364 cient space remains on the current page to accommodate the heading and
365 this number of lines of paragraph text, a page break is forced before
366 the heading is printed. Any display macro call or tbl, pic, or eqn re‐
367 gion between the heading and the subsequent paragraph suppresses this
368 grouping.
369 Typeface and decoration
371 The ms macros provide a variety of ways to style text. Attend closely
372 to the ordering of arguments labeled pre and post, which is not intu‐
373 itive. Support for pre arguments is a GNU extension.
374 .B [text [post [pre]]]
376 Style text in bold, followed by post in the previous font style
377 without intervening space, and preceded by pre similarly. With‐
378 out arguments, ms styles subsequent text in bold until the next
379 paragraphing, heading, or no-argument typeface macro call.
380 .R [text [post [pre]]]
382 As .B, but use the roman style (upright text of normal weight)
383 instead of bold. Argument recognition is a GNU extension.
384 .I [text [post [pre]]]
386 As .B, but use an italic or oblique style instead of bold.
387 .BI [text [post [pre]]]
389 As .B, but use a bold italic or bold oblique style instead of
390 upright bold. This is a Tenth Edition Research Unix extension.
391 .CW [text [post [pre]]]
393 As .B, but use a constant-width (monospaced) roman typeface in‐
394 stead of bold. This is a Tenth Edition Research Unix extension.
395 .BX [text]
397 Typeset text and draw a box around it. On terminal devices, re‐
398 verse video is used instead. If you want text to contain space,
399 use unbreakable space or horizontal motion escape sequences (\~,
400 \space, \^, \|, \0, or \h).
401 .UL [text [post]]
403 Typeset text with an underline. post, if present, is set after
404 text with no intervening space.
405 .LG Set subsequent text in larger type (2 points larger than the
407 current size) until the next type size, paragraphing, or heading
408 macro call. You can specify this macro multiple times to en‐
409 large the type size as needed.
410 .SM Set subsequent text in smaller type (2 points smaller than the
412 current size) until the next type size, paragraphing, or heading
413 macro call. You can specify this macro multiple times to reduce
414 the type size as needed.
415 .NL Set subsequent text at the normal type size (\n[PS]).
417 When pre is used, a hyphenation control escape sequence \% that would
419 ordinarily start text must start pre instead.
420 groff ms also offers strings to begin and end super- and subscripting.
422 These are GNU extensions.
423 \*{
425 \*} Begin and end superscripting, respectively.
426 \*<
428 \*> Begin and end subscripting, respectively.
429 Indented regions
431 You may need to indent a region of text while otherwise formatting it
432 normally. Indented regions can be nested.
433 .RS Begin a region where headings, paragraphs, and displays are in‐
435 dented (further) by \n[PI].
436 .RE End the (next) most recent indented region.
438 Keeps, boxed keeps, and displays
440 On occasion, you may want to keep several lines of text, or a region of
441 a document, together on a single page, preventing an automatic page
442 break within certain boundaries. This can cause a page break to occur
443 earlier than it normally would.
444 You can alternatively specify a floating keep: if a keep cannot fit on
446 the current page, ms holds its contents and allows text following the
447 keep (in the source document) to fill in the remainder of the current
448 page. When the page breaks, whether by reaching the end or bp request,
449 ms puts the floating keep at the beginning of the next page.
450 .KS Begin a keep.
452 .KF Begin a floating keep.
454 .KE End (floating) keep.
456 As an alternative to the keep mechanism, the ne request forces a page
458 break if there is not at least the amount of vertical space specified
459 in its argument remaining on the page.
460 A boxed keep has a frame drawn around it.
462 .B1 Begin a keep with a box drawn around it.
464 .B2 End boxed keep.
466 Boxed keep macros cause breaks; if you need to box a word or phrase
468 within a line, see the BX macro in section “Highlighting” above. Box
469 lines are drawn as close as possible to the text they enclose so that
470 they are usable within paragraphs. If you wish to place one or more
471 paragraphs in a boxed keep, you may improve their appearance by calling
472 .B1 after the first paragraphing macro, and by adding a small amount of
473 vertical space before calling .B2.
474 If you want a boxed keep to float, you will need to enclose the .B1 and
476 .B2 calls within a pair of .KF and .KE calls.
477 Displays turn off filling; lines of verse or program code are shown
479 with their lines broken as in the source document without requiring br
480 requests between lines. Displays can be kept on a single page or al‐
481 lowed to break across pages. The DS macro begins a kept display of the
482 layout specified in its first argument; non-kept displays are begun
483 with dedicated macros corresponding to their layout.
484 .DS L
486 .LD Begin (DS: kept) left-aligned display.
487 .DS [I [indent]]
489 .ID [indent]
490 Begin (DS: kept) display indented by indent if specified, \n[DI]
491 otherwise.
492 .DS B
494 .BD Begin (DS: kept) block display: the entire display is left-
495 aligned, but indented such that the longest line in the display
496 is centered on the page.
497 .DS C
499 .CD Begin (DS: kept) centered display: each line in the display is
500 centered.
501 .DS R
503 .RD Begin (DS: kept) right-aligned display. This is a GNU exten‐
504 sion.
505 .DE End any display.
507 The distance stored in \n[DD] is inserted before and after each pair of
509 display macros; this is a Berkeley extension. In groff ms, this dis‐
510 tance replaces any adjacent inter-paragraph distance or subsequent
511 spacing prior to a section heading. The DI register is a GNU exten‐
512 sion; its value is an indentation applied to displays created with .DS
513 and .ID without arguments, to “.DS I” without an indentation argument,
514 and to equations set with “.EQ I”. Changes to either register take ef‐
515 fect at the next display boundary.
516 Tables, figures, equations, and references
518 The ms package is often used with the tbl, pic, eqn, and refer pre‐
519 processors. The \n[DD] distance is also applied to regions of the doc‐
520 ument preprocessed with eqn, pic, and tbl. Mark text meant for pre‐
521 processors by enclosing it in pairs of tokens as follows, with nothing
522 between the dot and the macro name. The preprocessors match these to‐
523 kens only at the start of an input line.
524 .TS [H]
526 .TE Demarcate a table to be processed by the tbl preprocessor. The
527 optional H argument instructs ms to repeat table rows (often
528 column headings) at the top of each new page the table spans, if
529 applicable; calling the TH macro marks the end of such rows.
530 tbl(1) provides a comprehensive reference to the preprocessor
531 and offers examples of its use.
532 .PS
534 .PE
535 .PF .PS begins a picture to be processed by the pic preprocessor;
536 either of .PE or .PF ends it, the latter with “flyback” to the
537 vertical position at its top.
538 .EQ [align [label]]
540 .EN Demarcate an equation to be processed by the eqn preprocessor.
541 The equation is centered by default; align can be C, L, or I to
542 (explicitly) center, left-align, or indent it by \n[DI], respec‐
543 tively. If specified, label is set right-aligned.
544 .[
546 .] Demarcate a bibliographic citation to be processed by the refer
547 preprocessor. refer(1) provides a comprehensive reference to
548 the preprocessor and the format of its bibliographic database.
549 When refer emits collected references (as might be done on a “Works
551 Cited” page), it interpolates the string \*[REFERENCES] as an unnum‐
552 bered heading (.SH).
553 Attempting to place a multi-page table inside a keep can lead to un‐
555 pleasant results, particularly if the tbl “allbox” option is used.
556 Footnotes
558 A footnote is typically anchored to a place in the text with a marker,
559 which is a small integer, a symbol, or arbitrary user-specified text.
560 \** Place an automatic number, an automatically generated numeric
562 footnote marker, in the text. Each time this string is interpo‐
563 lated, the number it produces increments by one. Automatic num‐
564 bers start at 1. This is a Berkeley extension.
565 Enclose the footnote text in FS and FE macro calls to set it at the
567 nearest available “foot”, or bottom, of a text column or page.
568 .FS [marker]
570 Begin a footnote. The .FS-MARK hook (see below) is called with
571 any supplied marker argument, which is then also placed at the
572 beginning of the footnote text. If marker is omitted, the next
573 pending automatic number enqueued by interpolation of the *
574 string is used, and if none exists, nothing is prefixed.
575 .FE End footnote text.
577 groff ms provides a hook macro, FS-MARK, for user-determined operations
579 to be performed when the FS macro is called. It is passed the same ar‐
580 guments as .FS itself. By default, this macro has an empty definition.
581 .FS-MARK is a GNU extension.
582 Footnote text is formatted as paragraphs are, using analogous parame‐
584 ters. The registers FI, FPD, FPS, and FVS correspond to PI, PD, PS,
585 and VS, respectively; FPD, FPS, and FVS are GNU extensions.
586 The FF register controls the formatting of automatically numbered foot‐
588 note paragraphs, and those for which .FS is given a marker argument, at
589 the bottom of a column or page as follows.
590 0 Set an automatic number, or a specified FS marker argu‐
592 ment, as a superscript (on typesetter devices) or sur‐
593 rounded by square brackets (on terminals). The footnote
594 paragraph is indented as with .PP if there is an .FS ar‐
595 gument or an automatic number, and as with .LP otherwise.
596 This is the default.
597 1 As 0, but set the marker as regular text, and follow an
599 automatic number with a period.
600 2 As 1, but without indentation (like .LP).
602 3 As 1, but set the footnote paragraph with the marker
604 hanging (like .IP).
605 Language and localization
607 groff ms provides several strings that you can customize for your own
608 purposes, or redefine to adapt the macro package to languages other
609 than English. It is already localized for Czech, German, French, Ital‐
610 ian, and Swedish. Load the desired localization macro package after
611 ms; see groff_tmac(5).
612 String Default
614 ───────────────────────────────────
615 \*[REFERENCES] References
616 \*[ABSTRACT] \f[I]ABSTRACT\f[]
617 \*[TOC] Table of Contents
618 \*[MONTH1] January
619 \*[MONTH2] February
620 \*[MONTH3] March
621 \*[MONTH4] April
622 \*[MONTH5] May
623 \*[MONTH6] June
624 \*[MONTH7] July
625 \*[MONTH8] August
626 \*[MONTH9] September
627 \*[MONTH10] October
628 \*[MONTH11] November
629 \*[MONTH12] December
630 ───────────────────────────────────
631 The default for ABSTRACT includes font selection escape sequences to
632 set the word in italics.
633 Headers and footers
635 There are multiple ways to produce headers and footers. One is to de‐
636 fine the strings LH, CH, and RH to set the left, center, and right
637 headers, respectively; and LF, CF, and RF to set the left, center, and
638 right footers. This approach suffices for documents that do not dis‐
639 tinguish odd- and even-numbered pages.
640 Another method is to call macros that set headers or footers for odd-
642 or even-numbered pages. Each such macro takes a delimited argument
643 separating the left, center, and right header or footer texts from each
644 other. You can replace the neutral apostrophes (') shown below with
645 any character not appearing in the header or footer text. These macros
646 are Berkeley extensions.
647 .OH 'left'center'right'
649 .OF 'left'center'right'
650 .EH 'left'center'right'
651 .EF 'left'center'right'
652 The OH and EH macros define headers for odd- (recto) and even-
653 numbered (verso) pages, respectively; the OF and EF macros de‐
654 fine footers for them.
655 With either method, a percent sign % in header or footer text is re‐
657 placed by the current page number. By default, ms places no header on
658 a page numbered “1” (regardless of its number format).
659 .P1 Typeset the header even on page 1. To be effective, this macro
661 must be called before the header trap is sprung on any page num‐
662 bered “1”. This is a Berkeley extension.
663 For even greater flexibility, ms permits redefinition of the macros
665 called when the page header and footer traps are sprung. PT (“page
666 trap”) is called by ms when the header is to be written, and BT (“bot‐
667 tom trap”) when the footer is to be. The groff page location trap that
668 ms sets up to format the header also calls the (normally undefined) HD
669 macro after .PT; you can define .HD if you need additional processing
670 after setting the header. The HD hook is a Berkeley extension. Any
671 such macros you (re)define must implement any desired specialization
672 for odd-, even-, or first numbered pages.
673 Tab stops
675 Use the ta request to set tab stops as needed.
676 .TA Reset the tab stops to the ms default (every 5 ens). Redefine
678 this macro to create a different set of default tab stops.
679 Margins
681 Control margins using the registers summarized in the “Margins” portion
682 of the table in section “Document control settings” above. There is no
683 setting for the right margin; the combination of page offset \n[PO] and
684 line length \n[LL] determines it.
685 Multiple columns
687 ms can set text in as many columns as reasonably fit on the page. The
688 following macros force a page break if a multi-column layout is active
689 when they are called. \n[MINGW] is the default minimum gutter width;
690 it is a GNU extension. When multiple columns are in use, keeps and the
691 HORPHANS and PORPHANS registers work with respect to column breaks in‐
692 stead of page breaks.
693 .1C Arrange page text in a single column (the default).
695 .2C Arrange page text in two columns.
697 .MC [column-width [gutter-width]]
699 Arrange page text in multiple columns. If you specify no argu‐
700 ments, it is equivalent to the 2C macro. Otherwise, column-
701 width is the width of each column and gutter-width is the mini‐
702 mum distance between columns.
703 Creating a table of contents
705 Define an entry to appear in the table of contents by bracketing its
706 text between calls to the XS and XE macros. A typical application is
707 to call them immediately after NH or SH and repeat the heading text
708 within them. The XA macro, used within .XS/.XE pairs, supplements an
709 entry—for instance, when it requires multiple output lines, whether be‐
710 cause a heading is too long to fit or because style dictates that page
711 numbers not be repeated. You may wish to indent the text thus wrapped
712 to correspond to its heading depth; this can be done in the entry text
713 by prefixing it with tabs or horizontal motion escape sequences, or by
714 providing a second argument to the XA macro. .XS and .XA automatically
715 associate the page number where they are called with the text following
716 them, but they accept arguments to override this behavior. At the end
717 of the document, call TC or PX to emit the table of contents; .TC re‐
718 sets the page number to i (Roman numeral one), and then calls PX. All
719 of these macros are Berkeley extensions.
720 .XS [page-number]
722 .XA [page-number [indentation]]
723 .XE Begin, supplement, and end a table of contents entry. Each en‐
724 try is associated with page-number (otherwise the current page
725 number); a page-number of “no” prevents a leader and page number
726 from being emitted for that entry. Use of .XA within .XS/.XE is
727 optional; it can be repeated. If indentation is present, a sup‐
728 plemental entry is indented by that amount; ens are assumed if
729 no unit is indicated. Text on input lines between .XS and .XE
730 is stored for later recall by .PX.
731 .PX [no]
733 Switch to single-column layout. Unless “no” is specified, cen‐
734 ter and interpolate \*[TOC] in bold and two points larger than
735 the body text. Emit the table of contents entries.
736 .TC [no]
738 Set the page number to 1, the page number format to lowercase
739 Roman numerals, and call PX (with a “no” argument, if present).
740 The remaining features in this subsection are GNU extensions. groff ms
742 obviates the need to repeat heading text after .XS calls. Call .XN and
743 .XH after .NH and .SH, respectively. Text to be appended to the for‐
744 matted section heading, but not to appear in the table of contents en‐
745 try, can follow these calls.
746 .XN heading-text
748 Format heading-text and create a corresponding table of contents
749 entry; the indentation is computed from the depth argument of
750 the preceding NH call.
751 .XH depth heading-text
753 As .XN, but use depth to determine the indentation.
754 groff ms encourages customization of table of contents entry produc‐
756 tion. (Re-)define any of the following macros as desired.
757 .XN-REPLACEMENT heading-text
759 .XH-REPLACEMENT depth heading-text
760 These hook macros implement .XN and .XH, and call XN-INIT and
761 XH-INIT, respectively, then call XH-UPDATE-TOC with the argu‐
762 ments given them.
763 .XH-INIT
765 .XN-INIT
766 These hook macros do nothing by default.
767 .XH-UPDATE-TOC depth heading-text
769 Bracket heading-text with XS and XE calls, indenting it by 2 ens
770 per level of depth beyond the first.
771 You can customize the style of the leader that bridges each table of
773 contents entry with its page number; define the TC-LEADER special char‐
774 acter by using the char request. A typical leader combines the dot
775 glyph “.” with a horizontal motion escape sequence to spread the dots.
776 The width of the page number field is stored in the TC-MARGIN register.
777
779 The groff ms macros are an independent reimplementation, using no AT&T
780 code. Since they take advantage of the extended features of groff,
781 they cannot be used with AT&T troff. groff ms supports features de‐
782 scribed above as Berkeley and Tenth Edition Research Unix extensions,
783 and adds several of its own.
784 • The internals of groff ms differ from the internals of AT&T ms.
786 Documents that depend upon implementation details of AT&T ms may not
787 format properly with groff ms. Such details include macros whose
788 function was not documented in the AT&T ms manual (“Typing Documents
789 on the UNIX System: Using the -ms Macros with Troff and Nroff”, M.
790 E. Lesk, Bell Laboratories, 1978).
791 • The error-handling policy of groff ms is to detect and report er‐
793 rors, rather than to ignore them silently.
794 • Tenth Edition Research Unix supported P1/P2 macros to bracket code
796 examples; groff ms does not.
797 • groff ms does not work in GNU troff's AT&T compatibility mode. If
799 loaded when that mode is enabled, it aborts processing with a diag‐
800 nostic message.
801 • Multiple line spacing is not supported. Use a larger vertical spac‐
803 ing instead.
804 • groff ms uses the same header and footer defaults in both nroff and
806 troff modes as AT&T ms does in troff mode; AT&T's default in nroff
807 mode is to put the date, in U.S. traditional format (e.g., “January
808 1, 2021”), in the center footer (the CF string).
809 • Many groff ms macros, including those for paragraphs, headings, and
811 displays, cause a reset of paragraph rendering parameters, and may
812 change the indentation; they do so not by incrementing or decrement‐
813 ing it, but by setting it absolutely. This can cause problems for
814 documents that define additional macros of their own that try to ma‐
815 nipulate indentation. Use .RS and .RE instead of the in request.
816 • AT&T ms interpreted the values of the registers PS and VS in points,
818 and did not support the use of scaling units with them. groff ms
819 interprets values of the registers PS, VS, FPS, and FVS, equal to or
820 larger than 1,000 (one thousand) as decimal fractions multiplied
821 by 1,000. (Register values are converted to and stored as basic
822 units. See “Measurements” in the groff Texinfo manual or in
823 groff(7)). This threshold makes use of a scaling unit with these
824 parameters practical for high-resolution devices while preserving
825 backward compatibility. It also permits expression of non-integral
826 type sizes. For example, “groff -rPS=10.5p” at the shell prompt is
827 equivalent to placing “.nr PS 10.5p” at the beginning of the docu‐
828 ment.
829 • AT&T ms's AU macro supported arguments used with some document
831 types; groff ms does not.
832 • Right-aligned displays are available. The AT&T ms manual observes
834 that “it is tempting to assume that “.DS R” will right adjust lines,
835 but it doesn't work”. In groff ms, it does.
836 • To make groff ms use the default page offset (which also specifies
838 the left margin), the PO register must stay undefined until the
839 first ms macro is called. This implies that \n[PO] should not be
840 used early in the document, unless it is changed also: accessing an
841 undefined register automatically defines it.
842 • groff ms supports the PN register, but it is not necessary; you can
844 access the page number via the usual % register and invoke the af
845 request to assign a different format to it if desired. (If you re‐
846 define the ms PT macro and desire special treatment of certain page
847 numbers—like “1”—you may need to handle a non-Arabic page number
848 format, as groff ms's .PT does; see the macro package source. groff
849 ms aliases the PN register to %.)
850 • The AT&T ms manual documents registers CW and GW as setting the de‐
852 fault column width and “intercolumn gap”, respectively, and which
853 applied when .MC was called with fewer than two arguments. groff ms
854 instead treats .MC without arguments as synonymous with .2C; there
855 is thus no occasion for a default column width register. Further,
856 the MINGW register and the second argument to .MC specify a minimum
857 space between columns, not the fixed gutter width of AT&T ms.
858 • The AT&T ms manual did not document the QI register; Berkeley and
860 groff ms do.
861 • The register GS is set to 1 by the groff ms macros, but is not used
863 by the AT&T ms package. Documents that need to determine whether
864 they are being formatted with groff ms or another implementation
865 should test this register.
866 Unix Version 7 macros not implemented by groff ms
868 Several macros described in the Unix Version 7 ms documentation are
869 unimplemented by groff ms because they are specific to the requirements
870 of documents produced internally by Bell Laboratories, some of which
871 also require a glyph for the Bell System logo that groff does not sup‐
872 port. These macros implemented several document type formats (EG, IM,
873 MF, MR, TM, TR), were meaningful only in conjunction with the use of
874 certain document types (AT, CS, CT, OK, SG), stored the postal ad‐
875 dresses of Bell Labs sites (HO, IH, MH, PY, WH), or lacked a stable
876 definition over time (UX).
877
879 groff ms retains some legacy features solely to support formatting of
880 historical documents; contemporary ones should not use them because
881 they can render poorly. See groff_char(7) instead.
882 AT&T ms accent mark strings
884 AT&T ms defined accent mark strings as follows.
885 String Description
887 ──────────────────────────────────────────────────────
888 \*['] Apply acute accent to subsequent glyph.
889 \*[`] Apply grave accent to subsequent glyph.
890 \*[:] Apply dieresis (umlaut) to subsequent glyph.
891 \*[^] Apply circumflex accent to subsequent glyph.
892 \*[~] Apply tilde accent to subsequent glyph.
893 \*[C] Apply caron to subsequent glyph.
894 \*[,] Apply cedilla to subsequent glyph.
895 Berkeley ms accent mark and glyph strings
897 Berkeley ms offered an AM macro; calling it redefined the AT&T accent
898 mark strings (except for \*C), applied them to the preceding glyph, and
899 defined additional strings, some for spacing glyphs.
900 .AM Enable alternative accent mark and glyph-producing strings.
902 String Description
904 ───────────────────────────────────────────────────────────────
905 \*['] Apply acute accent to preceding glyph.
906 \*[`] Apply grave accent to preceding glyph.
908 \*[:] Apply dieresis (umlaut) to preceding glyph.
909 \*[^] Apply circumflex accent to preceding glyph.
910 \*[~] Apply tilde accent to preceding glyph.
911 \*[,] Apply cedilla to preceding glyph.
912 \*[/] Apply stroke (slash) to preceding glyph.
913 \*[v] Apply caron to preceding glyph.
914 \*[_] Apply macron to preceding glyph.
915 \*[.] Apply underdot to preceding glyph.
916 \*[o] Apply ring accent to preceding glyph.
917 ───────────────────────────────────────────────────────────────
918 \*[?] Interpolate inverted question mark.
919 \*[!] Interpolate inverted exclamation mark.
920 \*[8] Interpolate small letter sharp s.
921 \*[q] Interpolate small letter o with hook accent (ogonek).
922 \*[3] Interpolate small letter yogh.
923 \*[d-] Interpolate small letter eth.
924 \*[D-] Interpolate capital letter eth.
925 \*[th] Interpolate small letter thorn.
926 \*[TH] Interpolate capital letter thorn.
927 \*[ae] Interpolate small ae ligature.
928 \*[AE] Interpolate capital ae ligature.
929 \*[oe] Interpolate small oe ligature.
930 \*[OE] Interpolate capital oe ligature.
931
933 The following conventions are used for names of macros, strings, and
934 registers. External names available to documents that use the groff ms
935 macros contain only uppercase letters and digits.
936 Internally, the macros are divided into modules. Conventions for iden‐
938 tifier names are as follows.
939 • Names used only within one module are of the form module*name.
941 • Names used outside the module in which they are defined are of the
943 form module@name.
944 • Names associated with a particular environment are of the form
946 environment:name; these are used only within the par module.
947 • name does not have a module prefix.
949 • Constructed names used to implement arrays are of the form
951 array!index.
952 Thus the groff ms macros reserve the following names:
954 • Names containing the characters *, @, and :.
956 • Names containing only uppercase letters and digits.
958
960 /usr/share/groff/1.23.0/tmac/s.tmac
961 implements the package.
962 /usr/share/groff/1.23.0/tmac/refer-ms.tmac
964 implements refer(1) support for ms.
965 /usr/share/groff/1.23.0/tmac/ms.tmac
967 is a wrapper enabling the package to be loaded with “groff -m
968 ms”.
969
971 The GNU version of the ms macro package was written by James Clark and
972 contributors. This document was written by Clark, Larry Kollar
973 ⟨lkollar@despammed.com⟩, and G. Branden Robinson ⟨g.branden.robinson@
974 gmail.com⟩.
975
977 A manual is available in source and rendered form. On your system, it
978 may be compressed and/or available in additional formats.
979 /usr/share/doc/groff/ms.ms
981 /usr/share/doc/groff/ms.ps
982 “Using groff with the ms Macro Package”; Larry Kollar and
983 G. Branden Robinson.
984 /usr/share/doc/groff/msboxes.ms
986 /usr/share/doc/groff/msboxes.pdf
987 “Using PDF boxes with groff and the ms macros”; Deri James.
988 BOXSTART and BOXSTOP macros are available via the sboxes exten‐
989 sion package, enabling colored, bordered boxes when the pdf out‐
990 put device is used.
991 Groff: The GNU Implementation of troff, by Trent A. Fisher and Werner
993 Lemberg, is the primary groff manual. You can browse it interactively
994 with “info groff”.
995 groff(1), troff(1), tbl(1), pic(1), eqn(1), refer(1)
997groff 1.23.0 2 November 2023 groff_ms(7)