1groff_ms(7) Miscellaneous Information Manual groff_ms(7)
2
3
4
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
17 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
24 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
34 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
42 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
48 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
54 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
62 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
77 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
82 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
92 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
103 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
112 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
121 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
130 \*[SN-STYLE] can alternatively be made an alias of \*[SN-NO-DOT] with
131 the als request.
132
133 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
144 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
151 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
159 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
171 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
179 .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
193 .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
197 .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
202 .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
208 .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
213 .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
218 .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
225 .AE End the abstract.
226
227 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
236 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
240 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
245 \*[-] Interpolate an em dash.
246
247 \*[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
252 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
261 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
268 .LP Set a paragraph without any (additional) indentation.
269
270 .PP Set a paragraph with a first-line left indentation in the amount
271 stored in the PI register.
272
273 .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
280 .QP Set a paragraph indented from both left and right margins by
281 \n[QI].
282
283 .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
289 .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
293 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
301 .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
313 .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
320 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
325 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
336 .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
344 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
349 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
355 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
360 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
370 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
375 .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
381 .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
385 .I [text [post [pre]]]
386 As .B, but use an italic or oblique style instead of bold.
387
388 .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
392 .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
396 .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
402 .UL [text [post]]
403 Typeset text with an underline. post, if present, is set after
404 text with no intervening space.
405
406 .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
411 .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
416 .NL Set subsequent text at the normal type size (\n[PS]).
417
418 When pre is used, a hyphenation control escape sequence \% that would
419 ordinarily start text must start pre instead.
420
421 groff ms also offers strings to begin and end super- and subscripting.
422 These are GNU extensions.
423
424 \*{
425 \*} Begin and end superscripting, respectively.
426
427 \*<
428 \*> Begin and end subscripting, respectively.
429
430 Indented regions
431 You may need to indent a region of text while otherwise formatting it
432 normally. Indented regions can be nested.
433
434 .RS Begin a region where headings, paragraphs, and displays are in‐
435 dented (further) by \n[PI].
436
437 .RE End the (next) most recent indented region.
438
439 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
445 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
451 .KS Begin a keep.
452
453 .KF Begin a floating keep.
454
455 .KE End (floating) keep.
456
457 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
461 A boxed keep has a frame drawn around it.
462
463 .B1 Begin a keep with a box drawn around it.
464
465 .B2 End boxed keep.
466
467 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
475 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
478 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
485 .DS L
486 .LD Begin (DS: kept) left-aligned display.
487
488 .DS [I [indent]]
489 .ID [indent]
490 Begin (DS: kept) display indented by indent if specified, \n[DI]
491 otherwise.
492
493 .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
498 .DS C
499 .CD Begin (DS: kept) centered display: each line in the display is
500 centered.
501
502 .DS R
503 .RD Begin (DS: kept) right-aligned display. This is a GNU exten‐
504 sion.
505
506 .DE End any display.
507
508 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
517 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
525 .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
533 .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
539 .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
545 .[
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
550 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
554 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
557 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
561 \** 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
566 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
569 .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
576 .FE End footnote text.
577
578 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
583 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
587 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
591 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
598 1 As 0, but set the marker as regular text, and follow an
599 automatic number with a period.
600
601 2 As 1, but without indentation (like .LP).
602
603 3 As 1, but set the footnote paragraph with the marker
604 hanging (like .IP).
605
606 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
613 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
634 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
641 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
648 .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
656 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
660 .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
664 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
674 Tab stops
675 Use the ta request to set tab stops as needed.
676
677 .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
680 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
686 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
694 .1C Arrange page text in a single column (the default).
695
696 .2C Arrange page text in two columns.
697
698 .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
704 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
721 .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
732 .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
737 .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
741 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
747 .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
752 .XH depth heading-text
753 As .XN, but use depth to determine the indentation.
754
755 groff ms encourages customization of table of contents entry produc‐
756 tion. (Re-)define any of the following macros as desired.
757
758 .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
764 .XH-INIT
765 .XN-INIT
766 These hook macros do nothing by default.
767
768 .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
772 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
785 • 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
792 • The error-handling policy of groff ms is to detect and report er‐
793 rors, rather than to ignore them silently.
794
795 • Tenth Edition Research Unix supported P1/P2 macros to bracket code
796 examples; groff ms does not.
797
798 • 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
802 • Multiple line spacing is not supported. Use a larger vertical spac‐
803 ing instead.
804
805 • 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
810 • 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
817 • 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
830 • AT&T ms's AU macro supported arguments used with some document
831 types; groff ms does not.
832
833 • 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
837 • 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
843 • 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
851 • 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
859 • The AT&T ms manual did not document the QI register; Berkeley and
860 groff ms do.
861
862 • 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
867 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
883 AT&T ms accent mark strings
884 AT&T ms defined accent mark strings as follows.
885
886 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
896 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
901 .AM Enable alternative accent mark and glyph-producing strings.
902
903 String Description
904 ───────────────────────────────────────────────────────────────
905 \*['] Apply acute accent to preceding glyph.
906
907 \*[`] 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
937 Internally, the macros are divided into modules. Conventions for iden‐
938 tifier names are as follows.
939
940 • Names used only within one module are of the form module*name.
941
942 • Names used outside the module in which they are defined are of the
943 form module@name.
944
945 • Names associated with a particular environment are of the form
946 environment:name; these are used only within the par module.
947
948 • name does not have a module prefix.
949
950 • Constructed names used to implement arrays are of the form
951 array!index.
952
953 Thus the groff ms macros reserve the following names:
954
955 • Names containing the characters *, @, and :.
956
957 • Names containing only uppercase letters and digits.
958
960 /usr/share/groff/1.23.0/tmac/s.tmac
961 implements the package.
962
963 /usr/share/groff/1.23.0/tmac/refer-ms.tmac
964 implements refer(1) support for ms.
965
966 /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
980 /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
985 /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
992 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
996 groff(1), troff(1), tbl(1), pic(1), eqn(1), refer(1)
997
998
999
1000groff 1.23.0 2 November 2023 groff_ms(7)