3 Copyright (C) 1989-1995, 2001, 2002, 2003, 2004, 2005
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,
155 cb s cb s s cb s cb s
156 afCW s l s s l s l s.
157 Reg. Definition Effective Default
160 Page offset (left margin)
174 Bottom (footer) margin
185 cb s cb s s cb s cb s
186 afCW s l s s l s l s.
187 Reg. Definition Effective Default
193 Line spacing (leading)
197 for section headings of
198 increasing importance
211 .B Paragraph settings
216 Reg. Definition Effective Default
222 Space between paragraphs
225 Quoted paragraph indent
228 Number of initial lines
232 Number of initial lines
233 to be kept with heading
246 Reg. Definition Effective Default
248 FL Footnote length next footnote \[rs]n[LL]*5/6
249 FI Footnote indent next footnote 2n
250 FF Footnote format next footnote 0
251 FPS Point size next footnote \[rs]n[PS]-2
252 FVS Vert. spacing next footnote \[rs]n[FPS]+2
253 FPD Para. spacing next footnote \[rs]n[PD]/2
263 cb s cb s s cb s cb s
264 afCW s l s s l s l s.
265 Reg. Definition Effective Default
268 Minimum width between columns
276 .SS "Cover page macros"
278 Use the following macros to create a cover page for your document
283 Specifies the report format for your document.
284 The report format creates a separate cover page.
289 prints a subset of the
290 cover page on page\~1 of your document.
293 If you use the optional
297 prints a title page but
298 does not repeat any of the title page information
299 (title, author, abstract, etc.\&)
300 on page\~1 of the document.
304 (P-one) Prints the header on page\~1.
305 The default is to suppress the header.
309 (optional) Print the current date,
310 or the arguments to the macro if any,
311 on the title page (if specified)
313 This is the default for
318 (optional) Print the current date,
319 or the arguments to the macro if any,
320 on the title page (if specified)
321 but not in the footers.
322 This is the default for
327 Specifies the document title.
329 collects text following the
331 macro into the title, until reaching the author name or abstract.
335 Specifies the author's name.
336 You can specify multiple authors by using an
338 macro for each author.
342 Specifies the author's institution.
343 You can specify multiple institutions.
348 The default is to print the word
350 centered and in italics, above the text of the abstract.
353 suppresses this heading.
364 macro to create indented paragraphs,
367 macro to create paragraphs with no initial indent.
372 macro indents all text at both left and right margins.
373 The effect is identical to the HTML
376 The next paragraph or heading
377 returns margins to normal.
382 macro produces an exdented paragraph.
383 The first line of the paragraph begins at
385 and subsequent lines are indented
390 For each of the above paragraph types,
391 and also for any list entry introduced by the
395 the document control register
399 number of lines which must be printed,
400 after the start of the paragraph,
401 and before any page break occurs.
402 If there is insufficient space remaining on the current page
403 to accommodate this number of lines,
404 then a page break is forced
406 the first line of the paragraph is printed.
410 when a section heading
414 preceeds any of these paragraph types,
417 document control register specifies the
419 number of lines of the paragraph
420 which must be kept on the same page as the heading.
421 If insufficient space remains on the current page
422 to accommodate the heading and this number of lines of paragraph text,
423 then a page break is forced
425 the heading is printed.
430 Use headings to create a hierarchical structure
435 macros print headings in
437 using the same font family and point size as the body text.
438 For output devices which support scalable fonts,
439 this behaviour may be modified,
440 by defining the document control registers,
446 The following heading macros are available:
453 is either a numeric argument to indicate the
454 level of the heading, or
457 to set the section number explicitly.
458 If you specify heading levels out of sequence,
464 prints a warning on standard error.
469 register is set to a value
470 greater than the level of the heading,
471 then the point size of the heading will be increased by
473 units over the text size specified by the
476 for each level by which the heading level is less than
503 .RI \*(lq 1.\ Top\ Level\ Heading \*(rq
504 to be printed in 13pt
507 .RI \*(lq 1.1.\ Second\ Level\ Heading \*(rq
511 .RI \*(lq 1.1.1.\ Third\ Level\ Heading \*(rq,
512 and all more deeply nested heading levels,
513 will remain in the 10pt
515 text which is specified by the
520 Note that the value stored in
527 scaling factor should be employed,
528 when assigning a value specified in points.
533 the assigned heading number is available in the strings
535 (exactly as it appears in the formatted heading),
538 (with its final period omitted).
545 the user may redefine it as an alias for
548 by including the initialisation:
578 Unnumbered subheading.
579 The use of the optional
581 argument is a GNU extension,
582 which adjusts the point size of the unnumbered subheading
583 to match that of a numbered heading,
586 with the same value of
589 given the same settings for
594 as used in the preceeding
604 An Unnumbered Subheading
610 .RI \*(lq "An Unnumbered Subheading" \*(rq
620 macros provide a variety of methods to highlight
624 .B ".B [\fItxt\fP [\fIpost\fP [\fIpre\fP]]]"
625 Sets its first argument in
627 If you specify a second argument,
629 prints it in the previous font after
630 the bold text, with no intervening space
631 (this allows you to set punctuation after
632 the highlighted text without highlighting
634 Similarly, it prints the third argument (if any)
650 If you give this macro no arguments,
652 prints all text following in bold until
653 the next highlighting, paragraph, or heading macro.
656 .B ".R [\fItxt\fP [\fIpost\fP [\fIpre\fP]]]"
657 Sets its first argument in
658 roman (or regular) type.
659 It operates similarly to the
664 .B ".I [\fItxt\fP [\fIpost\fP [\fIpre\fP]]]"
665 Sets its first argument in
667 It operates similarly to the
672 .B ".CW [\fItxt\fP [\fIpost\fP [\fIpre\fP]]]"
673 Sets its first argument in a constant width face.
674 It operates similarly to the
679 .B ".BI [\fItxt\fP [\fIpost\fP [\fIpre\fP]]]"
680 Sets its first argument in bold italic type.
681 It operates similarly to the
687 Prints its argument and draws a box around it.
688 If you want to box a string that contains spaces,
689 use a digit-width space (\[rs]0).
692 .BI ".UL [" txt " [" post ]]
693 Prints its first argument with an underline.
694 If you specify a second argument,
696 prints it in the previous font after
697 the underlined text, with no intervening space.
701 Prints all text following in larger type
702 (2\~points larger than the current point size) until
703 the next font size, highlighting, paragraph, or heading macro.
704 You can specify this macro multiple times
705 to enlarge the point size as needed.
709 Prints all text following in
711 (2\~points smaller than the current point size) until
712 the next type size, highlighting, paragraph, or heading macro.
713 You can specify this macro multiple times
714 to reduce the point size as needed.
718 Prints all text following in
719 the normal point size
720 (that is, the value of the
725 .BI \[rs]*{ text \[rs]*}
733 You may need to indent sections of text.
734 A typical use for indents is to create nested lists and sublists.
741 macros to start and end a section of indented text, respectively.
744 register controls the amount of indent.
747 You can nest indented sections as deeply as needed by
748 using multiple, nested pairs of
758 macro handles duties for all lists.
759 Its syntax is as follows:
762 .BI ".IP [" marker " [" width ]]
767 is usually a bullet character
770 a number (or auto-incrementing number register) for numbered lists,
771 or a word or phrase for indented (glossary-style) lists.
776 specifies the indent for the body of each list item.
777 Once specified, the indent remains the same for all
778 list items in the document until specified again.
788 request to set tab stops as needed.
791 macro to reset tabs to the default (every 5n).
794 macro to create a different set of default tab stops.
797 .SS "Displays and keeps"
799 Use displays to show text-based examples or figures
800 (such as code listings).
801 Displays turn off filling, so lines of code can be
802 displayed as-is without inserting
804 requests in between each line.
807 on a single page, or allowed to break across pages.
808 The following table shows the display types available.
816 Display macro Type of display
819 \&.DS L \&.LD Left-justified.
820 \&.DS I [\fIindent\fP] \&.ID T{
821 Indented (default indent in the \fBDI\fP register).
824 Block-centered (left-justified, longest line centered).
826 \&.DS C \&.CD Centered.
827 \&.DS R \&.RD Right-justified.
836 macro to end any display type.
841 were formerly provided as aliases for
845 respectively, but they have been removed, and should no longer be used.
846 X11 documents which actually use
850 always load a specific macro file from the X11 distribution (macros.t)
851 which provides proper definitions for the two macros.
855 text together on a page,
857 a paragraph that refers to a table (or list, or other item)
858 immediately following, use the
865 macro begins a block of text to be kept on a single page,
868 macro ends the block.
878 If the keep cannot fit on the current page,
880 holds the contents of the keep and allows text following
881 the keep (in the source file) to fill in the remainder of
883 When the page breaks,
884 whether by an explicit
886 request or by reaching the end of the page,
888 prints the floating keep at the top of the new page.
889 This is useful for printing large graphics or tables
890 that do not need to appear exactly where specified.
897 can be used to enclose a text within a box;
902 Text in the box is automatically placed in a diversion
906 .SS "Tables, figures, equations, and references"
910 macros support the standard
918 Mark text meant for preprocessors by enclosing it
919 in pairs of tags as follows:
922 .BR ".TS [H]" " and " .TE
923 Denotes a table, to be processed by the
930 to create a running header with the information
935 prints the header at the beginning of the table;
936 if the table runs onto another page,
938 prints the header on the next page as well.
942 Denotes a graphic, to be processed by the
947 file by hand, using the
950 manual available on the Web as a reference,
951 or by using a graphics program such as
955 .BR ".EQ [\fI\,align\/\fP]" " and " .EN
956 Denotes an equation, to be processed by the
966 to center (the default), left-justify, or indent
971 Denotes a reference, to be processed by the
975 .IR @g@refer (@MAN1EXT@)
976 manual page provides a comprehensive reference
977 to the preprocessor and the format of the
978 bibliographic database.
985 macros provide a flexible footnote system.
986 You can specify a numbered footnote by using the
988 escape, followed by the text of the footnote
996 You can specify symbolic footnotes
997 by placing the mark character (such as
999 for the dagger character) in the body text,
1000 followed by the text of the footnote
1010 prints footnote numbers by changing the value of the
1012 register as follows:
1018 Prints the footnote number as a superscript; indents the footnote (default).
1022 Prints the number followed by a period (like\~1.\&)
1023 and indents the footnote.
1027 Like\~1, without an indent.
1031 Like\~1, but prints the footnote number as a hanging paragraph.
1035 You can use footnotes safely within keeps and displays,
1036 but avoid using numbered footnotes within floating keeps.
1037 You can set a second
1041 and its corresponding
1049 and the occurrences of
1051 are in the same order as the corresponding occurrences of
1055 .SS "Headers and footers"
1057 There are two ways to define headers and footers:
1065 to set the left, center, and right headers; use
1070 to set the left, center, and right footers.
1071 This works best for documents that do not distinguish
1072 between odd and even pages.
1079 macros to define headers for the odd and even pages; and
1083 macros to define footers for the odd and even pages.
1084 This is more flexible than defining the individual strings.
1085 The syntax for these macros is as follows:
1089 .B ".OH '\fIleft\fP'\fIcenter\fP'\fIright\fP'"
1093 You can replace the quote (') marks with any character not
1094 appearing in the header or footer text.
1099 You control margins using a set of number registers.
1100 The following table lists the register names and defaults:
1105 cb s cb s s cb s cb s
1106 afCW s l s s l s l s.
1107 Reg. Definition Effective Default
1110 Page offset (left margin)
1116 Header/footer length
1122 Bottom (footer) margin
1130 Note that there is no right margin setting.
1131 The combination of page offset and line length
1132 provide the information necessary to
1133 derive the right margin.
1136 .SS "Multiple columns"
1140 macros can set text in as many columns as will reasonably
1142 The following macros are available.
1143 All of them force a page break if a multi-column mode is already set.
1144 However, if the current mode is single-column, starting a multi-column
1158 .BI ".MC [" width " [" gutter ]]
1160 If you specify no arguments, it is equivalent to the
1165 is the width of each column and
1167 is the space between columns.
1170 number register is the default gutter width.
1173 .SS "Creating a table of contents"
1175 Wrap text that you want to appear in the
1176 table of contents in
1183 macro to print the table of contents at the end of the document,
1184 resetting the page number to\~\c
1189 You can manually create a table of contents
1190 by specifying a page number as the first argument to
1192 Add subsequent entries using the
1204 A Brief History of the Universe
1206 Details of Galactic Formation
1215 macro to print a manually-generated table of contents
1216 without resetting the page number.
1219 If you give the argument
1226 suppresses printing the title
1232 .SS "Fractional point sizes"
1236 macros only support integer values for the document's font size and
1238 To overcome this restriction, values larger than or equal to 1000 are taken
1239 as fractional values, multiplied by 1000.
1240 For example, `.nr\~PS\~10250' sets the font size to 10.25 points.
1243 The following four registers accept fractional point sizes:
1251 Due to backwards compatibility, the value of
1253 must be smaller than 40000 (this is 40.0 points).
1257 .SH "DIFFERENCES FROM troff ms"
1261 macros are a complete re-implementation,
1262 using no original AT&T code.
1263 Since they take advantage of the extended features in
1265 they cannot be used with AT&T
1267 Other differences include:
1272 differ from the internals of Unix
1274 Documents that depend upon implementation details of Unix
1276 may not format properly with
1280 The error-handling policy of
1282 is to detect and report errors,
1283 rather than silently to ignore them.
1286 Bell Labs localisms are not implemented.
1289 Berkeley localisms, in particular the
1294 are not implemented.
1298 does not work in compatibility mode (e.g., with the
1303 There is no support for typewriter-like devices.
1307 does not provide cut marks.
1310 Multiple line spacing is not supported
1311 (use a larger vertical spacing instead).
1316 documentation says that the
1320 number registers can be used to control the column width and
1321 gutter width, respectively.
1322 These number registers are not used in
1326 Macros that cause a reset
1327 (paragraphs, headings, etc.\&)
1328 may change the indent.
1329 Macros that change the indent do not increment or decrement
1330 the indent, but rather set it absolutely.
1331 This can cause problems for documents that define
1332 additional macros of their own.
1333 The solution is to use not the
1335 request but instead the
1347 but is not used by the Unix
1350 Documents that need to determine whether
1351 they are being formatted with Unix
1355 should use this number register.
1360 use the default page offset (which also specifies the left margin),
1363 number register must stay undefined until the first
1368 should not be used early in the document, unless it is changed also:
1369 Remember that accessing an undefined register automatically defines it.
1376 You can redefine the following strings to adapt the
1378 macros to languages other than English:
1383 String Default Value
1385 REFERENCES References
1387 TOC Table of Contents
1406 string produces an em dash \[em] like this.
1413 to get a left and right typographer's quote,
1416 (and plain quotes in
1425 string sets the default font family.
1426 If this string is undefined at initialization,
1430 The point size, vertical spacing, and inter-paragraph spacing for footnotes
1431 are controlled by the number registers
1436 at initialization these are set to
1442 If any of these registers are defined before initialization,
1443 the initialization macro does not change them.
1446 The hyphenation flags (as set by the
1448 request) are set from the
1454 Improved accent marks
1455 (as originally defined in Berkeley's
1458 are available by specifying the
1460 macro at the beginning of your document.
1461 You can place an accent over most characters
1462 by specifying the string defining the accent
1463 directly after the character.
1466 produces an n with a tilde over it.
1470 .SH "NAMING CONVENTIONS"
1474 The following conventions are used for names of macros, strings and
1476 External names available to documents that use the
1478 macros contain only uppercase letters and digits.
1481 Internally the macros are divided into modules;
1482 naming conventions are as follows:
1485 Names used only within one module are of the form
1486 .IB \%module * name\fR.
1489 Names used outside the module in which they are defined are of the form
1490 .IB \%module @ name\fR.
1493 Names associated with a particular environment are of the form
1494 .IB \%environment : name\fR;
1495 these are used only within the
1501 does not have a module prefix.
1504 Constructed names used to implement arrays are of the form
1505 .IB \%array ! index\fR.
1508 Thus the groff ms macros reserve the following names:
1511 Names containing the characters
1518 Names containing only uppercase letters and digits.
1524 .B @MACRODIR@/ms.tmac
1528 .B @MACRODIR@/s.tmac
1534 .BR groff (@MAN1EXT@),
1535 .BR @g@troff (@MAN1EXT@),
1536 .BR @g@tbl (@MAN1EXT@),
1537 .BR @g@pic (@MAN1EXT@),
1538 .BR @g@eqn (@MAN1EXT@),
1539 .BR @g@refer (@MAN1EXT@),
1540 .I Groff: The GNU Implementation of troff
1541 by Trent Fisher and Werner Lemberg.
1547 Original manual page by James Clark
1549 rewritten by Larry Kollar
1550 (\fIlkollar@despammed.com\fR).
1554 .\" Local Variables:
lentferj's projects / dragonfly.git / blob