1 '\" t -- preprocess: tbl(1)
5 Copyright (c) 2014 - 2017 Steffen (Daode) Nurpmeso <steffen@sdaoden.eu>.
7 Copyright (C) 1989 - 1995, 2001 - 2007
8 Free Software Foundation, Inc.
10 Permission is granted to make and distribute verbatim copies of
11 this manual provided the copyright notice and this permission notice
12 are preserved on all copies.
14 Permission is granted to copy and distribute modified versions of this
15 manual under the conditions for verbatim copying, provided that the
16 entire resulting derived work is distributed under the terms of a
17 permission notice identical to this one.
19 Permission is granted to copy and distribute translations of this
20 manual into another language, under the above conditions for modified
21 versions, except that this permission notice may be included in
22 translations approved by the Free Software Foundation instead of in
26 .do nr groff_ms_C \n[.C]
29 .TH @U_ROFF@_MS @MAN7EXT@ "@MDATE@" "@T_ROFF@ v@VERSION@"
34 @L_ROFF@_ms \- @T_ROFF@ ms macros
62 macros are mostly compatible with the
63 documented behavior of the 4.3
68 .I Differences from troff ms
72 macros are suitable for reports, letters, books, and
73 technical documentation.
80 macro package expects files to have
81 a certain amount of structure.
82 The simplest documents can begin with a paragraph macro
83 and consist of text separated by paragraph macros
85 Longer documents have a structure as follows:
91 (report) macro at the beginning of the document,
93 prints the cover page information on its own page;
94 otherwise it prints the information on the
95 first page with your document text immediately following.
96 Other document formats found in AT&T
99 or Berkeley, and are not supported in
103 .B "Format and layout"
104 By setting number registers,
105 you can change your document's type (font and size),
106 margins, spacing, headers and footers, and footnotes.
108 .I "Document control registers"
109 below for more details.
113 A cover page consists of a title,
114 and optionally the author's name and institution,
115 an abstract, and the date.
117 .I "Cover page macros"
118 below for more details.
122 Following the cover page is your document.
123 It consists of paragraphs, headings, and lists.
126 .B "Table of contents"
127 Longer documents usually include a table of contents,
128 which you can add by placing the
130 macro at the end of your document.
133 .SS "Document control registers"
135 The following table lists the document control
137 For the sake of consistency,
138 set registers related to margins at the beginning of your document,
151 Reg. Definition Effective Default
153 PO Page offset (left margin) next page 1i
154 LL Line length next paragraph 6i
155 LT Header/footer length next paragraph 6i
156 HM Top (header) margin next page 1i
157 FM Bottom (footer) margin next page 1i
169 Reg. Definition Effective Default
173 T} next paragraph 10p
175 Line spacing (leading)
176 T} next paragraph 12p
179 for section headings of
180 increasing importance
193 .B Paragraph settings
198 Reg. Definition Effective Default
204 Space between paragraphs
205 T} next paragraph 0.3v
207 Quoted paragraph indent
210 Number of initial lines
214 Number of initial lines
215 to be kept with heading
228 Reg. Definition Effective Default
230 FL Footnote length next footnote \[rs]n[LL]*5/6
231 FI Footnote indent next footnote 2n
232 FF Footnote format next footnote 0
233 FPS Point size next footnote \[rs]n[PS]-2
234 FVS Vert.\& spacing next footnote \[rs]n[FPS]+2
235 FPD Para.\& spacing next footnote \[rs]n[PD]/2
247 Reg. Definition Effective Default
249 DD Display, table, eqn, pic spacing next para. 0.5v
250 MINGW Minimum width between columns next page 2n
257 .SS "Cover page macros"
259 Use the following macros to create a cover page for your document
264 Specifies the report format for your document.
265 The report format creates a separate cover page.
270 prints a subset of the
271 cover page on page\~1 of your document.
274 If you use the optional
278 prints a title page but
279 does not repeat any of the title page information
280 (title, author, abstract, etc.\&)
281 on page\~1 of the document.
285 (P-one) Prints the header on page\~1.
286 The default is to suppress the header.
290 (optional) Print the current date,
291 or the arguments to the macro if any,
292 on the title page (if specified)
294 This is the default for
299 (optional) Print the current date,
300 or the arguments to the macro if any,
301 on the title page (if specified)
302 but not in the footers.
303 This is the default for
308 Specifies the document title.
310 collects text following the
312 macro into the title, until reaching the author name or abstract.
316 Specifies the author's name.
317 You can specify multiple authors by using an
319 macro for each author.
323 Specifies the author's institution.
324 You can specify multiple institutions.
329 The default is to print the word
331 centered and in italics, above the text of the abstract.
334 suppresses this heading.
345 macro to create indented paragraphs,
348 macro to create paragraphs with no initial indent.
353 macro indents all text at both left and right margins.
354 The next paragraph or heading
355 returns margins to normal.
360 macro produces an exdented paragraph.
361 The first line of the paragraph begins at
363 and subsequent lines are indented
368 For each of the above paragraph types,
369 and also for any list entry introduced by the
373 the document control register
377 number of lines which must be printed,
378 after the start of the paragraph,
379 and before any page break occurs.
380 If there is insufficient space remaining on the current page
381 to accommodate this number of lines,
382 then a page break is forced
384 the first line of the paragraph is printed.
388 when a section heading
392 precedes any of these paragraph types,
395 document control register specifies the
397 number of lines of the paragraph
398 which must be kept on the same page as the heading.
399 If insufficient space remains on the current page
400 to accommodate the heading and this number of lines of paragraph text,
401 then a page break is forced
403 the heading is printed.
408 Use headings to create a hierarchical structure
413 macros print headings in
415 using the same font family and point size as the body text.
416 For output devices which support scalable fonts,
417 this behaviour may be modified,
418 by defining the document control registers,
424 The following heading macros are available:
431 is either a numeric argument to indicate the
432 level of the heading, or
435 to set the section number explicitly.
436 If you specify heading levels out of sequence,
441 a warning on standard error is produced.
446 register is set to a value
447 greater than the level of the heading,
448 then the point size of the heading will be increased by
450 units over the text size specified by the
453 for each level by which the heading level is less than
480 .RI \*(lq 1.\ Top\ Level\ Heading \*(rq
481 to be printed in 13pt
484 .RI \*(lq 1.1.\ Second\ Level\ Heading \*(rq
488 .RI \*(lq 1.1.1.\ Third\ Level\ Heading \*(rq,
489 and all more deeply nested heading levels,
490 will remain in the 10pt
492 text which is specified by the
497 Note that the value stored in
504 scaling factor should be employed,
505 when assigning a value specified in points.
508 The style used to represent the section number,
509 within a numbered heading,
513 this may be set to either the
524 is initialised by defining the alias
528 \&.als SN-STYLE SN-DOT
532 it may be changed to the
536 by defining the alternative alias
540 \&.als SN-STYLE SN-NO-DOT
544 Any such change becomes effective with the first use of
547 the new alias is defined.
552 the assigned heading number is available in the strings
554 (as it appears in the default formatting style for numbered headings,
555 with a terminating period following the number),
558 (with this terminating period omitted).
565 the user may redefine it as an alias for
568 by including the initialisation:
579 the change becomes effective with the next use of
582 the new alias is defined.
586 Unnumbered subheading.
587 The use of the optional
589 argument is a GNU extension,
590 which adjusts the point size of the unnumbered subheading
591 to match that of a numbered heading,
594 with the same value of
597 given the same settings for
602 as used in the preceding
612 An Unnumbered Subheading
618 .RI \*(lq "An Unnumbered Subheading" \*(rq
628 macros provide a variety of methods to highlight
632 .B ".B [\fItxt\fP [\fIpost\fP [\fIpre\fP]]]"
633 Sets its first argument in
635 If you specify a second argument,
636 it is printed in the previous font after
637 the bold text, with no intervening space
638 (this allows you to set punctuation after
639 the highlighted text without highlighting
641 Similarly, it prints the third argument (if any)
657 If you give this macro no arguments,
658 all the following text is printed in bold until
659 the next highlighting, paragraph, or heading macro.
662 .B ".R [\fItxt\fP [\fIpost\fP [\fIpre\fP]]]"
663 Sets its first argument in
664 roman (or regular) type.
665 It operates similarly to the
670 .B ".I [\fItxt\fP [\fIpost\fP [\fIpre\fP]]]"
671 Sets its first argument in
673 It operates similarly to the
678 .B ".CW [\fItxt\fP [\fIpost\fP [\fIpre\fP]]]"
679 Sets its first argument in a constant width face.
680 It operates similarly to the
685 .B ".BI [\fItxt\fP [\fIpost\fP [\fIpre\fP]]]"
686 Sets its first argument in bold italic type.
687 It operates similarly to the
693 Prints its argument and draws a box around it.
694 If you want to box a string that contains spaces,
695 use a digit-width space (\[rs]0).
698 .BI ".UL [" txt " [" post ]]
699 Prints its first argument with an underline.
700 If you specify a second argument,
701 it is printed in the previous font after
702 the underlined text, with no intervening space.
706 Prints all text following in larger type
707 (2\~points larger than the current point size) until
708 the next font size, highlighting, paragraph, or heading macro.
709 You can specify this macro multiple times
710 to enlarge the point size as needed.
714 Prints all text following in
716 (2\~points smaller than the current point size) until
717 the next type size, highlighting, paragraph, or heading macro.
718 You can specify this macro multiple times
719 to reduce the point size as needed.
723 Prints all text following in
724 the normal point size
725 (that is, the value of the
730 .BI \[rs]*{ text \[rs]*}
738 You may need to indent sections of text.
739 A typical use for indents is to create nested lists and sublists.
746 macros to start and end a section of indented text, respectively.
749 register controls the amount of indent.
752 You can nest indented sections as deeply as needed by
753 using multiple, nested pairs of
763 macro handles duties for all lists.
764 Its syntax is as follows:
767 .BI ".IP [" marker " [" width ]]
772 is usually a bullet character
775 a number (or auto-incrementing number register) for numbered lists,
776 or a word or phrase for indented (glossary-style) lists.
781 specifies the indent for the body of each list item.
782 Once specified, the indent remains the same for all
783 list items in the document until specified again.
793 request to set tab stops as needed.
796 macro to reset tabs to the default (every 5n).
799 macro to create a different set of default tab stops.
802 .SS "Displays and keeps"
804 Use displays to show text-based examples or figures
805 (such as code listings).
806 Displays turn off filling, so lines of code can be
807 displayed as-is without inserting
809 requests in between each line.
812 on a single page, or allowed to break across pages.
813 The following table shows the display types available.
821 Display macro Type of display
824 \&.DS L \&.LD Left-justified.
825 \&.DS I [\fIindent\fP] \&.ID T{
826 Indented (default indent in the \fBDI\fP register).
829 Block-centered (left-justified, longest line centered).
831 \&.DS C \&.CD Centered.
832 \&.DS R \&.RD Right-justified.
841 macro to end any display type.
846 were formerly provided as aliases for
850 respectively, but they have been removed, and should no longer be used.
851 X11 documents which actually use
855 always load a specific macro file from the X11 distribution (macros.t)
856 which provides proper definitions for the two macros.
860 text together on a page,
862 a paragraph that refers to a table (or list, or other item)
863 immediately following, use the
870 macro begins a block of text to be kept on a single page,
873 macro ends the block.
883 If the keep cannot fit on the current page,
885 holds the contents of the keep and allows text following
886 the keep (in the source file) to fill in the remainder of
888 When the page breaks,
889 whether by an explicit
891 request or by reaching the end of the page,
892 the floating keep is printed at the top of the new page.
893 This is useful for printing large graphics or tables
894 that do not need to appear exactly where specified.
901 can be used to enclose a text within a box;
906 Text in the box is automatically placed in a diversion
910 .SS "Tables, figures, equations, and references"
914 macros support the standard
921 Mark text meant for preprocessors by enclosing it
922 in pairs of tags as follows:
925 .BR ".TS [H]" " and " .TE
926 Denotes a table, to be processed by the
931 instructs to create a running header with the information up to the
934 The header is printed at the beginning of the table;
935 if the table runs onto another page,
936 the header is printed on the next page as well.
940 Denotes a graphic, to be processed by the
945 file by hand, using the
948 manual available on the Web as a reference,
949 or by using a graphics program such as
953 .BR ".EQ [\fI\,align\/\fP]" " and " .EN
954 Denotes an equation, to be processed by the
964 to center (the default), left-justify, or indent
969 Denotes a reference, to be processed by the
973 .IR @L_P_REFER@ (@MAN1EXT@)
974 manual page provides a comprehensive reference
975 to the preprocessor and the format of the
976 bibliographic database.
983 macros provide a flexible footnote system.
984 You can specify a numbered footnote by using the
986 escape, followed by the text of the footnote
994 You can specify symbolic footnotes
995 by placing the mark character (such as
997 for the dagger character) in the body text,
998 followed by the text of the footnote
1006 You can control how footnote numbers are printed by changing the value
1009 register as follows:
1015 Prints the footnote number as a superscript; indents the footnote (default).
1019 Prints the number followed by a period (like\~1.\&)
1020 and indents the footnote.
1024 Like\~1, without an indent.
1028 Like\~1, but prints the footnote number as a hanging paragraph.
1032 You can use footnotes safely within keeps and displays,
1033 but avoid using numbered footnotes within floating keeps.
1034 You can set a second
1038 and its corresponding
1046 and the occurrences of
1048 are in the same order as the corresponding occurrences of
1052 .SS "Headers and footers"
1054 There are three ways to define headers and footers:
1062 to set the left, center, and right headers; use
1067 to set the left, center, and right footers.
1068 This works best for documents that do not distinguish
1069 between odd and even pages.
1076 macros to define headers for the odd and even pages; and
1080 macros to define footers for the odd and even pages.
1081 This is more flexible than defining the individual strings.
1082 The syntax for these macros is as follows:
1086 .B ".OH '\fIleft\/\fP'\,\fIcenter\/\fP'\,\fIright\/\fP'"
1090 You can replace the quote (') marks with any character not
1091 appearing in the header or footer text.
1094 You can also redefine the
1098 macros to change the behavior of
1099 the header and footer, respectively.
1100 The header process also calls the (undefined)
1104 you can define this macro if you need additional processing
1105 after printing the header
1106 (for example, to draw a line below the header).
1111 You control margins using a set of number registers.
1112 The following table lists the register names and defaults:
1119 Reg. Definition Effective Default
1121 PO Page offset (left margin) next page 1i
1122 LL Line length next paragraph 6i
1123 LT Header/footer length next paragraph 6i
1124 HM Top (header) margin next page 1i
1125 FM Bottom (footer) margin next page 1i
1132 Note that there is no right margin setting.
1133 The combination of page offset and line length
1134 provide the information necessary to
1135 derive the right margin.
1138 .SS "Multiple columns"
1142 macros can set text in as many columns as will reasonably
1144 The following macros are available.
1145 All of them force a page break if a multi-column mode is already set.
1146 However, if the current mode is single-column, starting a multi-column
1160 .BI ".MC [" width " [" gutter ]]
1162 If you specify no arguments, it is equivalent to the
1167 is the width of each column and
1169 is the space between columns.
1172 number register is the default gutter width.
1175 .SS "Creating a table of contents"
1177 Wrap text that you want to appear in the
1178 table of contents in
1185 macro to print the table of contents at the end of the document,
1186 resetting the page number to\~\c
1191 You can manually create a table of contents
1192 by specifying a page number as the first argument to
1194 Add subsequent entries using the
1206 A Brief History of the Universe
1208 Details of Galactic Formation
1217 macro to print a manually-generated table of contents
1218 without resetting the page number.
1221 If you give the argument
1227 printing of the title specified by the
1229 string is suppressed.
1232 .SS "Fractional point sizes"
1236 macros only support integer values for the document's font size and
1238 To overcome this restriction, values larger than or equal to 1000 are taken
1239 as fractional values, multiplied by 1000.
1240 For example, `.nr\~PS\~10250' sets the font size to 10.25 points.
1243 The following four registers accept fractional point sizes:
1251 Due to backwards compatibility, the value of
1253 must be smaller than 40000 (this is 40.0 points).
1256 .SH "DIFFERENCES FROM troff ms"
1260 macros are a complete re-implementation,
1261 using no original AT&T code.
1262 Since they take advantage of the extended features in
1264 they cannot be used with AT&T
1266 Other differences include:
1271 differ from the internals of Unix
1273 Documents that depend upon implementation details of Unix
1275 may not format properly with
1279 The error-handling policy of
1281 is to detect and report errors,
1282 rather than silently to ignore them.
1285 Some Bell Labs localisms are not implemented by default.
1286 However, if you call the otherwise undocumented
1288 section-header macro, you will enable implementations of three other
1289 archaic Bell Labs macros:
1294 These are not enabled by default because (a)\~they were not documented,
1301 macros both collide with different macros in the Berkeley version of
1305 These emulations are sufficient to give back the 1976 Kernighan\~& Cherry
1307 .I "Typesetting Mathematics \(en User's Guide"
1308 its section headings, and restore some text that had gone missing as
1309 arguments of undefined macros.
1310 No warranty express or implied is given as to how well the typographic
1311 details these produce match the original Bell Labs macros.
1314 Berkeley localisms, in particular the
1319 are not implemented.
1323 does not work in compatibility mode (e.g., with the
1328 There is no support for typewriter-like devices.
1332 does not provide cut marks.
1335 Multiple line spacing is not supported
1336 (use a larger vertical spacing instead).
1341 documentation says that the
1345 number registers can be used to control the column width and
1346 gutter width, respectively.
1347 These number registers are not used in
1351 Macros that cause a reset
1352 (paragraphs, headings, etc.\&)
1353 may change the indent.
1354 Macros that change the indent do not increment or decrement
1355 the indent, but rather set it absolutely.
1356 This can cause problems for documents that define
1357 additional macros of their own.
1358 The solution is to use not the
1360 request but instead the
1372 but is not used by the Unix
1375 Documents that need to determine whether
1376 they are being formatted with Unix
1380 should use this number register.
1385 use the default page offset (which also specifies the left margin),
1388 number register must stay undefined until the first
1393 should not be used early in the document, unless it is changed also:
1394 Remember that accessing an undefined register automatically defines it.
1401 You can redefine the following strings to adapt the
1403 macros to languages other than English:
1408 String Default Value
1410 REFERENCES References
1412 TOC Table of Contents
1431 string produces an em dash \[em] like this.
1438 to get a left and right typographer's quote,
1441 (and plain quotes in
1449 string sets the default font family.
1450 If this string is undefined at initialization,
1454 The point size, vertical spacing, and inter-paragraph spacing for footnotes
1455 are controlled by the number registers
1460 at initialization these are set to
1466 If any of these registers are defined before initialization,
1467 the initialization macro does not change them.
1470 The hyphenation flags (as set by the
1472 request) are set from the
1478 Improved accent marks
1479 (as originally defined in Berkeley's
1482 are available by specifying the
1484 macro at the beginning of your document.
1485 You can place an accent over most characters
1486 by specifying the string defining the accent
1487 directly after the character.
1490 produces an n with a tilde over it.
1493 .SH "NAMING CONVENTIONS"
1495 The following conventions are used for names of macros, strings and
1497 External names available to documents that use the
1499 macros contain only uppercase letters and digits.
1502 Internally the macros are divided into modules;
1503 naming conventions are as follows:
1506 Names used only within one module are of the form
1507 .IB \%module * name\fR.
1510 Names used outside the module in which they are defined are of the form
1511 .IB \%module @ name\fR.
1514 Names associated with a particular environment are of the form
1515 .IB \%environment : name\fR;
1516 these are used only within the
1522 does not have a module prefix.
1525 Constructed names used to implement arrays are of the form
1526 .IB \%array ! index\fR.
1529 Thus the @T_ROFF@ ms macros reserve the following names:
1532 Names containing the characters
1539 Names containing only uppercase letters and digits.
1544 .B @MACRODIR@/ms.tmac
1548 .B @MACRODIR@/s.tmac
1554 .BR @L_ROFF@ (@MAN1EXT@),
1555 .BR @L_TROFF@ (@MAN1EXT@),
1556 .BR @L_P_TBL@ (@MAN1EXT@),
1557 .BR @L_P_PIC@ (@MAN1EXT@),
1558 .BR @L_P_EQN@ (@MAN1EXT@),
1559 .BR @L_P_REFER@ (@MAN1EXT@),
1560 .I Groff: The GNU Implementation of troff
1561 by Trent Fisher and Werner Lemberg.
1566 Original manual page by James Clark
1568 rewritten by Larry Kollar
1569 (\fIlkollar@despammed.com\fR).