3 Copyright (C) 1989-1995, 2001, 2002 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
20 .TH GROFF_MS @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
22 groff_ms \- groff ms macros
43 This manual page describes the GNU version of the
51 macros are mostly compatible with the
52 documented behavior of the 4.3
57 .I Differences from troff ms
61 macros are suitable for reports, letters, books, and
62 technical documentation.
67 macro package expects files to have
68 a certain amount of structure.
69 The simplest documents can begin with a paragraph macro
70 and consist of text separated by paragraph macros
72 Longer documents have a structure as follows:
77 (report) macro at the beginning of the document,
79 prints the cover page information on its own page;
80 otherwise it prints the information on the
81 first page with your document text immediately following.
82 Other document formats found in AT&T
85 or Berkeley, and are not supported in
88 .B "Format and layout"
89 By setting number registers,
90 you can change your document's type (font and size),
91 margins, spacing, headers and footers, and footnotes.
93 .I "Document control registers"
94 below for more details.
97 A cover page consists of a title,
98 and optionally the author's name and institution,
99 an abstract, and the date.
101 .I "Cover page macros"
102 below for more details.
105 Following the cover page is your document.
106 It consists of paragraphs, headings, and lists.
108 .B "Table of contents"
109 Longer documents usually include a table of contents,
110 which you can add by placing the
112 macro at the end of your document.
114 .SS "Document control registers"
115 The following table lists the document control
117 For the sake of consistency,
118 set registers related to margins at the beginning of your document,
128 cb s cb s s cb s cb s
129 afCW s l s s l s l s.
130 Reg. Definition Effective Default
133 Page offset (left margin)
147 Bottom (footer) margin
157 cb s cb s s cb s cb s
158 afCW s l s s l s l s.
159 Reg. Definition Effective Default
165 Line spacing (leading)
172 .B Paragraph settings
177 Reg. Definition Effective Default
183 Space between paragraphs
186 Quoted paragraph indent
198 Reg. Definition Effective Default
200 FL Footnote length next footnote LL*5/6
201 FI Footnote indent next footnote 2n
202 FF Footnote format next footnote 0
211 cb s cb s s cb s cb s
212 afCW s l s s l s l s.
213 Reg. Definition Effective Default
216 Minimum width between columns
223 .SS "Cover page macros"
224 Use the following macros to create a cover page for your document
228 Specifies the report format for your document.
229 The report format creates a separate cover page.
234 prints a subset of the
235 cover page on page\~1 of your document.
237 If you use the optional
241 prints a title page but
242 does not repeat any of the title page information
243 (title, author, abstract, etc.\&)
244 on page\~1 of the document.
247 (P-one) Prints the header on page\~1.
248 The default is to suppress the header.
251 (optional) Print the current date,
252 or the arguments to the macro if any,
253 on the title page (if specified)
255 This is the default for
259 (optional) Print the current date,
260 or the arguments to the macro if any,
261 on the title page (if specified)
262 but not in the footers.
263 This is the default for
267 Specifies the document title.
269 collects text following the
271 macro into the title, until reaching the author name or abstract.
274 Specifies the author's name.
275 You can specify multiple authors by using an
277 macro for each author.
280 Specifies the author's institution.
281 You can specify multiple institutions.
285 The default is to print the word
287 centered and in italics, above the text of the abstract.
290 suppresses this heading.
298 macro to create indented paragraphs,
301 macro to create paragraphs with no initial indent.
305 macro indents all text at both left and right margins.
306 The effect is identical to the HTML
309 The next paragraph or heading
310 returns margins to normal.
314 macro produces an exdented paragraph.
315 The first line of the paragraph begins at
317 and subsequent lines are indented
321 Use headings to create a hierarchical structure
325 macros print headings in
327 using the same font family and point size as the body text.
329 The following heading macros are available:
335 is either a numeric argument to indicate the
336 level of the heading, or
339 to set the section number explicitly.
340 If you specify heading levels out of sequence,
346 prints a warning on standard error.
349 Unnumbered subheading.
354 macros provide a variety of methods to highlight
357 .BI "\&.B [" txt " [" post " [" pre ]]]
358 Sets its first argument in
360 If you specify a second argument,
362 prints it in the previous font after
363 the bold text, with no intervening space
364 (this allows you to set punctuation after
365 the highlighted text without highlighting
367 Similarly, it prints the third argument (if any)
380 If you give this macro no arguments,
382 prints all text following in bold until
383 the next highlighting, paragraph, or heading macro.
385 .BI "\&.R [" txt " [" post " [" pre ]]]
386 Sets its first argument in
387 roman (or regular) type.
388 It operates similarly to the
392 .BI "\&.I [" txt " [" post " [" pre ]]]
393 Sets its first argument in
395 It operates similarly to the
399 .BI "\&.CW [" txt " [" post " [" pre ]]]
400 Sets its first argument in a constant width face.
401 It operates similarly to the
405 .BI "\&.BI [" txt " [" post " [" pre ]]]
406 Sets its first argument in bold italic type.
407 It operates similarly to the
412 Prints its argument and draws a box around it.
413 If you want to box a string that contains spaces,
414 use a digit-width space (\[rs]0).
416 .BI "\&.UL [" txt " [" post ]]
417 Prints its first argument with an underline.
418 If you specify a second argument,
420 prints it in the previous font after
421 the underlined text, with no intervening space.
424 Prints all text following in larger type
425 (2\~points larger than the current point size) until
426 the next font size, highlighting, paragraph, or heading macro.
427 You can specify this macro multiple times
428 to enlarge the point size as needed.
431 Prints all text following in
433 (2\~points smaller than the current point size) until
434 the next type size, highlighting, paragraph, or heading macro.
435 You can specify this macro multiple times
436 to reduce the point size as needed.
439 Prints all text following in
440 the normal point size
441 (that is, the value of the
445 .BI \[rs]*{ text \[rs]*}
451 You may need to indent sections of text.
452 A typical use for indents is to create nested lists and sublists.
458 macros to start and end a section of indented text, respectively.
461 register controls the amount of indent.
463 You can nest indented sections as deeply as needed by
464 using multiple, nested pairs of
472 macro handles duties for all lists.
473 Its syntax is as follows:
475 .BI ".IP [" marker " [" width ]]
479 is usually a bullet character
482 a number (or auto-incrementing number register) for numbered lists,
483 or a word or phrase for indented (glossary-style) lists.
487 specifies the indent for the body of each list item.
488 Once specified, the indent remains the same for all
489 list items in the document until specified again.
496 request to set tab stops as needed.
499 macro to reset tabs to the default (every 5n).
502 macro to create a different set of default tab stops.
504 .SS "Displays and keeps"
505 Use displays to show text-based examples or figures
506 (such as code listings).
507 Displays turn off filling, so lines of code can be
508 displayed as-is without inserting
510 requests in between each line.
513 on a single page, or allowed to break across pages.
514 The following table shows the display types available.
522 Display macro Type of display
525 \&.DS L \&.LD Left-justified.
526 \&.DS I [\fIindent\fP] \&.ID T{
527 Indented (default indent in the \fBDI\fP register).
530 Block-centered (left-justified, longest line centered).
532 \&.DS C \&.CD Centered.
533 \&.DS R \&.RD Right-justified.
541 macro to end any display type.
545 text together on a page,
547 a paragraph that refers to a table (or list, or other item)
548 immediately following, use the
555 macro begins a block of text to be kept on a single page,
558 macro ends the block.
567 If the keep cannot fit on the current page,
569 holds the contents of the keep and allows text following
570 the keep (in the source file) to fill in the remainder of
572 When the page breaks,
573 whether by an explicit
575 request or by reaching the end of the page,
577 prints the floating keep at the top of the new page.
578 This is useful for printing large graphics or tables
579 that do not need to appear exactly where specified.
581 .SS "Tables, figures, equations, and references"
584 macros support the standard
592 Mark text meant for preprocessors by enclosing it
593 in pairs of tags as follows:
595 .BR "\&.TS [H]" " and " \&.TE
596 Denotes a table, to be processed by the
603 to create a running header with the information
608 prints the header at the beginning of the table;
609 if the table runs onto another page,
611 prints the header on the next page as well.
613 .BR \&.PS " and " \&.PE
614 Denotes a graphic, to be processed by the
619 file by hand, using the
622 manual available on the Web as a reference,
623 or by using a graphics program such as
626 .BR "\&.EQ [\fI\,align\/\fP]" " and " \&.EN
627 Denotes an equation, to be processed by the
637 to center (the default), left-justify, or indent
640 .BR \&.[ " and " \&.]
641 Denotes a reference, to be processed by the
645 .IR @g@refer (@MAN1EXT@)
646 manual page provides a comprehensive reference
647 to the preprocessor and the format of the
648 bibliographic database.
653 macros provide a flexible footnote system.
654 You can specify a numbered footnote by using the
656 escape, followed by the text of the footnote
663 You can specify symbolic footnotes
664 by placing the mark character (such as
666 for the dagger character) in the body text,
667 followed by the text of the footnote
676 prints footnote numbers by changing the value of the
683 Prints the footnote number as a superscript; indents the footnote (default).
686 Prints the number followed by a period (like\~1.\&)
687 and indents the footnote.
690 Like\~1, without an indent.
693 Like\~1, but prints the footnote number as a hanging paragraph.
696 You can use footnotes safely within keeps and displays,
697 but avoid using numbered footnotes within floating keeps.
702 and its corresponding
710 and the occurrences of
712 are in the same order as the corresponding occurrences of
715 .SS "Headers and footers"
716 There are two ways to define headers and footers:
723 to set the left, center, and right headers; use
728 to set the left, center, and right footers.
729 This works best for documents that do not distinguish
730 between odd and even pages.
736 macros to define headers for the odd and even pages; and
740 macros to define footers for the odd and even pages.
741 This is more flexible than defining the individual strings.
742 The syntax for these macros is as follows:
745 .BI "\&.OH '" left ' center ' right '
748 You can replace the quote (') marks with any character not
749 appearing in the header or footer text.
752 You control margins using a set of number registers.
753 The following table lists the register names and defaults:
758 cb s cb s s cb s cb s
759 afCW s l s s l s l s.
760 Reg. Definition Effective Default
763 Page offset (left margin)
775 Bottom (footer) margin
782 Note that there is no right margin setting.
783 The combination of page offset and line length
784 provide the information necessary to
785 derive the right margin.
787 .SS "Multiple columns"
790 macros can set text in as many columns as will reasonably
792 The following macros are available.
793 All of them force a page break if a multi-column mode is already set.
794 However, if the current mode is single-column, starting a multi-column
805 .BI "\&.MC [" width " [" gutter ]]
807 If you specify no arguments, it is equivalent to the
812 is the width of each column and
814 is the space between columns.
817 number register is the default gutter width.
819 .SS "Creating a table of contents"
820 Wrap text that you want to appear in the
828 macro to print the table of contents at the end of the document,
829 resetting the page number to\~\c
833 You can manually create a table of contents
834 by specifying a page number as the first argument to
836 Add subsequent entries using the
847 A Brief History of the Universe
849 Details of Galactic Formation
857 macro to print a manually-generated table of contents
858 without resetting the page number.
860 If you give the argument
867 suppresses printing the title
872 .SH "DIFFERENCES FROM troff ms"
875 macros are a complete re-implementation,
876 using no original AT&T code.
877 Since they take advantage of the extended features in
879 they cannot be used with AT&T
881 Other differences include:
885 differ from the internals of Unix
887 Documents that depend upon implementation details of Unix
889 may not format properly with
892 The error-handling policy of
894 is to detect and report errors,
895 rather than silently to ignore them.
897 Bell Labs localisms are not implemented.
899 Berkeley localisms, in particular the
907 does not work in compatibility mode (e.g.\& with the
911 There is no support for typewriter-like devices.
914 does not provide cut marks.
916 Multiple line spacing is not supported
917 (use a larger vertical spacing instead).
921 documentation says that the
925 number registers can be used to control the column width and
926 gutter width respectively.
927 These number registers are not used in groff ms.
929 Macros that cause a reset
930 (paragraphs, headings, etc.)
931 may change the indent.
932 Macros that change the indent do not increment or decrement
933 the indent, but rather set it absolutely.
934 This can cause problems for documents that define
935 additional macros of their own.
936 The solution is to use not the
938 request but instead the
949 but is not used by the Unix
952 Documents that need to determine whether
953 they are being formatted with Unix
957 should use this number register.
961 You can redefine the following strings to adapt the
963 macros to languages other than English:
970 REFERENCES References
972 TOC Table of Contents
990 string produces an em dash \[em] like this.
995 string sets the default font family.
996 If this string is undefined at initialization,
999 The point size, vertical spacing, and inter-paragraph spacing for footnotes
1000 are controlled by the number registers
1005 at initialization these are set to
1011 If any of these registers are defined before initialization,
1012 the initialization macro does not change them.
1014 The hyphenation flags (as set by the
1016 request) are set from the
1021 Improved accent marks
1022 (as originally defined in Berkeley's
1025 are available by specifying the
1027 macro at the beginning of your document.
1028 You can place an accent over most characters
1029 by specifying the string defining the accent
1030 directly after the character.
1033 produces an n with a tilde over it.
1035 .SH "NAMING CONVENTIONS"
1037 The following conventions are used for names of macros, strings and
1039 External names available to documents that use the
1041 macros contain only uppercase letters and digits.
1043 Internally the macros are divided into modules;
1044 naming conventions are as follows:
1046 Names used only within one module are of the form
1047 .IB \%module * name\fR.
1049 Names used outside the module in which they are defined are of the form
1050 .IB \%module @ name\fR.
1052 Names associated with a particular environment are of the form
1053 .IB \%environment : name;
1054 these are used only within the
1059 does not have a module prefix.
1061 Constructed names used to implement arrays are of the form
1062 .IB \%array ! index\fR.
1064 Thus the groff ms macros reserve the following names:
1066 Names containing the characters
1072 Names containing only uppercase letters and digits.
1074 .B @MACRODIR@/ms.tmac
1078 .B @MACRODIR@/s.tmac
1080 .BR groff (@MAN1EXT@),
1081 .BR @g@troff (@MAN1EXT@),
1082 .BR @g@tbl (@MAN1EXT@),
1083 .BR @g@pic (@MAN1EXT@),
1084 .BR @g@eqn (@MAN1EXT@),
1085 .BR @g@refer (@MAN1EXT@),
1086 .I Groff: The GNU Implementation of troff
1087 by Trent Fisher and Werner Lemberg.
1089 Original manual page by James Clark
1091 rewritten by Larry Kollar
1092 (\fIlkollar@despammed.com\fR).
1093 .\" Local Variables:
projects / dragonfly.git / blob