3 Copyright (C) 1989-1995, 2001, 2002, 2003, 2004 Free Software Foundation, Inc.
5 Permission is granted to make and distribute verbatim copies of
6 this manual provided the copyright notice and this permission notice
7 are preserved on all copies.
9 Permission is granted to copy and distribute modified versions of this
10 manual under the conditions for verbatim copying, provided that the
11 entire resulting derived work is distributed under the terms of a
12 permission notice identical to this one.
14 Permission is granted to copy and distribute translations of this
15 manual into another language, under the above conditions for modified
16 versions, except that this permission notice may be included in
17 translations approved by the Free Software Foundation instead of in
21 .do nr groff_ms_C \n[.C]
24 .TH GROFF_MS @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
30 groff_ms \- groff ms macros
58 This manual page describes the GNU version of the
66 macros are mostly compatible with the
67 documented behavior of the 4.3
72 .I Differences from troff ms
76 macros are suitable for reports, letters, books, and
77 technical documentation.
85 macro package expects files to have
86 a certain amount of structure.
87 The simplest documents can begin with a paragraph macro
88 and consist of text separated by paragraph macros
90 Longer documents have a structure as follows:
96 (report) macro at the beginning of the document,
98 prints the cover page information on its own page;
99 otherwise it prints the information on the
100 first page with your document text immediately following.
101 Other document formats found in AT&T
104 or Berkeley, and are not supported in
108 .B "Format and layout"
109 By setting number registers,
110 you can change your document's type (font and size),
111 margins, spacing, headers and footers, and footnotes.
113 .I "Document control registers"
114 below for more details.
118 A cover page consists of a title,
119 and optionally the author's name and institution,
120 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 .SS "Document control registers"
140 The following table lists the document control
142 For the sake of consistency,
143 set registers related to margins at the beginning of your document,
154 cb s cb s s cb s cb s
155 afCW s l s s l s l s.
156 Reg. Definition Effective Default
159 Page offset (left margin)
173 Bottom (footer) margin
184 cb s cb s s cb s cb s
185 afCW s l s s l s l s.
186 Reg. Definition Effective Default
192 Line spacing (leading)
196 for section headings of
197 increasing importance
210 .B Paragraph settings
215 Reg. Definition Effective Default
221 Space between paragraphs
224 Quoted paragraph indent
227 Number of initial lines
231 Number of initial lines
232 to be kept with heading
245 Reg. Definition Effective Default
247 FL Footnote length next footnote \[rs]n[LL]*5/6
248 FI Footnote indent next footnote 2n
249 FF Footnote format next footnote 0
250 FPS Point size next footnote \[rs]n[PS]-2
251 FVS Vert. spacing next footnote \[rs]n[FPS]+2
252 FPD Para. spacing next footnote \[rs]n[PD]/2
262 cb s cb s s cb s cb s
263 afCW s l s s l s l s.
264 Reg. Definition Effective Default
267 Minimum width between columns
275 .SS "Cover page macros"
277 Use the following macros to create a cover page for your document
282 Specifies the report format for your document.
283 The report format creates a separate cover page.
288 prints a subset of the
289 cover page on page\~1 of your document.
292 If you use the optional
296 prints a title page but
297 does not repeat any of the title page information
298 (title, author, abstract, etc.\&)
299 on page\~1 of the document.
303 (P-one) Prints the header on page\~1.
304 The default is to suppress the header.
308 (optional) Print the current date,
309 or the arguments to the macro if any,
310 on the title page (if specified)
312 This is the default for
317 (optional) Print the current date,
318 or the arguments to the macro if any,
319 on the title page (if specified)
320 but not in the footers.
321 This is the default for
326 Specifies the document title.
328 collects text following the
330 macro into the title, until reaching the author name or abstract.
334 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.
342 You can specify multiple institutions.
347 The default is to print the word
349 centered and in italics, above the text of the abstract.
352 suppresses this heading.
363 macro to create indented paragraphs,
366 macro to create paragraphs with no initial indent.
371 macro indents all text at both left and right margins.
372 The effect is identical to the HTML
375 The next paragraph or heading
376 returns margins to normal.
381 macro produces an exdented paragraph.
382 The first line of the paragraph begins at
384 and subsequent lines are indented
389 For each of the above paragraph types,
390 and also for any list entry introduced by the
394 the document control register
398 number of lines which must be printed,
399 after the start of the paragraph,
400 and before any page break occurs.
401 If there is insufficient space remaining on the current page
402 to accommodate this number of lines,
403 then a page break is forced
405 the first line of the paragraph is printed.
409 when a section heading
413 preceeds any of these paragraph types,
416 document control register specifies the
418 number of lines of the paragraph
419 which must be kept on the same page as the heading.
420 If insufficient space remains on the current page
421 to accommodate the heading and this number of lines of paragraph text,
422 then a page break is forced
424 the heading is printed.
429 Use headings to create a hierarchical structure
434 macros print headings in
436 using the same font family and point size as the body text.
437 For output devices which support scalable fonts,
438 this behaviour may be modified,
439 by defining the document control registers,
445 The following heading macros are available:
452 is either a numeric argument to indicate the
453 level of the heading, or
456 to set the section number explicitly.
457 If you specify heading levels out of sequence,
463 prints a warning on standard error.
468 register is set to a value
469 greater than the level of the heading,
470 then the point size of the heading will be increased by
472 units over the text size specified by the
475 for each level by which the heading level is less than
502 .RI \*(lq 1.\ Top\ Level\ Heading \*(rq
503 to be printed in 13pt
506 .RI \*(lq 1.1.\ Second\ Level\ Heading \*(rq
510 .RI \*(lq 1.1.1.\ Third\ Level\ Heading \*(rq,
511 and all more deeply nested heading levels,
512 will remain in the 10pt
514 text which is specified by the
519 Note that the value stored in
526 scaling factor should be employed,
527 when assigning a value specified in points.
532 the assigned heading number is available in the strings
534 (exactly as it appears in the formatted heading),
537 (with its final period omitted).
544 the user may redefine it as an alias for
547 by including the initialisation:
577 Unnumbered subheading.
578 The use of the optional
580 argument is a GNU extension,
581 which adjusts the point size of the unnumbered subheading
582 to match that of a numbered heading,
585 with the same value of
588 given the same settings for
593 as used in the preceeding
603 An Unnumbered Subheading
609 .RI \*(lq "An Unnumbered Subheading" \*(rq
619 macros provide a variety of methods to highlight
623 .B ".B [\fItxt\fP [\fIpost\fP [\fIpre\fP]]]"
624 Sets its first argument in
626 If you specify a second argument,
628 prints it in the previous font after
629 the bold text, with no intervening space
630 (this allows you to set punctuation after
631 the highlighted text without highlighting
633 Similarly, it prints the third argument (if any)
649 If you give this macro no arguments,
651 prints all text following in bold until
652 the next highlighting, paragraph, or heading macro.
655 .B ".R [\fItxt\fP [\fIpost\fP [\fIpre\fP]]]"
656 Sets its first argument in
657 roman (or regular) type.
658 It operates similarly to the
663 .B ".I [\fItxt\fP [\fIpost\fP [\fIpre\fP]]]"
664 Sets its first argument in
666 It operates similarly to the
671 .B ".CW [\fItxt\fP [\fIpost\fP [\fIpre\fP]]]"
672 Sets its first argument in a constant width face.
673 It operates similarly to the
678 .B ".BI [\fItxt\fP [\fIpost\fP [\fIpre\fP]]]"
679 Sets its first argument in bold italic type.
680 It operates similarly to the
686 Prints its argument and draws a box around it.
687 If you want to box a string that contains spaces,
688 use a digit-width space (\[rs]0).
691 .BI ".UL [" txt " [" post ]]
692 Prints its first argument with an underline.
693 If you specify a second argument,
695 prints it in the previous font after
696 the underlined text, with no intervening space.
700 Prints all text following in larger type
701 (2\~points larger than the current point size) until
702 the next font size, highlighting, paragraph, or heading macro.
703 You can specify this macro multiple times
704 to enlarge the point size as needed.
708 Prints all text following in
710 (2\~points smaller than the current point size) until
711 the next type size, highlighting, paragraph, or heading macro.
712 You can specify this macro multiple times
713 to reduce the point size as needed.
717 Prints all text following in
718 the normal point size
719 (that is, the value of the
724 .BI \[rs]*{ text \[rs]*}
732 You may need to indent sections of text.
733 A typical use for indents is to create nested lists and sublists.
740 macros to start and end a section of indented text, respectively.
743 register controls the amount of indent.
746 You can nest indented sections as deeply as needed by
747 using multiple, nested pairs of
757 macro handles duties for all lists.
758 Its syntax is as follows:
761 .BI ".IP [" marker " [" width ]]
766 is usually a bullet character
769 a number (or auto-incrementing number register) for numbered lists,
770 or a word or phrase for indented (glossary-style) lists.
775 specifies the indent for the body of each list item.
776 Once specified, the indent remains the same for all
777 list items in the document until specified again.
787 request to set tab stops as needed.
790 macro to reset tabs to the default (every 5n).
793 macro to create a different set of default tab stops.
796 .SS "Displays and keeps"
798 Use displays to show text-based examples or figures
799 (such as code listings).
800 Displays turn off filling, so lines of code can be
801 displayed as-is without inserting
803 requests in between each line.
806 on a single page, or allowed to break across pages.
807 The following table shows the display types available.
815 Display macro Type of display
818 \&.DS L \&.LD Left-justified.
819 \&.DS I [\fIindent\fP] \&.ID T{
820 Indented (default indent in the \fBDI\fP register).
823 Block-centered (left-justified, longest line centered).
825 \&.DS C \&.CD Centered.
826 \&.DS R \&.RD Right-justified.
835 macro to end any display type.
840 were formerly provided as aliases for
844 respectively, but they have been removed, and should no longer be used.
845 X11 documents which actually use
849 always load a specific macro file from the X11 distribution (macros.t)
850 which provides proper definitions for the two macros.
854 text together on a page,
856 a paragraph that refers to a table (or list, or other item)
857 immediately following, use the
864 macro begins a block of text to be kept on a single page,
867 macro ends the block.
877 If the keep cannot fit on the current page,
879 holds the contents of the keep and allows text following
880 the keep (in the source file) to fill in the remainder of
882 When the page breaks,
883 whether by an explicit
885 request or by reaching the end of the page,
887 prints the floating keep at the top of the new page.
888 This is useful for printing large graphics or tables
889 that do not need to appear exactly where specified.
892 .SS "Tables, figures, equations, and references"
896 macros support the standard
904 Mark text meant for preprocessors by enclosing it
905 in pairs of tags as follows:
908 .BR ".TS [H]" " and " .TE
909 Denotes a table, to be processed by the
916 to create a running header with the information
921 prints the header at the beginning of the table;
922 if the table runs onto another page,
924 prints the header on the next page as well.
928 Denotes a graphic, to be processed by the
933 file by hand, using the
936 manual available on the Web as a reference,
937 or by using a graphics program such as
941 .BR ".EQ [\fI\,align\/\fP]" " and " .EN
942 Denotes an equation, to be processed by the
952 to center (the default), left-justify, or indent
957 Denotes a reference, to be processed by the
961 .IR @g@refer (@MAN1EXT@)
962 manual page provides a comprehensive reference
963 to the preprocessor and the format of the
964 bibliographic database.
971 macros provide a flexible footnote system.
972 You can specify a numbered footnote by using the
974 escape, followed by the text of the footnote
982 You can specify symbolic footnotes
983 by placing the mark character (such as
985 for the dagger character) in the body text,
986 followed by the text of the footnote
996 prints footnote numbers by changing the value of the
1004 Prints the footnote number as a superscript; indents the footnote (default).
1008 Prints the number followed by a period (like\~1.\&)
1009 and indents the footnote.
1013 Like\~1, without an indent.
1017 Like\~1, but prints the footnote number as a hanging paragraph.
1021 You can use footnotes safely within keeps and displays,
1022 but avoid using numbered footnotes within floating keeps.
1023 You can set a second
1027 and its corresponding
1035 and the occurrences of
1037 are in the same order as the corresponding occurrences of
1041 .SS "Headers and footers"
1043 There are two ways to define headers and footers:
1051 to set the left, center, and right headers; use
1056 to set the left, center, and right footers.
1057 This works best for documents that do not distinguish
1058 between odd and even pages.
1065 macros to define headers for the odd and even pages; and
1069 macros to define footers for the odd and even pages.
1070 This is more flexible than defining the individual strings.
1071 The syntax for these macros is as follows:
1075 .B ".OH '\fIleft\fP'\fIcenter\fP'\fIright\fP'"
1079 You can replace the quote (') marks with any character not
1080 appearing in the header or footer text.
1085 You control margins using a set of number registers.
1086 The following table lists the register names and defaults:
1091 cb s cb s s cb s cb s
1092 afCW s l s s l s l s.
1093 Reg. Definition Effective Default
1096 Page offset (left margin)
1102 Header/footer length
1108 Bottom (footer) margin
1116 Note that there is no right margin setting.
1117 The combination of page offset and line length
1118 provide the information necessary to
1119 derive the right margin.
1122 .SS "Multiple columns"
1126 macros can set text in as many columns as will reasonably
1128 The following macros are available.
1129 All of them force a page break if a multi-column mode is already set.
1130 However, if the current mode is single-column, starting a multi-column
1144 .BI ".MC [" width " [" gutter ]]
1146 If you specify no arguments, it is equivalent to the
1151 is the width of each column and
1153 is the space between columns.
1156 number register is the default gutter width.
1159 .SS "Creating a table of contents"
1161 Wrap text that you want to appear in the
1162 table of contents in
1169 macro to print the table of contents at the end of the document,
1170 resetting the page number to\~\c
1175 You can manually create a table of contents
1176 by specifying a page number as the first argument to
1178 Add subsequent entries using the
1190 A Brief History of the Universe
1192 Details of Galactic Formation
1201 macro to print a manually-generated table of contents
1202 without resetting the page number.
1205 If you give the argument
1212 suppresses printing the title
1218 .SS "Fractional point sizes"
1222 macros only support integer values for the document's font size and
1224 To overcome this restriction, values larger than or equal to 1000 are taken
1225 as fractional values, multiplied by 1000.
1226 For example, `.nr\~PS\~10250' sets the font size to 10.25 points.
1229 The following four registers accept fractional point sizes:
1237 Due to backwards compatibility, the value of
1239 must be smaller than 40000 (this is 40.0 points).
1243 .SH "DIFFERENCES FROM troff ms"
1247 macros are a complete re-implementation,
1248 using no original AT&T code.
1249 Since they take advantage of the extended features in
1251 they cannot be used with AT&T
1253 Other differences include:
1258 differ from the internals of Unix
1260 Documents that depend upon implementation details of Unix
1262 may not format properly with
1266 The error-handling policy of
1268 is to detect and report errors,
1269 rather than silently to ignore them.
1272 Bell Labs localisms are not implemented.
1275 Berkeley localisms, in particular the
1280 are not implemented.
1284 does not work in compatibility mode (e.g.\& with the
1289 There is no support for typewriter-like devices.
1293 does not provide cut marks.
1296 Multiple line spacing is not supported
1297 (use a larger vertical spacing instead).
1302 documentation says that the
1306 number registers can be used to control the column width and
1307 gutter width respectively.
1308 These number registers are not used in groff ms.
1311 Macros that cause a reset
1312 (paragraphs, headings, etc.)
1313 may change the indent.
1314 Macros that change the indent do not increment or decrement
1315 the indent, but rather set it absolutely.
1316 This can cause problems for documents that define
1317 additional macros of their own.
1318 The solution is to use not the
1320 request but instead the
1332 but is not used by the Unix
1335 Documents that need to determine whether
1336 they are being formatted with Unix
1340 should use this number register.
1347 You can redefine the following strings to adapt the
1349 macros to languages other than English:
1354 String Default Value
1356 REFERENCES References
1358 TOC Table of Contents
1377 string produces an em dash \[em] like this.
1384 string sets the default font family.
1385 If this string is undefined at initialization,
1389 The point size, vertical spacing, and inter-paragraph spacing for footnotes
1390 are controlled by the number registers
1395 at initialization these are set to
1401 If any of these registers are defined before initialization,
1402 the initialization macro does not change them.
1405 The hyphenation flags (as set by the
1407 request) are set from the
1413 Improved accent marks
1414 (as originally defined in Berkeley's
1417 are available by specifying the
1419 macro at the beginning of your document.
1420 You can place an accent over most characters
1421 by specifying the string defining the accent
1422 directly after the character.
1425 produces an n with a tilde over it.
1429 .SH "NAMING CONVENTIONS"
1433 The following conventions are used for names of macros, strings and
1435 External names available to documents that use the
1437 macros contain only uppercase letters and digits.
1440 Internally the macros are divided into modules;
1441 naming conventions are as follows:
1444 Names used only within one module are of the form
1445 .IB \%module * name\fR.
1448 Names used outside the module in which they are defined are of the form
1449 .IB \%module @ name\fR.
1452 Names associated with a particular environment are of the form
1453 .IB \%environment : name;
1454 these are used only within the
1460 does not have a module prefix.
1463 Constructed names used to implement arrays are of the form
1464 .IB \%array ! index\fR.
1467 Thus the groff ms macros reserve the following names:
1470 Names containing the characters
1477 Names containing only uppercase letters and digits.
1483 .B @MACRODIR@/ms.tmac
1487 .B @MACRODIR@/s.tmac
1493 .BR groff (@MAN1EXT@),
1494 .BR @g@troff (@MAN1EXT@),
1495 .BR @g@tbl (@MAN1EXT@),
1496 .BR @g@pic (@MAN1EXT@),
1497 .BR @g@eqn (@MAN1EXT@),
1498 .BR @g@refer (@MAN1EXT@),
1499 .I Groff: The GNU Implementation of troff
1500 by Trent Fisher and Werner Lemberg.
1506 Original manual page by James Clark
1508 rewritten by Larry Kollar
1509 (\fIlkollar@despammed.com\fR).
1513 .\" Local Variables: