2 .TH GROFF_MS @MAN7EXT@ "@MDATE@" "groff @VERSION@"
4 groff_ms \- GNU roff manuscript macro package for formatting documents
7 .\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
8 .do nr groff_ms_C \n[.C]
12 .\" ====================================================================
14 .\" ====================================================================
16 .\" Copyright (C) 1989-2018 Free Software Foundation, Inc.
18 .\" Permission is granted to make and distribute verbatim copies of this
19 .\" manual provided the copyright notice and this permission notice are
20 .\" preserved on all copies.
22 .\" Permission is granted to copy and distribute modified versions of
23 .\" this manual under the conditions for verbatim copying, provided that
24 .\" the entire resulting derived work is distributed under the terms of
25 .\" a permission notice identical to this one.
27 .\" Permission is granted to copy and distribute translations of this
28 .\" manual into another language, under the above conditions for
29 .\" modified versions, except that this permission notice may be
30 .\" included in translations approved by the Free Software Foundation
31 .\" instead of in the original English.
34 .\" ====================================================================
36 .\" ====================================================================
50 .\" ====================================================================
52 .\" ====================================================================
54 This manual page describes the GNU version of the
63 macros are mostly compatible with the documented behavior of the 4.3
67 .I Differences from troff ms
72 macros are suitable for reports, letters, books, and technical
76 .\" ====================================================================
78 .\" ====================================================================
82 macro package expects files to have a certain amount of structure.
84 The simplest documents can begin with a paragraph macro and consist of
85 text separated by paragraph macros or even blank lines.
87 Longer documents have a structure as follows:
93 (report) macro at the beginning of the document,
95 prints the cover page information on its own page;
96 otherwise it prints the information on the
97 first page with your document text immediately following.
99 Other document formats found in AT&T
101 are specific to AT&T or Berkeley, and are not supported in
105 .B "Format and layout"
106 By setting number registers,
107 you can change your document's
108 margins, spacing, headers and footers, footnotes,
109 and the base point size for the text.
112 .I "Document control registers"
113 below for more details.
117 A cover page consists of a title,
118 and optionally the author's name and institution,
119 an abstract, and the date.
122 .I "Cover page macros"
123 below for more details.
127 Following the cover page is your document.
128 It consists of paragraphs, headings, and lists.
131 .B "Table of contents"
132 Longer documents usually include a table of contents,
133 which you can add by placing the
135 macro at the end of your document.
138 .\" ====================================================================
139 .SS "Document control registers"
140 .\" ====================================================================
142 The following table lists the document control
145 For the sake of consistency,
146 set registers related to margins at the beginning of your document,
159 Reg. Definition Effective Default
161 PO Page offset (left margin) next page 1i
162 LL Line length next paragraph 6i
163 LT Header/footer length next paragraph 6i
164 HM Top (header) margin next page 1i
165 FM Bottom (footer) margin next page 1i
177 Reg. Definition Effective Default
181 T} next paragraph 10p
183 Line spacing (leading)
184 T} next paragraph 12p
187 for section headings of
188 increasing importance
201 .B Paragraph settings
206 Reg. Definition Effective Default
212 Space between paragraphs
213 T} next paragraph 0.3v
215 Quoted paragraph indent
218 Number of initial lines
222 Number of initial lines
223 to be kept with heading
236 Reg. Definition Effective Default
238 FL Footnote length next footnote \[rs]n[LL]*5/6
239 FI Footnote indent next footnote 2n
240 FF Footnote format next footnote 0
241 FPS Point size next footnote \[rs]n[PS]\-2
242 FVS Vert.\& spacing next footnote \[rs]n[FPS]+2
243 FPD Para.\& spacing next footnote \[rs]n[PD]/2
255 Reg. Definition Effective Default
257 DD Display, table, eqn, pic spacing next para. 0.5v
258 MINGW Minimum width between columns next page 2n
264 .\" ====================================================================
265 .SS "Cover page macros"
266 .\" ====================================================================
268 Use the following macros to create a cover page for your document
273 Specifies the report format for your document.
275 The report format creates a separate cover page.
281 prints a subset of the
282 cover page on page\~1 of your document.
285 If you use the optional
289 prints a title page but
290 does not repeat any of the title page information
291 (title, author, abstract, etc.\&)
292 on page\~1 of the document.
296 (P-one) Prints the header on page\~1.
298 The default is to suppress the header.
303 (optional) Print the current date,
304 or the arguments to the macro if any,
305 on the title page (if specified)
308 This is the default for
314 (optional) Print the current date,
315 or the arguments to the macro if any,
316 on the title page (if specified)
317 but not in the footers.
319 This is the default for
324 Specifies the document title.
327 collects text following the
329 macro into the title, until reaching the author name or abstract.
333 Specifies the author's name.
335 You can specify multiple authors by using an
337 macro for each author.
341 Specifies the author's institution.
343 You can specify multiple institutions.
349 The default is to print the word
351 centered and in italics, above the text of the abstract.
355 suppresses this heading.
362 .\" ====================================================================
364 .\" ====================================================================
368 macro to create indented paragraphs,
371 macro to create paragraphs with no initial indent.
377 macro indents all text at both left and right margins
378 by the amount of the register
381 The effect is reminiscent of the HTML
385 The next paragraph or heading returns the margins to normal.
388 inserts the vertical space specified in register
390 as inter-paragraph spacing.
394 A paragraph bracketed between the macros
398 has the same appearance as a paragraph started with
400 and a following paragraph started with
407 insert the inter-paragraph spacing specified in
409 and the text is indented on both sides by the amount of register
416 can be split into further paragraphs by using
425 macro produces an \(lqexdented\(rq paragraph; that is, one with a
428 The first line of the paragraph begins at
430 and subsequent lines are indented
436 For each of the above paragraph types,
437 and also for any list entry introduced by the
441 the document control register
445 number of lines which must be printed,
446 after the start of the paragraph,
447 and before any page break occurs.
449 If there is insufficient space remaining on the current page
450 to accommodate this number of lines,
451 then a page break is forced
453 the first line of the paragraph is printed.
458 when a section heading
459 (see subsection \[lq]Headings\[rq] below)
460 precedes any of these paragraph types,
463 document control register specifies the
465 number of lines of the paragraph
466 which must be kept on the same page as the heading.
468 If insufficient space remains on the current page
469 to accommodate the heading and this number of lines of paragraph text,
470 then a page break is forced
472 the heading is printed.
475 .\" ====================================================================
477 .\" ====================================================================
479 Use headings to create a hierarchical structure
485 macros print headings in
487 using the same font family and point size as the body text.
489 For output devices which support scalable fonts,
490 this behaviour may be modified by defining the document control
498 The following heading macros are available:
506 is either a numeric argument to indicate the
507 level of the heading, or
509 .IR "xx\~xx\~" .\|.\|.\&
510 to set the section number explicitly.
512 If you specify heading levels out of sequence,
518 prints a warning on standard error.
523 register is set to a value
524 greater than the level of the heading,
525 then the point size of the heading will be increased by
527 units over the text size specified by the
530 for each level by which the heading level is less than
558 .RI \*(lq 1.\ Top\ Level\ Heading \*(rq
559 to be printed in 13pt
562 .RI \*(lq 1.1.\ Second\ Level\ Heading \*(rq
566 .RI \*(lq 1.1.1.\ Third\ Level\ Heading \*(rq,
567 and all more deeply nested heading levels,
568 will remain in the 10pt
570 text which is specified by the
575 Note that the value stored in
582 scaling factor should be employed when assigning a value specified in
586 The style used to represent the section number,
587 within a numbered heading,
591 this may be set to either the
603 is initialised by defining the alias
607 \&.als SN\-STYLE SN\-DOT
611 it may be changed to the
615 by defining the alternative alias
619 \&.als SN\-STYLE SN\-NO\-DOT
623 Any such change becomes effective with the first use of
626 the new alias is defined.
631 the assigned heading number is available in the strings
633 (as it appears in the default formatting style for numbered headings,
634 with a terminating period following the number),
637 (with this terminating period omitted).
645 the user may redefine it as an alias for
648 by including the initialisation:
653 \&.als SN SN\-NO\-DOT
659 the change becomes effective with the next use of
662 the new alias is defined.
667 Unnumbered subheading.
669 The use of the optional
671 argument is a GNU extension,
672 which adjusts the point size of the unnumbered subheading
673 to match that of a numbered heading,
676 with the same value of
680 given the same settings for
685 as used in the preceding
695 An Unnumbered Subheading
701 .RI \*(lq "An Unnumbered Subheading" \*(rq
707 .\" ====================================================================
709 .\" ====================================================================
713 macros provide a variety of methods to highlight
718 .RI " [" txt " [" post " [" pre ]]]
719 Sets its first argument in
722 If you specify a second argument,
724 prints it in the previous font after
725 the bold text, with no intervening space
726 (this allows you to set punctuation after
727 the highlighted text without highlighting
730 Similarly, it prints the third argument (if any)
747 If you give this macro no arguments,
749 prints all text following in bold until
750 the next highlighting, paragraph, or heading macro.
754 .RI " [" txt " [" post " [" pre ]]]
755 Sets its first argument in
756 roman (or regular) type.
758 It operates similarly to the
764 .RI " [" txt " [" post " [" pre ]]]
765 Sets its first argument in
767 It operates similarly to the
773 .RI " [" txt " [" post " [" pre ]]]
774 Sets its first argument in a constant-width face.
776 It operates similarly to the
782 .RI " [" txt " [" post " [" pre ]]]
783 Sets its first argument in bold italic type.
785 It operates similarly to the
792 Prints its argument and draws a box around it.
794 If you want to box a string that contains spaces,
795 use a digit-width space (\[rs]0).
799 .RI " [" txt " [" post ]]
800 Prints its first argument with an underline.
802 If you specify a second argument,
804 prints it in the previous font after the underlined text, with no
809 Prints all text following in larger type
810 (2\~points larger than the current point size) until
811 the next font size, highlighting, paragraph, or heading macro.
813 You can specify this macro multiple times to enlarge the point size as
818 Prints all text following in
820 (2\~points smaller than the current point size) until
821 the next type size, highlighting, paragraph, or heading macro.
823 You can specify this macro multiple times to reduce the point size as
828 Prints all text following in
829 the normal point size
830 (that is, the value of the
835 .BI \[rs]*{ text \[rs]*}
841 .\" ====================================================================
843 .\" ====================================================================
845 You may need to indent sections of text.
847 A typical use for indents is to create nested lists and sublists.
855 macros to start and end a section of indented text, respectively.
859 register controls the amount of indent.
863 You can nest indented sections as deeply as needed by using multiple,
870 .\" ====================================================================
872 .\" ====================================================================
876 macro handles duties for all lists.
878 Its syntax is as follows:
882 .RI " [" marker " [" width ]]
885 is usually a bullet character
888 a number (or auto-incrementing number register) for numbered lists,
889 or a word or phrase for indented (glossary-style) lists.
894 specifies the indent for the body of each list item.
896 Once specified, the indent remains the same for all list items in the
897 document until specified again.
903 .\" ====================================================================
905 .\" ====================================================================
909 request to set tab stops as needed.
913 macro to reset tabs to the default (every 5n).
917 macro to create a different set of default tab stops.
920 .\" ====================================================================
921 .SS "Displays and keeps"
922 .\" ====================================================================
924 Use displays to show text-based examples or figures
925 (such as code listings).
927 Displays turn off filling, so lines of code can be displayed as-is
930 requests in between each line.
934 on a single page, or allowed to break across pages.
936 The following table shows the display types available.
944 Display macro Type of display
947 \&.DS L \&.LD Left-justified.
948 \&.DS I [\,\fIindent\/\fP] \&.ID T{
949 Indented (default indent in the \fBDI\fP register).
952 Block-centered (left-justified, longest line centered).
954 \&.DS C \&.CD Centered.
955 \&.DS R \&.RD Right-justified.
964 macro to end any display type.
970 were formerly provided as aliases for
974 respectively, but they have been removed, and should no longer be used.
976 X11 documents which actually use
980 always load a specific macro file from the X11 distribution
982 which provides proper definitions for the two macros.
987 text together on a page,
989 a paragraph that refers to a table (or list, or other item)
990 immediately following, use the
998 macro begins a block of text to be kept on a single page,
1001 macro ends the block.
1013 If the keep cannot fit on the current page,
1015 holds the contents of the keep and allows text following
1016 the keep (in the source file) to fill in the remainder of
1019 When the page breaks,
1020 whether by an explicit
1022 request or by reaching the end of the page,
1024 prints the floating keep at the top of the new page.
1026 This is useful for printing large graphics or tables
1027 that do not need to appear exactly where specified.
1035 can be used to enclose a text within a box;
1041 Text in the box is automatically placed in a diversion
1045 .\" ====================================================================
1046 .SS "Tables, figures, equations, and references"
1047 .\" ====================================================================
1051 macros support the standard
1060 Mark text meant for preprocessors by enclosing it
1061 in pairs of tags as follows:
1064 .BR .TS " [" H "] and " .TE
1065 Denote a table to be processed by the
1073 to create a running header with the information
1079 prints the header at the beginning of the table;
1080 if the table runs onto another page,
1082 prints the header on the next page as well.
1086 Denote a graphic to be processed by the
1092 file by hand, using the
1095 manual available on the Web as a reference,
1096 or by using a graphics program such as
1101 .RI " [" align "] and "\c
1103 Denote an equation to be processed by the
1114 to center (the default), left-justify, or indent
1115 the equation, respectively.
1119 Denote a reference to be processed by the
1124 .IR @g@refer (@MAN1EXT@)
1125 manual page provides a comprehensive reference
1126 to the preprocessor and the format of the
1127 bibliographic database.
1130 .\" ====================================================================
1132 .\" ====================================================================
1136 macros provide a flexible footnote system.
1138 You can specify a numbered footnote by using the
1140 escape, followed by the text of the footnote
1149 You can specify symbolic footnotes
1150 by placing the mark character (such as
1152 for the dagger character) in the body text,
1153 followed by the text of the footnote
1164 prints footnote numbers by changing the value of the
1166 register as follows:
1172 Prints the footnote number as a superscript; indents the footnote
1177 Prints the number followed by a period (that is,\~\(lq1.\(rq\&)
1178 and indents the footnote.
1182 Like\~1, without an indent.
1186 Like\~1, but prints the footnote number as a paragraph with a hanging
1191 You can use footnotes safely within keeps and displays,
1192 but avoid using numbered footnotes within floating keeps.
1194 You can set a second
1198 and its corresponding
1206 and the occurrences of
1208 are in the same order as the corresponding occurrences of
1212 .\" ====================================================================
1213 .SS "Headers and footers"
1214 .\" ====================================================================
1216 There are three ways to define headers and footers:
1224 to set the left, center, and right headers.
1230 to set the left, center, and right footers.
1232 The string-setting approach works best for documents that do not
1233 distinguish between odd and even pages.
1240 macros to define headers for the odd and even pages,
1245 macros to define footers for the odd and even pages.
1247 This is more flexible than defining the individual strings.
1249 The syntax for these macros is as follows:
1253 .BI . XX " \[aq]" left \[aq] center \[aq] right \[aq]
1259 is one of the foregoing four macros and each of
1264 is text of your choice.
1266 You can replace the quote (\[aq]) marks with any character not
1267 appearing in the header or footer text.
1271 You can redefine the
1275 macros to change the behavior of
1276 the header and footer, respectively.
1278 The header process also calls the (undefined)
1282 you can define this macro if you need additional processing
1283 after printing the header
1284 (for example, to draw a line below the header).
1287 .\" ====================================================================
1289 .\" ====================================================================
1291 You control margins using a set of number registers.
1293 The following table lists the register names and defaults:
1300 Reg. Definition Effective Default
1302 PO Page offset (left margin) next page 1i
1303 LL Line length next paragraph 6i
1304 LT Header/footer length next paragraph 6i
1305 HM Top (header) margin next page 1i
1306 FM Bottom (footer) margin next page 1i
1313 Note that there is no right margin setting.
1314 The combination of page offset and line length
1315 provide the information necessary to
1316 derive the right margin.
1319 .\" ====================================================================
1320 .SS "Multiple columns"
1321 .\" ====================================================================
1325 macros can set text in as many columns as will reasonably
1328 The following macros are available.
1330 All of them force a page break if a multi-column mode is already set.
1332 However, if the current mode is single-column, starting a multi-column
1347 .RI " [" column-width " [" gutter-width ]]
1350 If you specify no arguments, it is equivalent to the
1356 is the width of each column and
1358 is the space between columns.
1362 number register is the default gutter width.
1365 .\" ====================================================================
1366 .SS "Creating a table of contents"
1367 .\" ====================================================================
1369 Wrap text that you want to appear in the table of contents in
1377 macro to print the table of contents at the end of the document,
1378 resetting the page number to\~\c
1384 You can manually create a table of contents
1385 by specifying a page number as the first argument to
1388 Add subsequent entries using the
1401 A Brief History of the Universe
1403 Details of Galactic Formation
1412 macro to print a manually-generated table of contents
1413 without resetting the page number.
1417 If you give the argument
1424 suppresses printing the title
1430 .\" ====================================================================
1431 .SS "Fractional point sizes"
1432 .\" ====================================================================
1436 macros only support integer values for the document's font size
1437 and vertical spacing.
1439 To overcome this restriction, values larger than or equal to 1000 are
1440 taken as fractional values, multiplied by 1000.
1442 For example, \[oq].nr\~PS\~10250\[cq] sets the font size to 10.25
1447 The following four registers accept fractional point sizes:
1456 Due to backwards compatibility, the value of
1458 must be smaller than 40000 (this is 40.0 points).
1461 .\" ====================================================================
1462 .SH "DIFFERENCES FROM troff ms"
1463 .\" ====================================================================
1467 macros are a complete re-implementation,
1468 using no original AT&T code.
1470 Since they take advantage of the extended features in
1472 they cannot be used with AT&T
1475 Other differences include:
1480 differ from the internals of Unix
1483 Documents that depend upon implementation details of Unix
1485 may not format properly with
1489 The error-handling policy of
1491 is to detect and report errors,
1492 rather than silently to ignore them.
1495 Some Bell Labs localisms are not implemented by default.
1497 However, if you call the otherwise undocumented
1499 section-header macro, you will enable implementations of three other
1500 archaic Bell Labs macros:
1506 These are not enabled by default because (a)\~they were not documented,
1513 macros both collide with different macros in the Berkeley version of
1517 These emulations are sufficient to give back the 1976 Kernighan\~&
1519 .I "Typesetting Mathematics \(en User's Guide"
1520 its section headings, and restore some text that had gone missing as
1521 arguments of undefined macros.
1523 No warranty express or implied is given as to how well the typographic
1524 details these produce match the original Bell Labs macros.
1527 Berkeley localisms, in particular the
1532 are not implemented.
1536 does not work in compatibility mode (e.g., with the
1541 There is no support for typewriter-like devices.
1545 does not provide cut marks.
1548 Multiple line spacing is not supported
1549 (use a larger vertical spacing instead).
1554 documentation says that the
1558 number registers can be used to control the column width and
1559 gutter width, respectively.
1561 These number registers are not used in
1565 Macros that cause a reset
1566 (paragraphs, headings, etc.\&)
1567 may change the indent.
1569 Macros that change the indent do not increment or decrement the
1570 indent, but rather set it absolutely.
1572 This can cause problems for documents that define additional macros of
1575 The solution is to use not the
1577 request but instead the
1589 but is not used by the Unix
1593 Documents that need to determine whether they are being formatted with
1598 should use this number register.
1603 use the default page offset (which also specifies the left margin),
1606 number register must stay undefined until the first
1612 should not be used early in the document, unless it is changed also:
1613 remember that accessing an undefined register automatically defines it.
1618 .\" ====================================================================
1620 .\" ====================================================================
1622 You can redefine the following strings to adapt the
1624 macros to languages other than English:
1629 String Default Value
1631 REFERENCES References
1633 TOC Table of Contents
1654 string produces an em dash\[em]like this.
1662 to get a left and right typographer's quote,
1665 (and plain quotes in
1669 .\" ====================================================================
1671 .\" ====================================================================
1675 string sets the default font family.
1677 If this string is undefined at initialization,
1682 The point size, vertical spacing, and inter-paragraph spacing for
1683 footnotes are controlled by the number registers
1688 at initialization these are set to
1695 If any of these registers are defined before initialization,
1696 the initialization macro does not change them.
1700 The hyphenation flags (as set by the
1702 request) are set from the
1709 Improved accent marks
1710 (as originally defined in Berkeley's
1713 are available by specifying the
1715 macro at the beginning of your document.
1717 You can place an accent over most characters by specifying the string
1718 defining the accent directly after the character.
1722 produces an n with a tilde over it.
1725 .\" ====================================================================
1726 .SH "NAMING CONVENTIONS"
1727 .\" ====================================================================
1729 The following conventions are used for names of macros, strings, and
1732 External names available to documents that use the
1734 macros contain only uppercase letters and digits.
1738 Internally the macros are divided into modules;
1739 naming conventions are as follows:
1742 Names used only within one module are of the form
1743 .IB \%module * name\fR.
1746 Names used outside the module in which they are defined are of the form
1747 .IB \%module @ name\fR.
1750 Names associated with a particular environment are of the form
1751 .IB \%environment : name\fR;
1752 these are used only within the
1758 does not have a module prefix.
1761 Constructed names used to implement arrays are of the form
1762 .IB \%array ! index\fR.
1766 Thus the groff ms macros reserve the following names:
1769 Names containing the characters
1776 Names containing only uppercase letters and digits.
1779 .\" ====================================================================
1781 .\" ====================================================================
1783 .I @MACRODIR@/ms.tmac
1787 .I @MACRODIR@/s.tmac
1791 .\" ====================================================================
1793 .\" ====================================================================
1794 The GNU version of the
1796 macro package was written by James Clark and contributors.
1798 This document was (re-)written by
1799 .MT lkollar@\:despammed.com
1804 .\" ====================================================================
1806 .\" ====================================================================
1808 .BR groff (@MAN1EXT@),
1809 .BR @g@troff (@MAN1EXT@),
1810 .BR @g@tbl (@MAN1EXT@),
1811 .BR @g@pic (@MAN1EXT@),
1812 .BR @g@eqn (@MAN1EXT@),
1813 .BR @g@refer (@MAN1EXT@)
1817 .IR "Groff: The GNU Implementation of troff" ,
1818 by Trent A.\& Fisher and Werner Lemberg
1821 .\" Restore compatibility mode (for, e.g., Solaris 10/11).
1825 .\" Local Variables:
1828 .\" vim: set filetype=groff: