3 Copyright (C) 1989-1995, 2001, 2002, 2003 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@"
26 groff_ms \- groff ms macros
47 This manual page describes the GNU version of the
55 macros are mostly compatible with the
56 documented behavior of the 4.3
61 .I Differences from troff ms
65 macros are suitable for reports, letters, books, and
66 technical documentation.
71 macro package expects files to have
72 a certain amount of structure.
73 The simplest documents can begin with a paragraph macro
74 and consist of text separated by paragraph macros
76 Longer documents have a structure as follows:
81 (report) macro at the beginning of the document,
83 prints the cover page information on its own page;
84 otherwise it prints the information on the
85 first page with your document text immediately following.
86 Other document formats found in AT&T
89 or Berkeley, and are not supported in
92 .B "Format and layout"
93 By setting number registers,
94 you can change your document's type (font and size),
95 margins, spacing, headers and footers, and footnotes.
97 .I "Document control registers"
98 below for more details.
101 A cover page consists of a title,
102 and optionally the author's name and institution,
103 an abstract, and the date.
105 .I "Cover page macros"
106 below for more details.
109 Following the cover page is your document.
110 It consists of paragraphs, headings, and lists.
112 .B "Table of contents"
113 Longer documents usually include a table of contents,
114 which you can add by placing the
116 macro at the end of your document.
118 .SS "Document control registers"
119 The following table lists the document control
121 For the sake of consistency,
122 set registers related to margins at the beginning of your document,
132 cb s cb s s cb s cb s
133 afCW s l s s l s l s.
134 Reg. Definition Effective Default
137 Page offset (left margin)
151 Bottom (footer) margin
161 cb s cb s s cb s cb s
162 afCW s l s s l s l s.
163 Reg. Definition Effective Default
169 Line spacing (leading)
176 .B Paragraph settings
181 Reg. Definition Effective Default
187 Space between paragraphs
190 Quoted paragraph indent
202 Reg. Definition Effective Default
204 FL Footnote length next footnote \[rs]n[LL]*5/6
205 FI Footnote indent next footnote 2n
206 FF Footnote format next footnote 0
207 FPS Point size next footnote \[rs]n[PS]-2
208 FVS Vert. spacing next footnote \[rs]n[FPS]+2
209 FPD Para. spacing next footnote \[rs]n[PD]/2
218 cb s cb s s cb s cb s
219 afCW s l s s l s l s.
220 Reg. Definition Effective Default
223 Minimum width between columns
230 .SS "Cover page macros"
231 Use the following macros to create a cover page for your document
235 Specifies the report format for your document.
236 The report format creates a separate cover page.
241 prints a subset of the
242 cover page on page\~1 of your document.
244 If you use the optional
248 prints a title page but
249 does not repeat any of the title page information
250 (title, author, abstract, etc.\&)
251 on page\~1 of the document.
254 (P-one) Prints the header on page\~1.
255 The default is to suppress the header.
258 (optional) Print the current date,
259 or the arguments to the macro if any,
260 on the title page (if specified)
262 This is the default for
266 (optional) Print the current date,
267 or the arguments to the macro if any,
268 on the title page (if specified)
269 but not in the footers.
270 This is the default for
274 Specifies the document title.
276 collects text following the
278 macro into the title, until reaching the author name or abstract.
281 Specifies the author's name.
282 You can specify multiple authors by using an
284 macro for each author.
287 Specifies the author's institution.
288 You can specify multiple institutions.
292 The default is to print the word
294 centered and in italics, above the text of the abstract.
297 suppresses this heading.
305 macro to create indented paragraphs,
308 macro to create paragraphs with no initial indent.
312 macro indents all text at both left and right margins.
313 The effect is identical to the HTML
316 The next paragraph or heading
317 returns margins to normal.
321 macro produces an exdented paragraph.
322 The first line of the paragraph begins at
324 and subsequent lines are indented
328 Use headings to create a hierarchical structure
332 macros print headings in
334 using the same font family and point size as the body text.
336 The following heading macros are available:
342 is either a numeric argument to indicate the
343 level of the heading, or
346 to set the section number explicitly.
347 If you specify heading levels out of sequence,
353 prints a warning on standard error.
356 Unnumbered subheading.
361 macros provide a variety of methods to highlight
364 .BI "\&.B [" txt " [" post " [" pre ]]]
365 Sets its first argument in
367 If you specify a second argument,
369 prints it in the previous font after
370 the bold text, with no intervening space
371 (this allows you to set punctuation after
372 the highlighted text without highlighting
374 Similarly, it prints the third argument (if any)
387 If you give this macro no arguments,
389 prints all text following in bold until
390 the next highlighting, paragraph, or heading macro.
392 .BI "\&.R [" txt " [" post " [" pre ]]]
393 Sets its first argument in
394 roman (or regular) type.
395 It operates similarly to the
399 .BI "\&.I [" txt " [" post " [" pre ]]]
400 Sets its first argument in
402 It operates similarly to the
406 .BI "\&.CW [" txt " [" post " [" pre ]]]
407 Sets its first argument in a constant width face.
408 It operates similarly to the
412 .BI "\&.BI [" txt " [" post " [" pre ]]]
413 Sets its first argument in bold italic type.
414 It operates similarly to the
419 Prints its argument and draws a box around it.
420 If you want to box a string that contains spaces,
421 use a digit-width space (\[rs]0).
423 .BI "\&.UL [" txt " [" post ]]
424 Prints its first argument with an underline.
425 If you specify a second argument,
427 prints it in the previous font after
428 the underlined text, with no intervening space.
431 Prints all text following in larger type
432 (2\~points larger than the current point size) until
433 the next font size, highlighting, paragraph, or heading macro.
434 You can specify this macro multiple times
435 to enlarge the point size as needed.
438 Prints all text following in
440 (2\~points smaller than the current point size) until
441 the next type size, highlighting, paragraph, or heading macro.
442 You can specify this macro multiple times
443 to reduce the point size as needed.
446 Prints all text following in
447 the normal point size
448 (that is, the value of the
452 .BI \[rs]*{ text \[rs]*}
458 You may need to indent sections of text.
459 A typical use for indents is to create nested lists and sublists.
465 macros to start and end a section of indented text, respectively.
468 register controls the amount of indent.
470 You can nest indented sections as deeply as needed by
471 using multiple, nested pairs of
479 macro handles duties for all lists.
480 Its syntax is as follows:
482 .BI ".IP [" marker " [" width ]]
486 is usually a bullet character
489 a number (or auto-incrementing number register) for numbered lists,
490 or a word or phrase for indented (glossary-style) lists.
494 specifies the indent for the body of each list item.
495 Once specified, the indent remains the same for all
496 list items in the document until specified again.
503 request to set tab stops as needed.
506 macro to reset tabs to the default (every 5n).
509 macro to create a different set of default tab stops.
511 .SS "Displays and keeps"
512 Use displays to show text-based examples or figures
513 (such as code listings).
514 Displays turn off filling, so lines of code can be
515 displayed as-is without inserting
517 requests in between each line.
520 on a single page, or allowed to break across pages.
521 The following table shows the display types available.
529 Display macro Type of display
532 \&.DS L \&.LD Left-justified.
533 \&.DS I [\fIindent\fP] \&.ID T{
534 Indented (default indent in the \fBDI\fP register).
537 Block-centered (left-justified, longest line centered).
539 \&.DS C \&.CD Centered.
540 \&.DS R \&.RD Right-justified.
548 macro to end any display type.
561 text together on a page,
563 a paragraph that refers to a table (or list, or other item)
564 immediately following, use the
571 macro begins a block of text to be kept on a single page,
574 macro ends the block.
583 If the keep cannot fit on the current page,
585 holds the contents of the keep and allows text following
586 the keep (in the source file) to fill in the remainder of
588 When the page breaks,
589 whether by an explicit
591 request or by reaching the end of the page,
593 prints the floating keep at the top of the new page.
594 This is useful for printing large graphics or tables
595 that do not need to appear exactly where specified.
597 .SS "Tables, figures, equations, and references"
600 macros support the standard
608 Mark text meant for preprocessors by enclosing it
609 in pairs of tags as follows:
611 .BR "\&.TS [H]" " and " \&.TE
612 Denotes a table, to be processed by the
619 to create a running header with the information
624 prints the header at the beginning of the table;
625 if the table runs onto another page,
627 prints the header on the next page as well.
629 .BR \&.PS " and " \&.PE
630 Denotes a graphic, to be processed by the
635 file by hand, using the
638 manual available on the Web as a reference,
639 or by using a graphics program such as
642 .BR "\&.EQ [\fI\,align\/\fP]" " and " \&.EN
643 Denotes an equation, to be processed by the
653 to center (the default), left-justify, or indent
656 .BR \&.[ " and " \&.]
657 Denotes a reference, to be processed by the
661 .IR @g@refer (@MAN1EXT@)
662 manual page provides a comprehensive reference
663 to the preprocessor and the format of the
664 bibliographic database.
669 macros provide a flexible footnote system.
670 You can specify a numbered footnote by using the
672 escape, followed by the text of the footnote
679 You can specify symbolic footnotes
680 by placing the mark character (such as
682 for the dagger character) in the body text,
683 followed by the text of the footnote
692 prints footnote numbers by changing the value of the
699 Prints the footnote number as a superscript; indents the footnote (default).
702 Prints the number followed by a period (like\~1.\&)
703 and indents the footnote.
706 Like\~1, without an indent.
709 Like\~1, but prints the footnote number as a hanging paragraph.
712 You can use footnotes safely within keeps and displays,
713 but avoid using numbered footnotes within floating keeps.
718 and its corresponding
726 and the occurrences of
728 are in the same order as the corresponding occurrences of
731 .SS "Headers and footers"
732 There are two ways to define headers and footers:
739 to set the left, center, and right headers; use
744 to set the left, center, and right footers.
745 This works best for documents that do not distinguish
746 between odd and even pages.
752 macros to define headers for the odd and even pages; and
756 macros to define footers for the odd and even pages.
757 This is more flexible than defining the individual strings.
758 The syntax for these macros is as follows:
761 .BI "\&.OH '" left ' center ' right '
764 You can replace the quote (') marks with any character not
765 appearing in the header or footer text.
768 You control margins using a set of number registers.
769 The following table lists the register names and defaults:
774 cb s cb s s cb s cb s
775 afCW s l s s l s l s.
776 Reg. Definition Effective Default
779 Page offset (left margin)
791 Bottom (footer) margin
798 Note that there is no right margin setting.
799 The combination of page offset and line length
800 provide the information necessary to
801 derive the right margin.
803 .SS "Multiple columns"
806 macros can set text in as many columns as will reasonably
808 The following macros are available.
809 All of them force a page break if a multi-column mode is already set.
810 However, if the current mode is single-column, starting a multi-column
821 .BI "\&.MC [" width " [" gutter ]]
823 If you specify no arguments, it is equivalent to the
828 is the width of each column and
830 is the space between columns.
833 number register is the default gutter width.
835 .SS "Creating a table of contents"
836 Wrap text that you want to appear in the
844 macro to print the table of contents at the end of the document,
845 resetting the page number to\~\c
849 You can manually create a table of contents
850 by specifying a page number as the first argument to
852 Add subsequent entries using the
863 A Brief History of the Universe
865 Details of Galactic Formation
873 macro to print a manually-generated table of contents
874 without resetting the page number.
876 If you give the argument
883 suppresses printing the title
888 .SH "DIFFERENCES FROM troff ms"
891 macros are a complete re-implementation,
892 using no original AT&T code.
893 Since they take advantage of the extended features in
895 they cannot be used with AT&T
897 Other differences include:
901 differ from the internals of Unix
903 Documents that depend upon implementation details of Unix
905 may not format properly with
908 The error-handling policy of
910 is to detect and report errors,
911 rather than silently to ignore them.
913 Bell Labs localisms are not implemented.
915 Berkeley localisms, in particular the
923 does not work in compatibility mode (e.g.\& with the
927 There is no support for typewriter-like devices.
930 does not provide cut marks.
932 Multiple line spacing is not supported
933 (use a larger vertical spacing instead).
937 documentation says that the
941 number registers can be used to control the column width and
942 gutter width respectively.
943 These number registers are not used in groff ms.
945 Macros that cause a reset
946 (paragraphs, headings, etc.)
947 may change the indent.
948 Macros that change the indent do not increment or decrement
949 the indent, but rather set it absolutely.
950 This can cause problems for documents that define
951 additional macros of their own.
952 The solution is to use not the
954 request but instead the
965 but is not used by the Unix
968 Documents that need to determine whether
969 they are being formatted with Unix
973 should use this number register.
977 You can redefine the following strings to adapt the
979 macros to languages other than English:
986 REFERENCES References
988 TOC Table of Contents
1006 string produces an em dash \[em] like this.
1011 string sets the default font family.
1012 If this string is undefined at initialization,
1015 The point size, vertical spacing, and inter-paragraph spacing for footnotes
1016 are controlled by the number registers
1021 at initialization these are set to
1027 If any of these registers are defined before initialization,
1028 the initialization macro does not change them.
1030 The hyphenation flags (as set by the
1032 request) are set from the
1037 Improved accent marks
1038 (as originally defined in Berkeley's
1041 are available by specifying the
1043 macro at the beginning of your document.
1044 You can place an accent over most characters
1045 by specifying the string defining the accent
1046 directly after the character.
1049 produces an n with a tilde over it.
1051 .SH "NAMING CONVENTIONS"
1053 The following conventions are used for names of macros, strings and
1055 External names available to documents that use the
1057 macros contain only uppercase letters and digits.
1059 Internally the macros are divided into modules;
1060 naming conventions are as follows:
1062 Names used only within one module are of the form
1063 .IB \%module * name\fR.
1065 Names used outside the module in which they are defined are of the form
1066 .IB \%module @ name\fR.
1068 Names associated with a particular environment are of the form
1069 .IB \%environment : name;
1070 these are used only within the
1075 does not have a module prefix.
1077 Constructed names used to implement arrays are of the form
1078 .IB \%array ! index\fR.
1080 Thus the groff ms macros reserve the following names:
1082 Names containing the characters
1088 Names containing only uppercase letters and digits.
1090 .B @MACRODIR@/ms.tmac
1094 .B @MACRODIR@/s.tmac
1096 .BR groff (@MAN1EXT@),
1097 .BR @g@troff (@MAN1EXT@),
1098 .BR @g@tbl (@MAN1EXT@),
1099 .BR @g@pic (@MAN1EXT@),
1100 .BR @g@eqn (@MAN1EXT@),
1101 .BR @g@refer (@MAN1EXT@),
1102 .I Groff: The GNU Implementation of troff
1103 by Trent Fisher and Werner Lemberg.
1105 Original manual page by James Clark
1107 rewritten by Larry Kollar
1108 (\fIlkollar@despammed.com\fR).
1112 .\" Local Variables:
nant's projects / dragonfly.git / blob