1GROFF_MS(7) Miscellaneous Information Manual GROFF_MS(7)
2
6 groff_ms - groff ms macros
7
9 groff -ms [ options... ] [ files... ]
10 groff -m ms [ options... ] [ files... ]
11
13 This manual page describes the GNU version of the ms macros, part of
14 the groff typesetting system. The ms macros are mostly compatible with
15 the documented behavior of the 4.3 BSD Unix ms macros (see Differences
16 from troff ms below for details). The ms macros are suitable for
17 reports, letters, books, and technical documentation.
18
20 The ms macro package expects files to have a certain amount of struc‐
21 ture. The simplest documents can begin with a paragraph macro and con‐
22 sist of text separated by paragraph macros or even blank lines. Longer
23 documents have a structure as follows:
24 Document type
26 If you use the RP (report) macro at the beginning of the docu‐
27 ment, groff prints the cover page information on its own page;
28 otherwise it prints the information on the first page with your
29 document text immediately following. Other document formats
30 found in AT&T troff are specific to AT&T or Berkeley, and are
31 not supported in groff ms.
32 Format and layout
34 By setting number registers, you can change your document's type
35 (font and size), margins, spacing, headers and footers, and
36 footnotes. See Document control registers below for more
37 details.
38 Cover page
40 A cover page consists of a title, and optionally the author's
41 name and institution, an abstract, and the date. See Cover page
42 macros below for more details.
43 Body Following the cover page is your document. It consists of para‐
45 graphs, headings, and lists.
46 Table of contents
48 Longer documents usually include a table of contents, which you
49 can add by placing the TC macro at the end of your document.
50 Document control registers
52 The following table lists the document control number registers. For
53 the sake of consistency, set registers related to margins at the begin‐
54 ning of your document, or just after the RP macro.
55 Margin settings
57 Reg. Definition Effective Default
59 ────────────────────────────────────────────────────────────
60 PO Page offset (left margin) next page 1i
61 LL Line length next paragraph 6i
62 LT Header/footer length next paragraph 6i
63 HM Top (header) margin next page 1i
64 FM Bottom (footer) margin next page 1i
65 ────────────────────────────────────────────────────────────
66 Text settings
68 Reg. Definition Effective Default
70 ─────────────────────────────────────────────────────────────────
71 PS Point size next paragraph 10p
72 VS Line spacing (leading) next paragraph 12p
73 PSINCR Point size increment for next heading 1p
74 section headings of increas‐
75 ing importance
76 GROWPS Heading level beyond which next heading 0
77 PSINCR is ignored
78 ─────────────────────────────────────────────────────────────────
79 Paragraph settings
81 Reg. Definition Effective Default
83 ─────────────────────────────────────────────────────────────────
84 PI Initial indent next paragraph 5n
85 PD Space between paragraphs next paragraph 0.3v
86 QI Quoted paragraph indent next paragraph 5n
87 PORPHANS Number of initial lines to next paragraph 1
88 be kept together
89 HORPHANS Number of initial lines to next heading 1
90 be kept with heading
91 ─────────────────────────────────────────────────────────────────
92 Footnote settings
94 Reg. Definition Effective Default
96 ────────────────────────────────────────────────────
97 FL Footnote length next footnote \n[LL]*5/6
98 FI Footnote indent next footnote 2n
99 FF Footnote format next footnote 0
100 FPS Point size next footnote \n[PS]-2
101 FVS Vert. spacing next footnote \n[FPS]+2
102 FPD Para. spacing next footnote \n[PD]/2
103 ────────────────────────────────────────────────────
104 Other settings
106 Reg. Definition Effective Default
108 ────────────────────────────────────────────────────────────
109 MINGW Minimum width between columns next page 2n
110 ────────────────────────────────────────────────────────────
111 Cover page macros
113 Use the following macros to create a cover page for your document in
114 the order shown.
115 .RP [no]
117 Specifies the report format for your document. The report for‐
118 mat creates a separate cover page. With no RP macro, groff
119 prints a subset of the cover page on page 1 of your document.
120 If you use the optional no argument, groff prints a title page
122 but does not repeat any of the title page information (title,
123 author, abstract, etc.) on page 1 of the document.
124 .P1 (P-one) Prints the header on page 1. The default is to suppress
126 the header.
127 .DA [xxx]
129 (optional) Print the current date, or the arguments to the macro
130 if any, on the title page (if specified) and in the footers.
131 This is the default for nroff.
132 .ND [xxx]
134 (optional) Print the current date, or the arguments to the macro
135 if any, on the title page (if specified) but not in the footers.
136 This is the default for troff.
137 .TL Specifies the document title. Groff collects text following the
139 TL macro into the title, until reaching the author name or
140 abstract.
141 .AU Specifies the author's name. You can specify multiple authors
143 by using an AU macro for each author.
144 .AI Specifies the author's institution. You can specify multiple
146 institutions.
147 .AB [no]
149 Begins the abstract. The default is to print the word ABSTRACT,
150 centered and in italics, above the text of the abstract. The
151 option no suppresses this heading.
152 .AE End the abstract.
154 Paragraphs
156 Use the PP macro to create indented paragraphs, and the LP macro to
157 create paragraphs with no initial indent.
158 The QP macro indents all text at both left and right margins. The
160 effect is identical to the HTML <BLOCKQUOTE> element. The next para‐
161 graph or heading returns margins to normal.
162 The XP macro produces an exdented paragraph. The first line of the
164 paragraph begins at the left margin, and subsequent lines are indented
165 (the opposite of PP).
166 For each of the above paragraph types, and also for any list entry
168 introduced by the IP macro (described later), the document control reg‐
169 ister PORPHANS, sets the minimum number of lines which must be printed,
170 after the start of the paragraph, and before any page break occurs. If
171 there is insufficient space remaining on the current page to accommo‐
172 date this number of lines, then a page break is forced before the first
173 line of the paragraph is printed.
174 Similarly, when a section heading (see subsection Headings below) pre‐
176 ceeds any of these paragraph types, the HORPHANS document control reg‐
177 ister specifies the minimum number of lines of the paragraph which must
178 be kept on the same page as the heading. If insufficient space remains
179 on the current page to accommodate the heading and this number of lines
180 of paragraph text, then a page break is forced before the heading is
181 printed.
182 Headings
184 Use headings to create a hierarchical structure for your document. By
185 default, the ms macros print headings in bold using the same font fam‐
186 ily and point size as the body text. For output devices which support
187 scalable fonts, this behaviour may be modified, by defining the docu‐
188 ment control registers, GROWPS and PSINCR.
189 The following heading macros are available:
191 .NH xx Numbered heading. The argument xx is either a numeric argument
193 to indicate the level of the heading, or S xx xx "..." to set
194 the section number explicitly. If you specify heading levels
195 out of sequence, such as invoking .NH 3 after .NH 1, groff
196 prints a warning on standard error.
197 If the GROWPS register is set to a value greater than the level
199 of the heading, then the point size of the heading will be
200 increased by PSINCR units over the text size specified by the PS
201 register, for each level by which the heading level is less than
202 the value of GROWPS. For example, the sequence:
203 .nr PS 10
205 .nr GROWPS 3
206 .nr PSINCR 1.5p
207 .
208 .NH 1
209 Top Level Heading
210 .
211 .NH 2
212 Second Level Heading
213 .
214 .NH 3
215 Third Level Heading
216 will cause “1. Top Level Heading” to be printed in 13pt bold
218 text, followed by “1.1. Second Level Heading” in 11.5pt bold
219 text, while “1.1.1. Third Level Heading”, and all more deeply
220 nested heading levels, will remain in the 10pt bold text which
221 is specified by the PS register.
222 Note that the value stored in PSINCR is interpreted in groff
224 basic units; the p scaling factor should be employed, when
225 assigning a value specified in points.
226 The style used to represent the section number, within a num‐
228 bered heading, is controlled by the SN-STYLE string; this may be
229 set to either the SN-DOT or the SN-NO-DOT style, (described
230 below), by aliasing SN-STYLE accordingly. By default, SN-STYLE
231 is initialised by defining the alias
232 .als SN-STYLE SN-DOT
234 it may be changed to the SN-NO-DOT style, if preferred, by
236 defining the alternative alias
237 .als SN-STYLE SN-NO-DOT
239 Any such change becomes effective with the first use of .NH,
241 after the new alias is defined.
242 After invoking .NH, the assigned heading number is available in
244 the strings SN-DOT (as it appears in the default formatting
245 style for numbered headings, with a terminating period following
246 the number), and SN-NO-DOT (with this terminating period omit‐
247 ted). The string SN is also defined, as an alias for SN-DOT; if
248 preferred, the user may redefine it as an alias for SN-NO-DOT,
249 by including the initialisation:
250 .als SN SN-NO-DOT
252 at any time; the change becomes effective with the next use of
254 .NH, after the new alias is defined.
255 .SH [xx]
257 Unnumbered subheading. The use of the optional xx argument is a
258 GNU extension, which adjusts the point size of the unnumbered
259 subheading to match that of a numbered heading, introduced using
260 .NH xx with the same value of xx. For example, given the same
261 settings for PS, GROWPS and PSINCR, as used in the preceeding
262 .NH example, the sequence:
263 .SH 2
265 An Unnumbered Subheading
266 will print “An Unnumbered Subheading” in 11.5pt bold text.
268 Highlighting
270 The ms macros provide a variety of methods to highlight or emphasize
271 text:
272 .B [txt [post [pre]]]
274 Sets its first argument in bold type. If you specify a second
275 argument, groff prints it in the previous font after the bold
276 text, with no intervening space (this allows you to set punctua‐
277 tion after the highlighted text without highlighting the punctu‐
278 ation). Similarly, it prints the third argument (if any) in the
279 previous font before the first argument. For example,
280 .B foo ) (
282 prints (foo).
284 If you give this macro no arguments, groff prints all text fol‐
286 lowing in bold until the next highlighting, paragraph, or head‐
287 ing macro.
288 .R [txt [post [pre]]]
290 Sets its first argument in roman (or regular) type. It operates
291 similarly to the B macro otherwise.
292 .I [txt [post [pre]]]
294 Sets its first argument in italic type. It operates similarly
295 to the B macro otherwise.
296 .CW [txt [post [pre]]]
298 Sets its first argument in a constant width face. It operates
299 similarly to the B macro otherwise.
300 .BI [txt [post [pre]]]
302 Sets its first argument in bold italic type. It operates simi‐
303 larly to the B macro otherwise.
304 .BX [txt]
306 Prints its argument and draws a box around it. If you want to
307 box a string that contains spaces, use a digit-width space (\0).
308 .UL [txt [post]]
310 Prints its first argument with an underline. If you specify a
311 second argument, groff prints it in the previous font after the
312 underlined text, with no intervening space.
313 .LG Prints all text following in larger type (2 points larger than
315 the current point size) until the next font size, highlighting,
316 paragraph, or heading macro. You can specify this macro multi‐
317 ple times to enlarge the point size as needed.
318 .SM Prints all text following in smaller type (2 points smaller than
320 the current point size) until the next type size, highlighting,
321 paragraph, or heading macro. You can specify this macro multi‐
322 ple times to reduce the point size as needed.
323 .NL Prints all text following in the normal point size (that is, the
325 value of the PS register).
326 \*{text\*}
328 Print the enclosed text as a superscript.
329 Indents
331 You may need to indent sections of text. A typical use for indents is
332 to create nested lists and sublists.
333 Use the RS and RE macros to start and end a section of indented text,
335 respectively. The PI register controls the amount of indent.
336 You can nest indented sections as deeply as needed by using multiple,
338 nested pairs of RS and RE.
339 Lists
341 The IP macro handles duties for all lists. Its syntax is as follows:
342 .IP [marker [width]]
344 The marker is usually a bullet character \(bu for unordered
346 lists, a number (or auto-incrementing number register) for num‐
347 bered lists, or a word or phrase for indented (glossary-style)
348 lists.
349 The width specifies the indent for the body of each list item.
351 Once specified, the indent remains the same for all list items
352 in the document until specified again.
353 Tab stops
355 Use the ta request to set tab stops as needed. Use the TA macro to
356 reset tabs to the default (every 5n). You can redefine the TA macro to
357 create a different set of default tab stops.
358 Displays and keeps
360 Use displays to show text-based examples or figures (such as code list‐
361 ings). Displays turn off filling, so lines of code can be displayed
362 as-is without inserting br requests in between each line. Displays can
363 be kept on a single page, or allowed to break across pages. The fol‐
364 lowing table shows the display types available.
365 Display macro Type of display
367 With keep No keep
368 ─────────────────────────────────────────────────────────────────
369 .DS L .LD Left-justified.
370 .DS I [indent] .ID Indented (default indent in the DI
371 register).
372 .DS B .BD Block-centered (left-justified, long‐
373 est line centered).
374 .DS C .CD Centered.
375 .DS R .RD Right-justified.
376 ─────────────────────────────────────────────────────────────────
377 Use the DE macro to end any display type. The macros Ds and De were
379 formerly provided as aliases for DS and DE, respectively, but they have
380 been removed, and should no longer be used. X11 documents which actu‐
381 ally use Ds and De always load a specific macro file from the X11 dis‐
382 tribution (macros.t) which provides proper definitions for the two
383 macros.
384 To keep text together on a page, such as a paragraph that refers to a
386 table (or list, or other item) immediately following, use the KS and KE
387 macros. The KS macro begins a block of text to be kept on a single
388 page, and the KE macro ends the block.
389 You can specify a floating keep using the KF and KE macros. If the
391 keep cannot fit on the current page, groff holds the contents of the
392 keep and allows text following the keep (in the source file) to fill in
393 the remainder of the current page. When the page breaks, whether by an
394 explicit bp request or by reaching the end of the page, groff prints
395 the floating keep at the top of the new page. This is useful for
396 printing large graphics or tables that do not need to appear exactly
397 where specified.
398 The macros B1 and B2 can be used to enclose a text within a box; .B1
400 begins the box, and .B2 ends it. Text in the box is automatically
401 placed in a diversion (keep).
402 Tables, figures, equations, and references
404 The -ms macros support the standard groff preprocessors: tbl, pic, eqn,
405 and refer. Mark text meant for preprocessors by enclosing it in pairs
406 of tags as follows:
407 .TS [H] and .TE
409 Denotes a table, to be processed by the tbl preprocessor. The
410 optional H argument instructs groff to create a running header
411 with the information up to the TH macro. Groff prints the
412 header at the beginning of the table; if the table runs onto
413 another page, groff prints the header on the next page as well.
414 .PS and .PE
416 Denotes a graphic, to be processed by the pic preprocessor. You
417 can create a pic file by hand, using the AT&T pic manual avail‐
418 able on the Web as a reference, or by using a graphics program
419 such as xfig.
420 .EQ [align] and .EN
422 Denotes an equation, to be processed by the eqn preprocessor.
423 The optional align argument can be C, L, or I to center (the
424 default), left-justify, or indent the equation.
425 .[ and .]
427 Denotes a reference, to be processed by the refer preprocessor.
428 The GNU refer(1) manual page provides a comprehensive reference
429 to the preprocessor and the format of the bibliographic data‐
430 base.
431 Footnotes
433 The ms macros provide a flexible footnote system. You can specify a
434 numbered footnote by using the \** escape, followed by the text of the
435 footnote enclosed by FS and FE macros.
436 You can specify symbolic footnotes by placing the mark character (such
438 as \(dg for the dagger character) in the body text, followed by the
439 text of the footnote enclosed by FS \(dg and FE macros.
440 You can control how groff prints footnote numbers by changing the value
442 of the FF register as follows:
443 0 Prints the footnote number as a superscript; indents the
445 footnote (default).
446 1 Prints the number followed by a period (like 1.) and
448 indents the footnote.
449 2 Like 1, without an indent.
451 3 Like 1, but prints the footnote number as a hanging para‐
453 graph.
454 You can use footnotes safely within keeps and displays, but avoid using
456 numbered footnotes within floating keeps. You can set a second \**
457 between a \** and its corresponding .FS; as long as each .FS occurs
458 after the corresponding \** and the occurrences of .FS are in the same
459 order as the corresponding occurrences of \**.
460 Headers and footers
462 There are three ways to define headers and footers:
463 · Use the strings LH, CH, and RH to set the left, center, and right
465 headers; use LF, CF, and RF to set the left, center, and right foot‐
466 ers. This works best for documents that do not distinguish between
467 odd and even pages.
468 · Use the OH and EH macros to define headers for the odd and even
470 pages; and OF and EF macros to define footers for the odd and even
471 pages. This is more flexible than defining the individual strings.
472 The syntax for these macros is as follows:
473 .OH 'left'center'right'
475 You can replace the quote (') marks with any character not appearing
477 in the header or footer text.
478 You can also redefine the PT and BT macros to change the behavior of
480 the header and footer, respectively. The header process also calls the
481 (undefined) HD macro after PT ; you can define this macro if you need
482 additional processing after printing the header (for example, to draw a
483 line below the header).
484 Margins
486 You control margins using a set of number registers. The following ta‐
487 ble lists the register names and defaults:
488 Reg. Definition Effective Default
490 ────────────────────────────────────────────────────────────
491 PO Page offset (left margin) next page 1i
492 LL Line length next paragraph 6i
493 LT Header/footer length next paragraph 6i
494 HM Top (header) margin next page 1i
495 FM Bottom (footer) margin next page 1i
496 ────────────────────────────────────────────────────────────
497 Note that there is no right margin setting. The combination of page
499 offset and line length provide the information necessary to derive the
500 right margin.
501 Multiple columns
503 The ms macros can set text in as many columns as will reasonably fit on
504 the page. The following macros are available. All of them force a
505 page break if a multi-column mode is already set. However, if the cur‐
506 rent mode is single-column, starting a multi-column mode does not force
507 a page break.
508 .1C Single-column mode.
510 .2C Two-column mode.
512 .MC [width [gutter]]
514 Multi-column mode. If you specify no arguments, it is equiva‐
515 lent to the 2C macro. Otherwise, width is the width of each
516 column and gutter is the space between columns. The MINGW num‐
517 ber register is the default gutter width.
518 Creating a table of contents
520 Wrap text that you want to appear in the table of contents in XS and XE
521 macros. Use the TC macro to print the table of contents at the end of
522 the document, resetting the page number to i (Roman numeral 1).
523 You can manually create a table of contents by specifying a page number
525 as the first argument to XS. Add subsequent entries using the XA
526 macro. For example:
527 .XS 1
529 Introduction
530 .XA 2
531 A Brief History of the Universe
532 .XA 729
533 Details of Galactic Formation
534 ...
535 .XE
536 Use the PX macro to print a manually-generated table of contents with‐
538 out resetting the page number.
539 If you give the argument no to either PX or TC, groff suppresses print‐
541 ing the title specified by the \*[TOC] string.
542 Fractional point sizes
544 Traditionally, the ms macros only support integer values for the docu‐
545 ment's font size and vertical spacing. To overcome this restriction,
546 values larger than or equal to 1000 are taken as fractional values,
547 multiplied by 1000. For example, `.nr PS 10250' sets the font size to
548 10.25 points.
549 The following four registers accept fractional point sizes: PS, VS,
551 FPS, and FVS.
552 Due to backwards compatibility, the value of VS must be smaller than
554 40000 (this is 40.0 points).
555
557 The groff ms macros are a complete re-implementation, using no original
558 AT&T code. Since they take advantage of the extended features in
559 groff, they cannot be used with AT&T troff. Other differences include:
560 · The internals of groff ms differ from the internals of Unix ms.
562 Documents that depend upon implementation details of Unix ms may not
563 format properly with groff ms.
564 · The error-handling policy of groff ms is to detect and report
566 errors, rather than silently to ignore them.
567 · Some Bell Labs localisms are not implemented by default. However,
569 if you call the otherwise undocumented SC section-header macro, you
570 will enable implementations of three other archaic Bell Labs macros:
571 UC, P1, and P2. These are not enabled by default because (a) they
572 were not documented, in the original ms manual, and (b) the P1 and
573 UC macros both collide with different macros in the Berkeley version
574 of ms.
575 These emulations are sufficient to give back the 1976 Kernighan &
577 Cherry paper Typsetting Mathematics – User's Guide its section head‐
578 ings, and restore some text that had gone missing as arguments of
579 undefined macros. No warranty express or implied is given as to how
580 well the typographic details these produce match the original Bell
581 Labs macros.
582 · Berkeley localisms, in particular the TM and CT macros, are not
584 implemented.
585 · Groff ms does not work in compatibility mode (e.g., with the -C
587 option).
588 · There is no support for typewriter-like devices.
590 · Groff ms does not provide cut marks.
592 · Multiple line spacing is not supported (use a larger vertical spac‐
594 ing instead).
595 · Some Unix ms documentation says that the CW and GW number registers
597 can be used to control the column width and gutter width, respec‐
598 tively. These number registers are not used in groff ms.
599 · Macros that cause a reset (paragraphs, headings, etc.) may change
601 the indent. Macros that change the indent do not increment or
602 decrement the indent, but rather set it absolutely. This can cause
603 problems for documents that define additional macros of their own.
604 The solution is to use not the in request but instead the RS and RE
605 macros.
606 · The number register GS is set to 1 by the groff ms macros, but is
608 not used by the Unix ms macros. Documents that need to determine
609 whether they are being formatted with Unix ms or groff ms should use
610 this number register.
611 · To make groff ms use the default page offset (which also specifies
613 the left margin), the PO number register must stay undefined until
614 the first ms macro is evaluated. This implies that PO should not be
615 used early in the document, unless it is changed also: Remember that
616 accessing an undefined register automatically defines it.
617 Strings
619 You can redefine the following strings to adapt the groff ms macros to
620 languages other than English:
621 String Default Value
623 ───────────────────────────────
624 REFERENCES References
625 ABSTRACT ABSTRACT
626 TOC Table of Contents
627 MONTH1 January
628 MONTH2 February
629 MONTH3 March
630 MONTH4 April
631 MONTH5 May
632 MONTH6 June
633 MONTH7 July
634 MONTH8 August
635 MONTH9 September
636 MONTH10 October
637 MONTH11 November
638 MONTH12 December
639 ───────────────────────────────
640 The \*- string produces an em dash — like this.
642 Use \*Q and \*U to get a left and right typographer's quote, respec‐
644 tively, in troff (and plain quotes in nroff).
645 Text Settings
648 The FAM string sets the default font family. If this string is unde‐
649 fined at initialization, it is set to Times.
650 The point size, vertical spacing, and inter-paragraph spacing for foot‐
652 notes are controlled by the number registers FPS, FVS, and FPD; at ini‐
653 tialization these are set to \n(PS-2, \n[FPS]+2, and \n(PD/2, respec‐
654 tively. If any of these registers are defined before initialization,
655 the initialization macro does not change them.
656 The hyphenation flags (as set by the hy request) are set from the HY
658 register; the default is 14.
659 Improved accent marks (as originally defined in Berkeley's ms version)
661 are available by specifying the AM macro at the beginning of your docu‐
662 ment. You can place an accent over most characters by specifying the
663 string defining the accent directly after the character. For example,
664 n\*~ produces an n with a tilde over it.
665
667 The following conventions are used for names of macros, strings and
668 number registers. External names available to documents that use the
669 groff ms macros contain only uppercase letters and digits.
670 Internally the macros are divided into modules; naming conventions are
672 as follows:
673 · Names used only within one module are of the form module*name.
675 · Names used outside the module in which they are defined are of the
677 form module@name.
678 · Names associated with a particular environment are of the form
680 environment:name; these are used only within the par module.
681 · name does not have a module prefix.
683 · Constructed names used to implement arrays are of the form
685 array!index.
686 Thus the groff ms macros reserve the following names:
688 · Names containing the characters *, @, and :.
690 · Names containing only uppercase letters and digits.
692
694 /usr/share/groff/1.20.1/tmac/ms.tmac (a wrapper file for s.tmac)
695 /usr/share/groff/1.20.1/tmac/s.tmac
696
698 groff(1), troff(1), tbl(1), pic(1), eqn(1), refer(1), Groff: The GNU
699 Implementation of troff by Trent Fisher and Werner Lemberg.
700
702 Original manual page by James Clark et al; rewritten by Larry Kollar
703 (lkollar@despammed.com).
704Groff Version 1.20.1 9 January 2009 GROFF_MS(7)