1 '\" t -- preprocess: tbl(1)
5 Copyright (c) 2014 Steffen (Daode) Nurpmeso <sdaoden@users.sf.net>.
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 MINGW Minimum width between columns next page 2n
256 .SS "Cover page macros"
258 Use the following macros to create a cover page for your document
263 Specifies the report format for your document.
264 The report format creates a separate cover page.
269 prints a subset of the
270 cover page on page\~1 of your document.
273 If you use the optional
277 prints a title page but
278 does not repeat any of the title page information
279 (title, author, abstract, etc.\&)
280 on page\~1 of the document.
284 (P-one) Prints the header on page\~1.
285 The default is to suppress the header.
289 (optional) Print the current date,
290 or the arguments to the macro if any,
291 on the title page (if specified)
293 This is the default for
298 (optional) Print the current date,
299 or the arguments to the macro if any,
300 on the title page (if specified)
301 but not in the footers.
302 This is the default for
307 Specifies the document title.
309 collects text following the
311 macro into the title, until reaching the author name or abstract.
315 Specifies the author's name.
316 You can specify multiple authors by using an
318 macro for each author.
322 Specifies the author's institution.
323 You can specify multiple institutions.
328 The default is to print the word
330 centered and in italics, above the text of the abstract.
333 suppresses this heading.
344 macro to create indented paragraphs,
347 macro to create paragraphs with no initial indent.
352 macro indents all text at both left and right margins.
353 The next paragraph or heading
354 returns margins to normal.
359 macro produces an exdented paragraph.
360 The first line of the paragraph begins at
362 and subsequent lines are indented
367 For each of the above paragraph types,
368 and also for any list entry introduced by the
372 the document control register
376 number of lines which must be printed,
377 after the start of the paragraph,
378 and before any page break occurs.
379 If there is insufficient space remaining on the current page
380 to accommodate this number of lines,
381 then a page break is forced
383 the first line of the paragraph is printed.
387 when a section heading
391 preceeds any of these paragraph types,
394 document control register specifies the
396 number of lines of the paragraph
397 which must be kept on the same page as the heading.
398 If insufficient space remains on the current page
399 to accommodate the heading and this number of lines of paragraph text,
400 then a page break is forced
402 the heading is printed.
407 Use headings to create a hierarchical structure
412 macros print headings in
414 using the same font family and point size as the body text.
415 For output devices which support scalable fonts,
416 this behaviour may be modified,
417 by defining the document control registers,
423 The following heading macros are available:
430 is either a numeric argument to indicate the
431 level of the heading, or
434 to set the section number explicitly.
435 If you specify heading levels out of sequence,
440 a warning on standard error is produced.
445 register is set to a value
446 greater than the level of the heading,
447 then the point size of the heading will be increased by
449 units over the text size specified by the
452 for each level by which the heading level is less than
479 .RI \*(lq 1.\ Top\ Level\ Heading \*(rq
480 to be printed in 13pt
483 .RI \*(lq 1.1.\ Second\ Level\ Heading \*(rq
487 .RI \*(lq 1.1.1.\ Third\ Level\ Heading \*(rq,
488 and all more deeply nested heading levels,
489 will remain in the 10pt
491 text which is specified by the
496 Note that the value stored in
503 scaling factor should be employed,
504 when assigning a value specified in points.
507 The style used to represent the section number,
508 within a numbered heading,
512 this may be set to either the
523 is initialised by defining the alias
527 \&.als SN-STYLE SN-DOT
531 it may be changed to the
535 by defining the alternative alias
539 \&.als SN-STYLE SN-NO-DOT
543 Any such change becomes effective with the first use of
546 the new alias is defined.
551 the assigned heading number is available in the strings
553 (as it appears in the default formatting style for numbered headings,
554 with a terminating period following the number),
557 (with this terminating period omitted).
564 the user may redefine it as an alias for
567 by including the initialisation:
578 the change becomes effective with the next use of
581 the new alias is defined.
585 Unnumbered subheading.
586 The use of the optional
588 argument is a GNU extension,
589 which adjusts the point size of the unnumbered subheading
590 to match that of a numbered heading,
593 with the same value of
596 given the same settings for
601 as used in the preceeding
611 An Unnumbered Subheading
617 .RI \*(lq "An Unnumbered Subheading" \*(rq
627 macros provide a variety of methods to highlight
631 .B ".B [\fItxt\fP [\fIpost\fP [\fIpre\fP]]]"
632 Sets its first argument in
634 If you specify a second argument,
635 it is printed in the previous font after
636 the bold text, with no intervening space
637 (this allows you to set punctuation after
638 the highlighted text without highlighting
640 Similarly, it prints the third argument (if any)
656 If you give this macro no arguments,
657 all the following text is printed in bold until
658 the next highlighting, paragraph, or heading macro.
661 .B ".R [\fItxt\fP [\fIpost\fP [\fIpre\fP]]]"
662 Sets its first argument in
663 roman (or regular) type.
664 It operates similarly to the
669 .B ".I [\fItxt\fP [\fIpost\fP [\fIpre\fP]]]"
670 Sets its first argument in
672 It operates similarly to the
677 .B ".CW [\fItxt\fP [\fIpost\fP [\fIpre\fP]]]"
678 Sets its first argument in a constant width face.
679 It operates similarly to the
684 .B ".BI [\fItxt\fP [\fIpost\fP [\fIpre\fP]]]"
685 Sets its first argument in bold italic type.
686 It operates similarly to the
692 Prints its argument and draws a box around it.
693 If you want to box a string that contains spaces,
694 use a digit-width space (\[rs]0).
697 .BI ".UL [" txt " [" post ]]
698 Prints its first argument with an underline.
699 If you specify a second argument,
700 it is printed in the previous font after
701 the underlined text, with no intervening space.
705 Prints all text following in larger type
706 (2\~points larger than the current point size) until
707 the next font size, highlighting, paragraph, or heading macro.
708 You can specify this macro multiple times
709 to enlarge the point size as needed.
713 Prints all text following in
715 (2\~points smaller than the current point size) until
716 the next type size, highlighting, paragraph, or heading macro.
717 You can specify this macro multiple times
718 to reduce the point size as needed.
722 Prints all text following in
723 the normal point size
724 (that is, the value of the
729 .BI \[rs]*{ text \[rs]*}
737 You may need to indent sections of text.
738 A typical use for indents is to create nested lists and sublists.
745 macros to start and end a section of indented text, respectively.
748 register controls the amount of indent.
751 You can nest indented sections as deeply as needed by
752 using multiple, nested pairs of
762 macro handles duties for all lists.
763 Its syntax is as follows:
766 .BI ".IP [" marker " [" width ]]
771 is usually a bullet character
774 a number (or auto-incrementing number register) for numbered lists,
775 or a word or phrase for indented (glossary-style) lists.
780 specifies the indent for the body of each list item.
781 Once specified, the indent remains the same for all
782 list items in the document until specified again.
792 request to set tab stops as needed.
795 macro to reset tabs to the default (every 5n).
798 macro to create a different set of default tab stops.
801 .SS "Displays and keeps"
803 Use displays to show text-based examples or figures
804 (such as code listings).
805 Displays turn off filling, so lines of code can be
806 displayed as-is without inserting
808 requests in between each line.
811 on a single page, or allowed to break across pages.
812 The following table shows the display types available.
820 Display macro Type of display
823 \&.DS L \&.LD Left-justified.
824 \&.DS I [\fIindent\fP] \&.ID T{
825 Indented (default indent in the \fBDI\fP register).
828 Block-centered (left-justified, longest line centered).
830 \&.DS C \&.CD Centered.
831 \&.DS R \&.RD Right-justified.
840 macro to end any display type.
845 were formerly provided as aliases for
849 respectively, but they have been removed, and should no longer be used.
850 X11 documents which actually use
854 always load a specific macro file from the X11 distribution (macros.t)
855 which provides proper definitions for the two macros.
859 text together on a page,
861 a paragraph that refers to a table (or list, or other item)
862 immediately following, use the
869 macro begins a block of text to be kept on a single page,
872 macro ends the block.
882 If the keep cannot fit on the current page,
884 holds the contents of the keep and allows text following
885 the keep (in the source file) to fill in the remainder of
887 When the page breaks,
888 whether by an explicit
890 request or by reaching the end of the page,
891 the floating keep is printed at the top of the new page.
892 This is useful for printing large graphics or tables
893 that do not need to appear exactly where specified.
900 can be used to enclose a text within a box;
905 Text in the box is automatically placed in a diversion
909 .SS "Tables, figures, equations, and references"
913 macros support the standard
920 Mark text meant for preprocessors by enclosing it
921 in pairs of tags as follows:
924 .BR ".TS [H]" " and " .TE
925 Denotes a table, to be processed by the
930 instructs to create a running header with the information up to the
933 The header is printed at the beginning of the table;
934 if the table runs onto another page,
935 the header is printed on the next page as well.
939 Denotes a graphic, to be processed by the
944 file by hand, using the
947 manual available on the Web as a reference,
948 or by using a graphics program such as
952 .BR ".EQ [\fI\,align\/\fP]" " and " .EN
953 Denotes an equation, to be processed by the
963 to center (the default), left-justify, or indent
968 Denotes a reference, to be processed by the
972 .IR @L_P_REFER@ (@MAN1EXT@)
973 manual page provides a comprehensive reference
974 to the preprocessor and the format of the
975 bibliographic database.
982 macros provide a flexible footnote system.
983 You can specify a numbered footnote by using the
985 escape, followed by the text of the footnote
993 You can specify symbolic footnotes
994 by placing the mark character (such as
996 for the dagger character) in the body text,
997 followed by the text of the footnote
1005 You can control how footnote numbers are printed by changing the value
1008 register as follows:
1014 Prints the footnote number as a superscript; indents the footnote (default).
1018 Prints the number followed by a period (like\~1.\&)
1019 and indents the footnote.
1023 Like\~1, without an indent.
1027 Like\~1, but prints the footnote number as a hanging paragraph.
1031 You can use footnotes safely within keeps and displays,
1032 but avoid using numbered footnotes within floating keeps.
1033 You can set a second
1037 and its corresponding
1045 and the occurrences of
1047 are in the same order as the corresponding occurrences of
1051 .SS "Headers and footers"
1053 There are three ways to define headers and footers:
1061 to set the left, center, and right headers; use
1066 to set the left, center, and right footers.
1067 This works best for documents that do not distinguish
1068 between odd and even pages.
1075 macros to define headers for the odd and even pages; and
1079 macros to define footers for the odd and even pages.
1080 This is more flexible than defining the individual strings.
1081 The syntax for these macros is as follows:
1085 .B ".OH '\fIleft\fP'\fIcenter\fP'\fIright\fP'"
1089 You can replace the quote (') marks with any character not
1090 appearing in the header or footer text.
1093 You can also redefine the
1097 macros to change the behavior of
1098 the header and footer, respectively.
1099 The header process also calls the (undefined)
1103 you can define this macro if you need additional processing
1104 after printing the header
1105 (for example, to draw a line below the header).
1110 You control margins using a set of number registers.
1111 The following table lists the register names and defaults:
1118 Reg. Definition Effective Default
1120 PO Page offset (left margin) next page 1i
1121 LL Line length next paragraph 6i
1122 LT Header/footer length next paragraph 6i
1123 HM Top (header) margin next page 1i
1124 FM Bottom (footer) margin next page 1i
1131 Note that there is no right margin setting.
1132 The combination of page offset and line length
1133 provide the information necessary to
1134 derive the right margin.
1137 .SS "Multiple columns"
1141 macros can set text in as many columns as will reasonably
1143 The following macros are available.
1144 All of them force a page break if a multi-column mode is already set.
1145 However, if the current mode is single-column, starting a multi-column
1159 .BI ".MC [" width " [" gutter ]]
1161 If you specify no arguments, it is equivalent to the
1166 is the width of each column and
1168 is the space between columns.
1171 number register is the default gutter width.
1174 .SS "Creating a table of contents"
1176 Wrap text that you want to appear in the
1177 table of contents in
1184 macro to print the table of contents at the end of the document,
1185 resetting the page number to\~\c
1190 You can manually create a table of contents
1191 by specifying a page number as the first argument to
1193 Add subsequent entries using the
1205 A Brief History of the Universe
1207 Details of Galactic Formation
1216 macro to print a manually-generated table of contents
1217 without resetting the page number.
1220 If you give the argument
1226 printing of the title specified by the
1228 string is suppressed.
1231 .SS "Fractional point sizes"
1235 macros only support integer values for the document's font size and
1237 To overcome this restriction, values larger than or equal to 1000 are taken
1238 as fractional values, multiplied by 1000.
1239 For example, `.nr\~PS\~10250' sets the font size to 10.25 points.
1242 The following four registers accept fractional point sizes:
1250 Due to backwards compatibility, the value of
1252 must be smaller than 40000 (this is 40.0 points).
1255 .SH "DIFFERENCES FROM troff ms"
1259 macros are a complete re-implementation,
1260 using no original AT&T code.
1261 Since they take advantage of the extended features in
1263 they cannot be used with AT&T
1265 Other differences include:
1270 differ from the internals of Unix
1272 Documents that depend upon implementation details of Unix
1274 may not format properly with
1278 The error-handling policy of
1280 is to detect and report errors,
1281 rather than silently to ignore them.
1284 Some Bell Labs localisms are not implemented by default.
1285 However, if you call the otherwise undocumented
1287 section-header macro, you will enable implementations of three other
1288 archaic Bell Labs macros:
1293 These are not enabled by default because (a)\~they were not documented,
1300 macros both collide with different macros in the Berkeley version of
1304 These emulations are sufficient to give back the 1976 Kernighan\~& Cherry
1306 .I "Typsetting Mathematics \(en User's Guide"
1307 its section headings, and restore some text that had gone missing as
1308 arguments of undefined macros.
1309 No warranty express or implied is given as to how well the typographic
1310 details these produce match the original Bell Labs macros.
1313 Berkeley localisms, in particular the
1318 are not implemented.
1322 does not work in compatibility mode (e.g., with the
1327 There is no support for typewriter-like devices.
1331 does not provide cut marks.
1334 Multiple line spacing is not supported
1335 (use a larger vertical spacing instead).
1340 documentation says that the
1344 number registers can be used to control the column width and
1345 gutter width, respectively.
1346 These number registers are not used in
1350 Macros that cause a reset
1351 (paragraphs, headings, etc.\&)
1352 may change the indent.
1353 Macros that change the indent do not increment or decrement
1354 the indent, but rather set it absolutely.
1355 This can cause problems for documents that define
1356 additional macros of their own.
1357 The solution is to use not the
1359 request but instead the
1371 but is not used by the Unix
1374 Documents that need to determine whether
1375 they are being formatted with Unix
1379 should use this number register.
1384 use the default page offset (which also specifies the left margin),
1387 number register must stay undefined until the first
1392 should not be used early in the document, unless it is changed also:
1393 Remember that accessing an undefined register automatically defines it.
1400 You can redefine the following strings to adapt the
1402 macros to languages other than English:
1407 String Default Value
1409 REFERENCES References
1411 TOC Table of Contents
1430 string produces an em dash \[em] like this.
1437 to get a left and right typographer's quote,
1440 (and plain quotes in
1448 string sets the default font family.
1449 If this string is undefined at initialization,
1453 The point size, vertical spacing, and inter-paragraph spacing for footnotes
1454 are controlled by the number registers
1459 at initialization these are set to
1465 If any of these registers are defined before initialization,
1466 the initialization macro does not change them.
1469 The hyphenation flags (as set by the
1471 request) are set from the
1477 Improved accent marks
1478 (as originally defined in Berkeley's
1481 are available by specifying the
1483 macro at the beginning of your document.
1484 You can place an accent over most characters
1485 by specifying the string defining the accent
1486 directly after the character.
1489 produces an n with a tilde over it.
1492 .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
1553 .BR @L_ROFF@ (@MAN1EXT@),
1554 .BR @L_TROFF@ (@MAN1EXT@),
1555 .BR @L_P_TBL@ (@MAN1EXT@),
1556 .BR @L_P_PIC@ (@MAN1EXT@),
1557 .BR @L_P_EQN@ (@MAN1EXT@),
1558 .BR @L_P_REFER@ (@MAN1EXT@),
1559 .I Groff: The GNU Implementation of troff
1560 by Trent Fisher and Werner Lemberg.
1565 Original manual page by James Clark
1567 rewritten by Larry Kollar
1568 (\fIlkollar@despammed.com\fR).