2 .do nr groff_ms_C \n[.C]
4 .TH GROFF_MS @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
6 groff_ms \- groff ms macros
9 .\" --------------------------------------------------------------------
11 .\" --------------------------------------------------------------------
14 Copyright \[co] 1989-2014 Free Software Foundation, Inc.
16 Permission is granted to make and distribute verbatim copies of
17 this manual provided the copyright notice and this permission notice
18 are preserved on all copies.
20 Permission is granted to copy and distribute modified versions of this
21 manual under the conditions for verbatim copying, provided that the
22 entire resulting derived work is distributed under the terms of a
23 permission notice identical to this one.
25 Permission is granted to copy and distribute translations of this
26 manual into another language, under the above conditions for modified
27 versions, except that this permission notice may be included in
28 translations approved by the Free Software Foundation instead of in
33 Original manual page by James Clark et al, rewritten by
34 .MT lkollar@despammed.com
39 .\" --------------------------------------------------------------------
41 .\" --------------------------------------------------------------------
62 .\" --------------------------------------------------------------------
64 .\" --------------------------------------------------------------------
66 This manual page describes the GNU version of the
75 macros are mostly compatible with the documented behavior of the 4.3
80 .I Differences from troff ms
85 macros are suitable for reports, letters, books, and technical
89 .\" --------------------------------------------------------------------
91 .\" --------------------------------------------------------------------
95 macro package expects files to have a certain amount of structure.
97 The simplest documents can begin with a paragraph macro and consist of
98 text separated by paragraph macros or even blank lines.
100 Longer documents have a structure as follows:
106 (report) macro at the beginning of the document,
108 prints the cover page information on its own page;
109 otherwise it prints the information on the
110 first page with your document text immediately following.
112 Other document formats found in AT&T
114 are specific to AT&T or Berkeley, and are not supported in
118 .B "Format and layout"
119 By setting number registers,
120 you can change your document\[aq]s type (font and size),
121 margins, spacing, headers and footers, and footnotes.
124 .I "Document control registers"
125 below for more details.
129 A cover page consists of a title,
130 and optionally the author\[aq]s name and institution,
131 an abstract, and the date.
134 .I "Cover page macros"
135 below for more details.
139 Following the cover page is your document.
140 It consists of paragraphs, headings, and lists.
143 .B "Table of contents"
144 Longer documents usually include a table of contents,
145 which you can add by placing the
147 macro at the end of your document.
150 .\" --------------------------------------------------------------------
151 .SS "Document control registers"
152 .\" --------------------------------------------------------------------
154 The following table lists the document control
157 For the sake of consistency,
158 set registers related to margins at the beginning of your document,
172 Reg. Definition Effective Default
174 PO Page offset (left margin) next page 1i
175 LL Line length next paragraph 6i
176 LT Header/footer length next paragraph 6i
177 HM Top (header) margin next page 1i
178 FM Bottom (footer) margin next page 1i
190 Reg. Definition Effective Default
194 T} next paragraph 10p
196 Line spacing (leading)
197 T} next paragraph 12p
200 for section headings of
201 increasing importance
214 .B Paragraph settings
219 Reg. Definition Effective Default
225 Space between paragraphs
226 T} next paragraph 0.3v
228 Quoted paragraph indent
231 Number of initial lines
235 Number of initial lines
236 to be kept with heading
249 Reg. Definition Effective Default
251 FL Footnote length next footnote \[rs]n[LL]*5/6
252 FI Footnote indent next footnote 2n
253 FF Footnote format next footnote 0
254 FPS Point size next footnote \[rs]n[PS]-2
255 FVS Vert.\& spacing next footnote \[rs]n[FPS]+2
256 FPD Para.\& spacing next footnote \[rs]n[PD]/2
268 Reg. Definition Effective Default
270 DD Display, table, eqn, pic spacing next para. 0.5v
271 MINGW Minimum width between columns next page 2n
278 .\" --------------------------------------------------------------------
279 .SS "Cover page macros"
280 .\" --------------------------------------------------------------------
282 Use the following macros to create a cover page for your document
287 Specifies the report format for your document.
289 The report format creates a separate cover page.
295 prints a subset of the
296 cover page on page\~1 of your document.
299 If you use the optional
303 prints a title page but
304 does not repeat any of the title page information
305 (title, author, abstract, etc.\&)
306 on page\~1 of the document.
310 (P-one) Prints the header on page\~1.
312 The default is to suppress the header.
316 (optional) Print the current date,
317 or the arguments to the macro if any,
318 on the title page (if specified)
321 This is the default for
326 (optional) Print the current date,
327 or the arguments to the macro if any,
328 on the title page (if specified)
329 but not in the footers.
331 This is the default for
336 Specifies the document title.
339 collects text following the
341 macro into the title, until reaching the author name or abstract.
345 Specifies the author\[aq]s name.
347 You can specify multiple authors by using an
349 macro for each author.
353 Specifies the author\[aq]s institution.
355 You can specify multiple institutions.
361 The default is to print the word
363 centered and in italics, above the text of the abstract.
367 suppresses this heading.
374 .\" --------------------------------------------------------------------
376 .\" --------------------------------------------------------------------
380 macro to create indented paragraphs,
383 macro to create paragraphs with no initial indent.
389 macro indents all text at both left and right margins.
391 The effect is identical to the HTML
394 The next paragraph or heading returns margins to normal.
400 macro produces an exdented paragraph.
402 The first line of the paragraph begins at
404 and subsequent lines are indented
410 For each of the above paragraph types,
411 and also for any list entry introduced by the
415 the document control register
419 number of lines which must be printed,
420 after the start of the paragraph,
421 and before any page break occurs.
423 If there is insufficient space remaining on the current page
424 to accommodate this number of lines,
425 then a page break is forced
427 the first line of the paragraph is printed.
432 when a section heading
436 precedes any of these paragraph types,
439 document control register specifies the
441 number of lines of the paragraph
442 which must be kept on the same page as the heading.
444 If insufficient space remains on the current page
445 to accommodate the heading and this number of lines of paragraph text,
446 then a page break is forced
448 the heading is printed.
451 .\" --------------------------------------------------------------------
453 .\" --------------------------------------------------------------------
455 Use headings to create a hierarchical structure
461 macros print headings in
463 using the same font family and point size as the body text.
465 For output devices which support scalable fonts,
466 this behaviour may be modified,
467 by defining the document control registers,
474 The following heading macros are available:
482 is either a numeric argument to indicate the
483 level of the heading, or
486 to set the section number explicitly.
488 If you specify heading levels out of sequence,
494 prints a warning on standard error.
499 register is set to a value
500 greater than the level of the heading,
501 then the point size of the heading will be increased by
503 units over the text size specified by the
506 for each level by which the heading level is less than
534 .RI \*(lq 1.\ Top\ Level\ Heading \*(rq
535 to be printed in 13pt
538 .RI \*(lq 1.1.\ Second\ Level\ Heading \*(rq
542 .RI \*(lq 1.1.1.\ Third\ Level\ Heading \*(rq,
543 and all more deeply nested heading levels,
544 will remain in the 10pt
546 text which is specified by the
551 Note that the value stored in
558 scaling factor should be employed,
559 when assigning a value specified in points.
562 The style used to represent the section number,
563 within a numbered heading,
567 this may be set to either the
579 is initialised by defining the alias
583 \&.als SN-STYLE SN-DOT
587 it may be changed to the
591 by defining the alternative alias
595 \&.als SN-STYLE SN-NO-DOT
599 Any such change becomes effective with the first use of
602 the new alias is defined.
607 the assigned heading number is available in the strings
609 (as it appears in the default formatting style for numbered headings,
610 with a terminating period following the number),
613 (with this terminating period omitted).
621 the user may redefine it as an alias for
624 by including the initialisation:
635 the change becomes effective with the next use of
638 the new alias is defined.
642 Unnumbered subheading.
643 The use of the optional
645 argument is a GNU extension,
646 which adjusts the point size of the unnumbered subheading
647 to match that of a numbered heading,
650 with the same value of
654 given the same settings for
659 as used in the preceding
669 An Unnumbered Subheading
675 .RI \*(lq "An Unnumbered Subheading" \*(rq
681 .\" --------------------------------------------------------------------
683 .\" --------------------------------------------------------------------
687 macros provide a variety of methods to highlight
691 .B ".B [\fItxt\fP [\fIpost\fP [\fIpre\fP]]]"
692 Sets its first argument in
695 If you specify a second argument,
697 prints it in the previous font after
698 the bold text, with no intervening space
699 (this allows you to set punctuation after
700 the highlighted text without highlighting
703 Similarly, it prints the third argument (if any)
720 If you give this macro no arguments,
722 prints all text following in bold until
723 the next highlighting, paragraph, or heading macro.
726 .B ".R [\fItxt\fP [\fIpost\fP [\fIpre\fP]]]"
727 Sets its first argument in
728 roman (or regular) type.
730 It operates similarly to the
735 .B ".I [\fItxt\fP [\fIpost\fP [\fIpre\fP]]]"
736 Sets its first argument in
738 It operates similarly to the
743 .B ".CW [\fItxt\fP [\fIpost\fP [\fIpre\fP]]]"
744 Sets its first argument in a constant width face.
746 It operates similarly to the
751 .B ".BI [\fItxt\fP [\fIpost\fP [\fIpre\fP]]]"
752 Sets its first argument in bold italic type.
754 It operates similarly to the
760 Prints its argument and draws a box around it.
762 If you want to box a string that contains spaces,
763 use a digit-width space (\[rs]0).
766 .BI ".UL [" txt " [" post ]]
767 Prints its first argument with an underline.
769 If you specify a second argument,
771 prints it in the previous font after the underlined text, with no
776 Prints all text following in larger type
777 (2\~points larger than the current point size) until
778 the next font size, highlighting, paragraph, or heading macro.
780 You can specify this macro multiple times to enlarge the point size as
785 Prints all text following in
787 (2\~points smaller than the current point size) until
788 the next type size, highlighting, paragraph, or heading macro.
790 You can specify this macro multiple times to reduce the point size as
795 Prints all text following in
796 the normal point size
797 (that is, the value of the
802 .BI \[rs]*{ text \[rs]*}
808 .\" --------------------------------------------------------------------
810 .\" --------------------------------------------------------------------
812 You may need to indent sections of text.
814 A typical use for indents is to create nested lists and sublists.
822 macros to start and end a section of indented text, respectively.
826 register controls the amount of indent.
830 You can nest indented sections as deeply as needed by using multiple,
837 .\" --------------------------------------------------------------------
839 .\" --------------------------------------------------------------------
843 macro handles duties for all lists.
845 Its syntax is as follows:
848 .BI ".IP [" marker " [" width ]]
853 is usually a bullet character
856 a number (or auto-incrementing number register) for numbered lists,
857 or a word or phrase for indented (glossary-style) lists.
862 specifies the indent for the body of each list item.
864 Once specified, the indent remains the same for all list items in the
865 document until specified again.
871 .\" --------------------------------------------------------------------
873 .\" --------------------------------------------------------------------
877 request to set tab stops as needed.
881 macro to reset tabs to the default (every 5n).
885 macro to create a different set of default tab stops.
888 .\" --------------------------------------------------------------------
889 .SS "Displays and keeps"
890 .\" --------------------------------------------------------------------
892 Use displays to show text-based examples or figures
893 (such as code listings).
895 Displays turn off filling, so lines of code can be displayed as-is
898 requests in between each line.
902 on a single page, or allowed to break across pages.
904 The following table shows the display types available.
912 Display macro Type of display
915 \&.DS L \&.LD Left-justified.
916 \&.DS I [\fIindent\fP] \&.ID T{
917 Indented (default indent in the \fBDI\fP register).
920 Block-centered (left-justified, longest line centered).
922 \&.DS C \&.CD Centered.
923 \&.DS R \&.RD Right-justified.
932 macro to end any display type.
938 were formerly provided as aliases for
942 respectively, but they have been removed, and should no longer be used.
944 X11 documents which actually use
948 always load a specific macro file from the X11 distribution (macros.t)
949 which provides proper definitions for the two macros.
954 text together on a page,
956 a paragraph that refers to a table (or list, or other item)
957 immediately following, use the
965 macro begins a block of text to be kept on a single page,
968 macro ends the block.
980 If the keep cannot fit on the current page,
982 holds the contents of the keep and allows text following
983 the keep (in the source file) to fill in the remainder of
986 When the page breaks,
987 whether by an explicit
989 request or by reaching the end of the page,
991 prints the floating keep at the top of the new page.
993 This is useful for printing large graphics or tables
994 that do not need to appear exactly where specified.
1002 can be used to enclose a text within a box;
1008 Text in the box is automatically placed in a diversion
1012 .\" --------------------------------------------------------------------
1013 .SS "Tables, figures, equations, and references"
1014 .\" --------------------------------------------------------------------
1018 macros support the standard
1027 Mark text meant for preprocessors by enclosing it
1028 in pairs of tags as follows:
1031 .BR ".TS [H]" " and " .TE
1032 Denotes a table, to be processed by the
1040 to create a running header with the information
1046 prints the header at the beginning of the table;
1047 if the table runs onto another page,
1049 prints the header on the next page as well.
1053 Denotes a graphic, to be processed by the
1059 file by hand, using the
1062 manual available on the Web as a reference,
1063 or by using a graphics program such as
1067 .BR ".EQ [\fI\,align\/\fP]" " and " .EN
1068 Denotes an equation, to be processed by the
1079 to center (the default), left-justify, or indent
1084 Denotes a reference, to be processed by the
1089 .IR @g@refer (@MAN1EXT@)
1090 manual page provides a comprehensive reference
1091 to the preprocessor and the format of the
1092 bibliographic database.
1095 .\" --------------------------------------------------------------------
1097 .\" --------------------------------------------------------------------
1101 macros provide a flexible footnote system.
1103 You can specify a numbered footnote by using the
1105 escape, followed by the text of the footnote
1114 You can specify symbolic footnotes
1115 by placing the mark character (such as
1117 for the dagger character) in the body text,
1118 followed by the text of the footnote
1129 prints footnote numbers by changing the value of the
1131 register as follows:
1137 Prints the footnote number as a superscript; indents the footnote (default).
1141 Prints the number followed by a period (like\~1.\&)
1142 and indents the footnote.
1146 Like\~1, without an indent.
1150 Like\~1, but prints the footnote number as a hanging paragraph.
1154 You can use footnotes safely within keeps and displays,
1155 but avoid using numbered footnotes within floating keeps.
1157 You can set a second
1161 and its corresponding
1169 and the occurrences of
1171 are in the same order as the corresponding occurrences of
1175 .\" --------------------------------------------------------------------
1176 .SS "Headers and footers"
1177 .\" --------------------------------------------------------------------
1179 There are three ways to define headers and footers:
1187 to set the left, center, and right headers; use
1192 to set the left, center, and right footers.
1194 This works best for documents that do not distinguish
1195 between odd and even pages.
1202 macros to define headers for the odd and even pages; and
1206 macros to define footers for the odd and even pages.
1208 This is more flexible than defining the individual strings.
1210 The syntax for these macros is as follows:
1214 .B ".OH '\fIleft\/\fP'\,\fIcenter\/\fP'\,\fIright\/\fP'"
1218 You can replace the quote (\[aq]) marks with any character not
1219 appearing in the header or footer text.
1223 You can also redefine the
1227 macros to change the behavior of
1228 the header and footer, respectively.
1230 The header process also calls the (undefined)
1234 you can define this macro if you need additional processing
1235 after printing the header
1236 (for example, to draw a line below the header).
1239 .\" --------------------------------------------------------------------
1241 .\" --------------------------------------------------------------------
1243 You control margins using a set of number registers.
1245 The following table lists the register names and defaults:
1252 Reg. Definition Effective Default
1254 PO Page offset (left margin) next page 1i
1255 LL Line length next paragraph 6i
1256 LT Header/footer length next paragraph 6i
1257 HM Top (header) margin next page 1i
1258 FM Bottom (footer) margin next page 1i
1265 Note that there is no right margin setting.
1266 The combination of page offset and line length
1267 provide the information necessary to
1268 derive the right margin.
1271 .\" --------------------------------------------------------------------
1272 .SS "Multiple columns"
1273 .\" --------------------------------------------------------------------
1277 macros can set text in as many columns as will reasonably
1280 The following macros are available.
1282 All of them force a page break if a multi-column mode is already set.
1284 However, if the current mode is single-column, starting a multi-column
1298 .BI ".MC [" width " [" gutter ]]
1301 If you specify no arguments, it is equivalent to the
1307 is the width of each column and
1309 is the space between columns.
1313 number register is the default gutter width.
1316 .\" --------------------------------------------------------------------
1317 .SS "Creating a table of contents"
1318 .\" --------------------------------------------------------------------
1320 Wrap text that you want to appear in the table of contents in
1328 macro to print the table of contents at the end of the document,
1329 resetting the page number to\~\c
1335 You can manually create a table of contents
1336 by specifying a page number as the first argument to
1339 Add subsequent entries using the
1352 A Brief History of the Universe
1354 Details of Galactic Formation
1363 macro to print a manually-generated table of contents
1364 without resetting the page number.
1368 If you give the argument
1375 suppresses printing the title
1381 .\" --------------------------------------------------------------------
1382 .SS "Fractional point sizes"
1383 .\" --------------------------------------------------------------------
1387 macros only support integer values for the document\[aq]s font size
1388 and vertical spacing.
1390 To overcome this restriction, values larger than or equal to 1000 are
1391 taken as fractional values, multiplied by 1000.
1393 For example, \[oq].nr\~PS\~10250\[cq] sets the font size to 10.25
1398 The following four registers accept fractional point sizes:
1407 Due to backwards compatibility, the value of
1409 must be smaller than 40000 (this is 40.0 points).
1412 .\" --------------------------------------------------------------------
1413 .SH "DIFFERENCES FROM troff ms"
1414 .\" --------------------------------------------------------------------
1418 macros are a complete re-implementation,
1419 using no original AT&T code.
1421 Since they take advantage of the extended features in
1423 they cannot be used with AT&T
1426 Other differences include:
1431 differ from the internals of Unix
1434 Documents that depend upon implementation details of Unix
1436 may not format properly with
1440 The error-handling policy of
1442 is to detect and report errors,
1443 rather than silently to ignore them.
1446 Some Bell Labs localisms are not implemented by default.
1448 However, if you call the otherwise undocumented
1450 section-header macro, you will enable implementations of three other
1451 archaic Bell Labs macros:
1457 These are not enabled by default because (a)\~they were not documented,
1464 macros both collide with different macros in the Berkeley version of
1468 These emulations are sufficient to give back the 1976 Kernighan\~&
1470 .I "Typesetting Mathematics \(en User\[aq]s Guide"
1471 its section headings, and restore some text that had gone missing as
1472 arguments of undefined macros.
1474 No warranty express or implied is given as to how well the typographic
1475 details these produce match the original Bell Labs macros.
1478 Berkeley localisms, in particular the
1483 are not implemented.
1487 does not work in compatibility mode (e.g., with the
1492 There is no support for typewriter-like devices.
1496 does not provide cut marks.
1499 Multiple line spacing is not supported
1500 (use a larger vertical spacing instead).
1505 documentation says that the
1509 number registers can be used to control the column width and
1510 gutter width, respectively.
1512 These number registers are not used in
1516 Macros that cause a reset
1517 (paragraphs, headings, etc.\&)
1518 may change the indent.
1520 Macros that change the indent do not increment or decrement the
1521 indent, but rather set it absolutely.
1523 This can cause problems for documents that define additional macros of
1526 The solution is to use not the
1528 request but instead the
1540 but is not used by the Unix
1544 Documents that need to determine whether they are being formatted with
1549 should use this number register.
1554 use the default page offset (which also specifies the left margin),
1557 number register must stay undefined until the first
1563 should not be used early in the document, unless it is changed also:
1564 Remember that accessing an undefined register automatically defines it.
1569 .\" --------------------------------------------------------------------
1571 .\" --------------------------------------------------------------------
1573 You can redefine the following strings to adapt the
1575 macros to languages other than English:
1580 String Default Value
1582 REFERENCES References
1584 TOC Table of Contents
1604 string produces an em dash \[em] like this.
1612 to get a left and right typographer\[aq]s quote,
1615 (and plain quotes in
1619 .\" --------------------------------------------------------------------
1621 .\" --------------------------------------------------------------------
1625 string sets the default font family.
1627 If this string is undefined at initialization,
1632 The point size, vertical spacing, and inter-paragraph spacing for
1633 footnotes are controlled by the number registers
1638 at initialization these are set to
1645 If any of these registers are defined before initialization,
1646 the initialization macro does not change them.
1650 The hyphenation flags (as set by the
1652 request) are set from the
1659 Improved accent marks
1660 (as originally defined in Berkeley\[aq]s
1663 are available by specifying the
1665 macro at the beginning of your document.
1667 You can place an accent over most characters by specifying the string
1668 defining the accent directly after the character.
1672 produces an n with a tilde over it.
1675 .\" --------------------------------------------------------------------
1676 .SH "NAMING CONVENTIONS"
1677 .\" --------------------------------------------------------------------
1679 The following conventions are used for names of macros, strings and
1682 External names available to documents that use the
1684 macros contain only uppercase letters and digits.
1688 Internally the macros are divided into modules;
1689 naming conventions are as follows:
1692 Names used only within one module are of the form
1693 .IB \%module * name\fR.
1696 Names used outside the module in which they are defined are of the form
1697 .IB \%module @ name\fR.
1700 Names associated with a particular environment are of the form
1701 .IB \%environment : name\fR;
1702 these are used only within the
1708 does not have a module prefix.
1711 Constructed names used to implement arrays are of the form
1712 .IB \%array ! index\fR.
1716 Thus the groff ms macros reserve the following names:
1719 Names containing the characters
1726 Names containing only uppercase letters and digits.
1729 .\" --------------------------------------------------------------------
1731 .\" --------------------------------------------------------------------
1733 .B @MACRODIR@/ms.tmac
1737 .B @MACRODIR@/s.tmac
1741 .\" --------------------------------------------------------------------
1744 .\" --------------------------------------------------------------------
1746 .BR groff (@MAN1EXT@),
1747 .BR @g@troff (@MAN1EXT@),
1748 .BR @g@tbl (@MAN1EXT@),
1749 .BR @g@pic (@MAN1EXT@),
1750 .BR @g@eqn (@MAN1EXT@),
1751 .BR @g@refer (@MAN1EXT@),
1752 .I Groff: The GNU Implementation of troff
1753 by Trent Fisher and Werner Lemberg.
1756 .\" --------------------------------------------------------------------
1758 .\" --------------------------------------------------------------------
1760 .\" --------------------------------------------------------------------
1762 .\" --------------------------------------------------------------------
1769 .\" Local Variables:
projects / platform / upstream / groff.git / blob