3 Copyright (C) 1989-1995, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2009
4 Free Software Foundation, Inc.
6 Permission is granted to make and distribute verbatim copies of
7 this manual provided the copyright notice and this permission notice
8 are preserved on all copies.
10 Permission is granted to copy and distribute modified versions of this
11 manual under the conditions for verbatim copying, provided that the
12 entire resulting derived work is distributed under the terms of a
13 permission notice identical to this one.
15 Permission is granted to copy and distribute translations of this
16 manual into another language, under the above conditions for modified
17 versions, except that this permission notice may be included in
18 translations approved by the Free Software Foundation instead of in
22 .do nr groff_ms_C \n[.C]
25 .TH GROFF_MS @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
31 groff_ms \- groff ms macros
59 This manual page describes the GNU version of the
67 macros are mostly compatible with the
68 documented behavior of the 4.3
73 .I Differences from troff ms
77 macros are suitable for reports, letters, books, and
78 technical documentation.
86 macro package expects files to have
87 a certain amount of structure.
88 The simplest documents can begin with a paragraph macro
89 and consist of text separated by paragraph macros
91 Longer documents have a structure as follows:
97 (report) macro at the beginning of the document,
99 prints the cover page information on its own page;
100 otherwise it prints the information on the
101 first page with your document text immediately following.
102 Other document formats found in AT&T
105 or Berkeley, and are not supported in
109 .B "Format and layout"
110 By setting number registers,
111 you can change your document's type (font and size),
112 margins, spacing, headers and footers, and footnotes.
114 .I "Document control registers"
115 below for more details.
119 A cover page consists of a title,
120 and optionally the author's name and institution,
121 an abstract, and the date.
123 .I "Cover page macros"
124 below for more details.
128 Following the cover page is your document.
129 It consists of paragraphs, headings, and lists.
132 .B "Table of contents"
133 Longer documents usually include a table of contents,
134 which you can add by placing the
136 macro at the end of your document.
139 .SS "Document control registers"
141 The following table lists the document control
143 For the sake of consistency,
144 set registers related to margins at the beginning of your document,
157 Reg. Definition Effective Default
159 PO Page offset (left margin) next page 1i
160 LL Line length next paragraph 6i
161 LT Header/footer length next paragraph 6i
162 HM Top (header) margin next page 1i
163 FM Bottom (footer) margin next page 1i
175 Reg. Definition Effective Default
179 T} next paragraph 10p
181 Line spacing (leading)
182 T} next paragraph 12p
185 for section headings of
186 increasing importance
199 .B Paragraph settings
204 Reg. Definition Effective Default
210 Space between paragraphs
211 T} next paragraph 0.3v
213 Quoted paragraph indent
216 Number of initial lines
220 Number of initial lines
221 to be kept with heading
234 Reg. Definition Effective Default
236 FL Footnote length next footnote \[rs]n[LL]*5/6
237 FI Footnote indent next footnote 2n
238 FF Footnote format next footnote 0
239 FPS Point size next footnote \[rs]n[PS]-2
240 FVS Vert. spacing next footnote \[rs]n[FPS]+2
241 FPD Para. spacing next footnote \[rs]n[PD]/2
253 Reg. Definition Effective Default
255 MINGW Minimum width between columns next page 2n
262 .SS "Cover page macros"
264 Use the following macros to create a cover page for your document
269 Specifies the report format for your document.
270 The report format creates a separate cover page.
275 prints a subset of the
276 cover page on page\~1 of your document.
279 If you use the optional
283 prints a title page but
284 does not repeat any of the title page information
285 (title, author, abstract, etc.\&)
286 on page\~1 of the document.
290 (P-one) Prints the header on page\~1.
291 The default is to suppress the header.
295 (optional) Print the current date,
296 or the arguments to the macro if any,
297 on the title page (if specified)
299 This is the default for
304 (optional) Print the current date,
305 or the arguments to the macro if any,
306 on the title page (if specified)
307 but not in the footers.
308 This is the default for
313 Specifies the document title.
315 collects text following the
317 macro into the title, until reaching the author name or abstract.
321 Specifies the author's name.
322 You can specify multiple authors by using an
324 macro for each author.
328 Specifies the author's institution.
329 You can specify multiple institutions.
334 The default is to print the word
336 centered and in italics, above the text of the abstract.
339 suppresses this heading.
350 macro to create indented paragraphs,
353 macro to create paragraphs with no initial indent.
358 macro indents all text at both left and right margins.
359 The effect is identical to the HTML
362 The next paragraph or heading
363 returns margins to normal.
368 macro produces an exdented paragraph.
369 The first line of the paragraph begins at
371 and subsequent lines are indented
376 For each of the above paragraph types,
377 and also for any list entry introduced by the
381 the document control register
385 number of lines which must be printed,
386 after the start of the paragraph,
387 and before any page break occurs.
388 If there is insufficient space remaining on the current page
389 to accommodate this number of lines,
390 then a page break is forced
392 the first line of the paragraph is printed.
396 when a section heading
400 preceeds any of these paragraph types,
403 document control register specifies the
405 number of lines of the paragraph
406 which must be kept on the same page as the heading.
407 If insufficient space remains on the current page
408 to accommodate the heading and this number of lines of paragraph text,
409 then a page break is forced
411 the heading is printed.
416 Use headings to create a hierarchical structure
421 macros print headings in
423 using the same font family and point size as the body text.
424 For output devices which support scalable fonts,
425 this behaviour may be modified,
426 by defining the document control registers,
432 The following heading macros are available:
439 is either a numeric argument to indicate the
440 level of the heading, or
443 to set the section number explicitly.
444 If you specify heading levels out of sequence,
450 prints a warning on standard error.
455 register is set to a value
456 greater than the level of the heading,
457 then the point size of the heading will be increased by
459 units over the text size specified by the
462 for each level by which the heading level is less than
489 .RI \*(lq 1.\ Top\ Level\ Heading \*(rq
490 to be printed in 13pt
493 .RI \*(lq 1.1.\ Second\ Level\ Heading \*(rq
497 .RI \*(lq 1.1.1.\ Third\ Level\ Heading \*(rq,
498 and all more deeply nested heading levels,
499 will remain in the 10pt
501 text which is specified by the
506 Note that the value stored in
513 scaling factor should be employed,
514 when assigning a value specified in points.
517 The style used to represent the section number,
518 within a numbered heading,
522 this may be set to either the
533 is initialised by defining the alias
537 \&.als SN-STYLE SN-DOT
541 it may be changed to the
545 by defining the alternative alias
549 \&.als SN-STYLE SN-NO-DOT
553 Any such change becomes effective with the first use of
556 the new alias is defined.
561 the assigned heading number is available in the strings
563 (as it appears in the default formatting style for numbered headings,
564 with a terminating period following the number),
567 (with this terminating period omitted).
574 the user may redefine it as an alias for
577 by including the initialisation:
588 the change becomes effective with the next use of
591 the new alias is defined.
595 Unnumbered subheading.
596 The use of the optional
598 argument is a GNU extension,
599 which adjusts the point size of the unnumbered subheading
600 to match that of a numbered heading,
603 with the same value of
606 given the same settings for
611 as used in the preceeding
621 An Unnumbered Subheading
627 .RI \*(lq "An Unnumbered Subheading" \*(rq
637 macros provide a variety of methods to highlight
641 .B ".B [\fItxt\fP [\fIpost\fP [\fIpre\fP]]]"
642 Sets its first argument in
644 If you specify a second argument,
646 prints it in the previous font after
647 the bold text, with no intervening space
648 (this allows you to set punctuation after
649 the highlighted text without highlighting
651 Similarly, it prints the third argument (if any)
667 If you give this macro no arguments,
669 prints all text following in bold until
670 the next highlighting, paragraph, or heading macro.
673 .B ".R [\fItxt\fP [\fIpost\fP [\fIpre\fP]]]"
674 Sets its first argument in
675 roman (or regular) type.
676 It operates similarly to the
681 .B ".I [\fItxt\fP [\fIpost\fP [\fIpre\fP]]]"
682 Sets its first argument in
684 It operates similarly to the
689 .B ".CW [\fItxt\fP [\fIpost\fP [\fIpre\fP]]]"
690 Sets its first argument in a constant width face.
691 It operates similarly to the
696 .B ".BI [\fItxt\fP [\fIpost\fP [\fIpre\fP]]]"
697 Sets its first argument in bold italic type.
698 It operates similarly to the
704 Prints its argument and draws a box around it.
705 If you want to box a string that contains spaces,
706 use a digit-width space (\[rs]0).
709 .BI ".UL [" txt " [" post ]]
710 Prints its first argument with an underline.
711 If you specify a second argument,
713 prints it in the previous font after
714 the underlined text, with no intervening space.
718 Prints all text following in larger type
719 (2\~points larger than the current point size) until
720 the next font size, highlighting, paragraph, or heading macro.
721 You can specify this macro multiple times
722 to enlarge the point size as needed.
726 Prints all text following in
728 (2\~points smaller than the current point size) until
729 the next type size, highlighting, paragraph, or heading macro.
730 You can specify this macro multiple times
731 to reduce the point size as needed.
735 Prints all text following in
736 the normal point size
737 (that is, the value of the
742 .BI \[rs]*{ text \[rs]*}
750 You may need to indent sections of text.
751 A typical use for indents is to create nested lists and sublists.
758 macros to start and end a section of indented text, respectively.
761 register controls the amount of indent.
764 You can nest indented sections as deeply as needed by
765 using multiple, nested pairs of
775 macro handles duties for all lists.
776 Its syntax is as follows:
779 .BI ".IP [" marker " [" width ]]
784 is usually a bullet character
787 a number (or auto-incrementing number register) for numbered lists,
788 or a word or phrase for indented (glossary-style) lists.
793 specifies the indent for the body of each list item.
794 Once specified, the indent remains the same for all
795 list items in the document until specified again.
805 request to set tab stops as needed.
808 macro to reset tabs to the default (every 5n).
811 macro to create a different set of default tab stops.
814 .SS "Displays and keeps"
816 Use displays to show text-based examples or figures
817 (such as code listings).
818 Displays turn off filling, so lines of code can be
819 displayed as-is without inserting
821 requests in between each line.
824 on a single page, or allowed to break across pages.
825 The following table shows the display types available.
833 Display macro Type of display
836 \&.DS L \&.LD Left-justified.
837 \&.DS I [\fIindent\fP] \&.ID T{
838 Indented (default indent in the \fBDI\fP register).
841 Block-centered (left-justified, longest line centered).
843 \&.DS C \&.CD Centered.
844 \&.DS R \&.RD Right-justified.
853 macro to end any display type.
858 were formerly provided as aliases for
862 respectively, but they have been removed, and should no longer be used.
863 X11 documents which actually use
867 always load a specific macro file from the X11 distribution (macros.t)
868 which provides proper definitions for the two macros.
872 text together on a page,
874 a paragraph that refers to a table (or list, or other item)
875 immediately following, use the
882 macro begins a block of text to be kept on a single page,
885 macro ends the block.
895 If the keep cannot fit on the current page,
897 holds the contents of the keep and allows text following
898 the keep (in the source file) to fill in the remainder of
900 When the page breaks,
901 whether by an explicit
903 request or by reaching the end of the page,
905 prints the floating keep at the top of the new page.
906 This is useful for printing large graphics or tables
907 that do not need to appear exactly where specified.
914 can be used to enclose a text within a box;
919 Text in the box is automatically placed in a diversion
923 .SS "Tables, figures, equations, and references"
927 macros support the standard
935 Mark text meant for preprocessors by enclosing it
936 in pairs of tags as follows:
939 .BR ".TS [H]" " and " .TE
940 Denotes a table, to be processed by the
947 to create a running header with the information
952 prints the header at the beginning of the table;
953 if the table runs onto another page,
955 prints the header on the next page as well.
959 Denotes a graphic, to be processed by the
964 file by hand, using the
967 manual available on the Web as a reference,
968 or by using a graphics program such as
972 .BR ".EQ [\fI\,align\/\fP]" " and " .EN
973 Denotes an equation, to be processed by the
983 to center (the default), left-justify, or indent
988 Denotes a reference, to be processed by the
992 .IR @g@refer (@MAN1EXT@)
993 manual page provides a comprehensive reference
994 to the preprocessor and the format of the
995 bibliographic database.
1002 macros provide a flexible footnote system.
1003 You can specify a numbered footnote by using the
1005 escape, followed by the text of the footnote
1013 You can specify symbolic footnotes
1014 by placing the mark character (such as
1016 for the dagger character) in the body text,
1017 followed by the text of the footnote
1027 prints footnote numbers by changing the value of the
1029 register as follows:
1035 Prints the footnote number as a superscript; indents the footnote (default).
1039 Prints the number followed by a period (like\~1.\&)
1040 and indents the footnote.
1044 Like\~1, without an indent.
1048 Like\~1, but prints the footnote number as a hanging paragraph.
1052 You can use footnotes safely within keeps and displays,
1053 but avoid using numbered footnotes within floating keeps.
1054 You can set a second
1058 and its corresponding
1066 and the occurrences of
1068 are in the same order as the corresponding occurrences of
1072 .SS "Headers and footers"
1074 There are three ways to define headers and footers:
1082 to set the left, center, and right headers; use
1087 to set the left, center, and right footers.
1088 This works best for documents that do not distinguish
1089 between odd and even pages.
1096 macros to define headers for the odd and even pages; and
1100 macros to define footers for the odd and even pages.
1101 This is more flexible than defining the individual strings.
1102 The syntax for these macros is as follows:
1106 .B ".OH '\fIleft\fP'\fIcenter\fP'\fIright\fP'"
1110 You can replace the quote (') marks with any character not
1111 appearing in the header or footer text.
1114 You can also redefine the
1118 macros to change the behavior of
1119 the header and footer, respectively.
1120 The header process also calls the (undefined)
1124 you can define this macro if you need additional processing
1125 after printing the header
1126 (for example, to draw a line below the header).
1131 You control margins using a set of number registers.
1132 The following table lists the register names and defaults:
1139 Reg. Definition Effective Default
1141 PO Page offset (left margin) next page 1i
1142 LL Line length next paragraph 6i
1143 LT Header/footer length next paragraph 6i
1144 HM Top (header) margin next page 1i
1145 FM Bottom (footer) margin next page 1i
1152 Note that there is no right margin setting.
1153 The combination of page offset and line length
1154 provide the information necessary to
1155 derive the right margin.
1158 .SS "Multiple columns"
1162 macros can set text in as many columns as will reasonably
1164 The following macros are available.
1165 All of them force a page break if a multi-column mode is already set.
1166 However, if the current mode is single-column, starting a multi-column
1180 .BI ".MC [" width " [" gutter ]]
1182 If you specify no arguments, it is equivalent to the
1187 is the width of each column and
1189 is the space between columns.
1192 number register is the default gutter width.
1195 .SS "Creating a table of contents"
1197 Wrap text that you want to appear in the
1198 table of contents in
1205 macro to print the table of contents at the end of the document,
1206 resetting the page number to\~\c
1211 You can manually create a table of contents
1212 by specifying a page number as the first argument to
1214 Add subsequent entries using the
1226 A Brief History of the Universe
1228 Details of Galactic Formation
1237 macro to print a manually-generated table of contents
1238 without resetting the page number.
1241 If you give the argument
1248 suppresses printing the title
1254 .SS "Fractional point sizes"
1258 macros only support integer values for the document's font size and
1260 To overcome this restriction, values larger than or equal to 1000 are taken
1261 as fractional values, multiplied by 1000.
1262 For example, `.nr\~PS\~10250' sets the font size to 10.25 points.
1265 The following four registers accept fractional point sizes:
1273 Due to backwards compatibility, the value of
1275 must be smaller than 40000 (this is 40.0 points).
1279 .SH "DIFFERENCES FROM troff ms"
1283 macros are a complete re-implementation,
1284 using no original AT&T code.
1285 Since they take advantage of the extended features in
1287 they cannot be used with AT&T
1289 Other differences include:
1294 differ from the internals of Unix
1296 Documents that depend upon implementation details of Unix
1298 may not format properly with
1302 The error-handling policy of
1304 is to detect and report errors,
1305 rather than silently to ignore them.
1308 Some Bell Labs localisms are not implemented by default.
1309 However, if you call the otherwise undocumented
1311 section-header macro, you will enable implementations of three other
1312 archaic Bell Labs macros:
1317 These are not enabled by default because (a)\~they were not documented,
1324 macros both collide with different macros in the Berkeley version of
1328 These emulations are sufficient to give back the 1976 Kernighan\~& Cherry
1330 .I "Typsetting Mathematics \(en User's Guide"
1331 its section headings, and restore some text that had gone missing as
1332 arguments of undefined macros.
1333 No warranty express or implied is given as to how well the typographic
1334 details these produce match the original Bell Labs macros.
1337 Berkeley localisms, in particular the
1342 are not implemented.
1346 does not work in compatibility mode (e.g., with the
1351 There is no support for typewriter-like devices.
1355 does not provide cut marks.
1358 Multiple line spacing is not supported
1359 (use a larger vertical spacing instead).
1364 documentation says that the
1368 number registers can be used to control the column width and
1369 gutter width, respectively.
1370 These number registers are not used in
1374 Macros that cause a reset
1375 (paragraphs, headings, etc.\&)
1376 may change the indent.
1377 Macros that change the indent do not increment or decrement
1378 the indent, but rather set it absolutely.
1379 This can cause problems for documents that define
1380 additional macros of their own.
1381 The solution is to use not the
1383 request but instead the
1395 but is not used by the Unix
1398 Documents that need to determine whether
1399 they are being formatted with Unix
1403 should use this number register.
1408 use the default page offset (which also specifies the left margin),
1411 number register must stay undefined until the first
1416 should not be used early in the document, unless it is changed also:
1417 Remember that accessing an undefined register automatically defines it.
1424 You can redefine the following strings to adapt the
1426 macros to languages other than English:
1431 String Default Value
1433 REFERENCES References
1435 TOC Table of Contents
1454 string produces an em dash \[em] like this.
1461 to get a left and right typographer's quote,
1464 (and plain quotes in
1473 string sets the default font family.
1474 If this string is undefined at initialization,
1478 The point size, vertical spacing, and inter-paragraph spacing for footnotes
1479 are controlled by the number registers
1484 at initialization these are set to
1490 If any of these registers are defined before initialization,
1491 the initialization macro does not change them.
1494 The hyphenation flags (as set by the
1496 request) are set from the
1502 Improved accent marks
1503 (as originally defined in Berkeley's
1506 are available by specifying the
1508 macro at the beginning of your document.
1509 You can place an accent over most characters
1510 by specifying the string defining the accent
1511 directly after the character.
1514 produces an n with a tilde over it.
1518 .SH "NAMING CONVENTIONS"
1522 The following conventions are used for names of macros, strings and
1524 External names available to documents that use the
1526 macros contain only uppercase letters and digits.
1529 Internally the macros are divided into modules;
1530 naming conventions are as follows:
1533 Names used only within one module are of the form
1534 .IB \%module * name\fR.
1537 Names used outside the module in which they are defined are of the form
1538 .IB \%module @ name\fR.
1541 Names associated with a particular environment are of the form
1542 .IB \%environment : name\fR;
1543 these are used only within the
1549 does not have a module prefix.
1552 Constructed names used to implement arrays are of the form
1553 .IB \%array ! index\fR.
1556 Thus the groff ms macros reserve the following names:
1559 Names containing the characters
1566 Names containing only uppercase letters and digits.
1572 .B @MACRODIR@/ms.tmac
1576 .B @MACRODIR@/s.tmac
1582 .BR groff (@MAN1EXT@),
1583 .BR @g@troff (@MAN1EXT@),
1584 .BR @g@tbl (@MAN1EXT@),
1585 .BR @g@pic (@MAN1EXT@),
1586 .BR @g@eqn (@MAN1EXT@),
1587 .BR @g@refer (@MAN1EXT@),
1588 .I Groff: The GNU Implementation of troff
1589 by Trent Fisher and Werner Lemberg.
1595 Original manual page by James Clark
1597 rewritten by Larry Kollar
1598 (\fIlkollar@despammed.com\fR).
1602 .\" Local Variables: