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
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 \[rs]n[LL]*5/6
201 FI Footnote indent next footnote 2n
202 FF Footnote format next footnote 0
203 FPS Point size next footnote \[rs]n[PS]-2
204 FVS Vert. spacing next footnote \[rs]n[FPS]+2
205 FPD Para. spacing next footnote \[rs]n[PD]/2
214 cb s cb s s cb s cb s
215 afCW s l s s l s l s.
216 Reg. Definition Effective Default
219 Minimum width between columns
226 .SS "Cover page macros"
227 Use the following macros to create a cover page for your document
231 Specifies the report format for your document.
232 The report format creates a separate cover page.
237 prints a subset of the
238 cover page on page\~1 of your document.
240 If you use the optional
244 prints a title page but
245 does not repeat any of the title page information
246 (title, author, abstract, etc.\&)
247 on page\~1 of the document.
250 (P-one) Prints the header on page\~1.
251 The default is to suppress the header.
254 (optional) Print the current date,
255 or the arguments to the macro if any,
256 on the title page (if specified)
258 This is the default for
262 (optional) Print the current date,
263 or the arguments to the macro if any,
264 on the title page (if specified)
265 but not in the footers.
266 This is the default for
270 Specifies the document title.
272 collects text following the
274 macro into the title, until reaching the author name or abstract.
277 Specifies the author's name.
278 You can specify multiple authors by using an
280 macro for each author.
283 Specifies the author's institution.
284 You can specify multiple institutions.
288 The default is to print the word
290 centered and in italics, above the text of the abstract.
293 suppresses this heading.
301 macro to create indented paragraphs,
304 macro to create paragraphs with no initial indent.
308 macro indents all text at both left and right margins.
309 The effect is identical to the HTML
312 The next paragraph or heading
313 returns margins to normal.
317 macro produces an exdented paragraph.
318 The first line of the paragraph begins at
320 and subsequent lines are indented
324 Use headings to create a hierarchical structure
328 macros print headings in
330 using the same font family and point size as the body text.
332 The following heading macros are available:
338 is either a numeric argument to indicate the
339 level of the heading, or
342 to set the section number explicitly.
343 If you specify heading levels out of sequence,
349 prints a warning on standard error.
352 Unnumbered subheading.
357 macros provide a variety of methods to highlight
360 .BI "\&.B [" txt " [" post " [" pre ]]]
361 Sets its first argument in
363 If you specify a second argument,
365 prints it in the previous font after
366 the bold text, with no intervening space
367 (this allows you to set punctuation after
368 the highlighted text without highlighting
370 Similarly, it prints the third argument (if any)
383 If you give this macro no arguments,
385 prints all text following in bold until
386 the next highlighting, paragraph, or heading macro.
388 .BI "\&.R [" txt " [" post " [" pre ]]]
389 Sets its first argument in
390 roman (or regular) type.
391 It operates similarly to the
395 .BI "\&.I [" txt " [" post " [" pre ]]]
396 Sets its first argument in
398 It operates similarly to the
402 .BI "\&.CW [" txt " [" post " [" pre ]]]
403 Sets its first argument in a constant width face.
404 It operates similarly to the
408 .BI "\&.BI [" txt " [" post " [" pre ]]]
409 Sets its first argument in bold italic type.
410 It operates similarly to the
415 Prints its argument and draws a box around it.
416 If you want to box a string that contains spaces,
417 use a digit-width space (\[rs]0).
419 .BI "\&.UL [" txt " [" post ]]
420 Prints its first argument with an underline.
421 If you specify a second argument,
423 prints it in the previous font after
424 the underlined text, with no intervening space.
427 Prints all text following in larger type
428 (2\~points larger than the current point size) until
429 the next font size, highlighting, paragraph, or heading macro.
430 You can specify this macro multiple times
431 to enlarge the point size as needed.
434 Prints all text following in
436 (2\~points smaller than the current point size) until
437 the next type size, highlighting, paragraph, or heading macro.
438 You can specify this macro multiple times
439 to reduce the point size as needed.
442 Prints all text following in
443 the normal point size
444 (that is, the value of the
448 .BI \[rs]*{ text \[rs]*}
454 You may need to indent sections of text.
455 A typical use for indents is to create nested lists and sublists.
461 macros to start and end a section of indented text, respectively.
464 register controls the amount of indent.
466 You can nest indented sections as deeply as needed by
467 using multiple, nested pairs of
475 macro handles duties for all lists.
476 Its syntax is as follows:
478 .BI ".IP [" marker " [" width ]]
482 is usually a bullet character
485 a number (or auto-incrementing number register) for numbered lists,
486 or a word or phrase for indented (glossary-style) lists.
490 specifies the indent for the body of each list item.
491 Once specified, the indent remains the same for all
492 list items in the document until specified again.
499 request to set tab stops as needed.
502 macro to reset tabs to the default (every 5n).
505 macro to create a different set of default tab stops.
507 .SS "Displays and keeps"
508 Use displays to show text-based examples or figures
509 (such as code listings).
510 Displays turn off filling, so lines of code can be
511 displayed as-is without inserting
513 requests in between each line.
516 on a single page, or allowed to break across pages.
517 The following table shows the display types available.
525 Display macro Type of display
528 \&.DS L \&.LD Left-justified.
529 \&.DS I [\fIindent\fP] \&.ID T{
530 Indented (default indent in the \fBDI\fP register).
533 Block-centered (left-justified, longest line centered).
535 \&.DS C \&.CD Centered.
536 \&.DS R \&.RD Right-justified.
544 macro to end any display type.
557 text together on a page,
559 a paragraph that refers to a table (or list, or other item)
560 immediately following, use the
567 macro begins a block of text to be kept on a single page,
570 macro ends the block.
579 If the keep cannot fit on the current page,
581 holds the contents of the keep and allows text following
582 the keep (in the source file) to fill in the remainder of
584 When the page breaks,
585 whether by an explicit
587 request or by reaching the end of the page,
589 prints the floating keep at the top of the new page.
590 This is useful for printing large graphics or tables
591 that do not need to appear exactly where specified.
593 .SS "Tables, figures, equations, and references"
596 macros support the standard
604 Mark text meant for preprocessors by enclosing it
605 in pairs of tags as follows:
607 .BR "\&.TS [H]" " and " \&.TE
608 Denotes a table, to be processed by the
615 to create a running header with the information
620 prints the header at the beginning of the table;
621 if the table runs onto another page,
623 prints the header on the next page as well.
625 .BR \&.PS " and " \&.PE
626 Denotes a graphic, to be processed by the
631 file by hand, using the
634 manual available on the Web as a reference,
635 or by using a graphics program such as
638 .BR "\&.EQ [\fI\,align\/\fP]" " and " \&.EN
639 Denotes an equation, to be processed by the
649 to center (the default), left-justify, or indent
652 .BR \&.[ " and " \&.]
653 Denotes a reference, to be processed by the
657 .IR @g@refer (@MAN1EXT@)
658 manual page provides a comprehensive reference
659 to the preprocessor and the format of the
660 bibliographic database.
665 macros provide a flexible footnote system.
666 You can specify a numbered footnote by using the
668 escape, followed by the text of the footnote
675 You can specify symbolic footnotes
676 by placing the mark character (such as
678 for the dagger character) in the body text,
679 followed by the text of the footnote
688 prints footnote numbers by changing the value of the
695 Prints the footnote number as a superscript; indents the footnote (default).
698 Prints the number followed by a period (like\~1.\&)
699 and indents the footnote.
702 Like\~1, without an indent.
705 Like\~1, but prints the footnote number as a hanging paragraph.
708 You can use footnotes safely within keeps and displays,
709 but avoid using numbered footnotes within floating keeps.
714 and its corresponding
722 and the occurrences of
724 are in the same order as the corresponding occurrences of
727 .SS "Headers and footers"
728 There are two ways to define headers and footers:
735 to set the left, center, and right headers; use
740 to set the left, center, and right footers.
741 This works best for documents that do not distinguish
742 between odd and even pages.
748 macros to define headers for the odd and even pages; and
752 macros to define footers for the odd and even pages.
753 This is more flexible than defining the individual strings.
754 The syntax for these macros is as follows:
757 .BI "\&.OH '" left ' center ' right '
760 You can replace the quote (') marks with any character not
761 appearing in the header or footer text.
764 You control margins using a set of number registers.
765 The following table lists the register names and defaults:
770 cb s cb s s cb s cb s
771 afCW s l s s l s l s.
772 Reg. Definition Effective Default
775 Page offset (left margin)
787 Bottom (footer) margin
794 Note that there is no right margin setting.
795 The combination of page offset and line length
796 provide the information necessary to
797 derive the right margin.
799 .SS "Multiple columns"
802 macros can set text in as many columns as will reasonably
804 The following macros are available.
805 All of them force a page break if a multi-column mode is already set.
806 However, if the current mode is single-column, starting a multi-column
817 .BI "\&.MC [" width " [" gutter ]]
819 If you specify no arguments, it is equivalent to the
824 is the width of each column and
826 is the space between columns.
829 number register is the default gutter width.
831 .SS "Creating a table of contents"
832 Wrap text that you want to appear in the
840 macro to print the table of contents at the end of the document,
841 resetting the page number to\~\c
845 You can manually create a table of contents
846 by specifying a page number as the first argument to
848 Add subsequent entries using the
859 A Brief History of the Universe
861 Details of Galactic Formation
869 macro to print a manually-generated table of contents
870 without resetting the page number.
872 If you give the argument
879 suppresses printing the title
884 .SH "DIFFERENCES FROM troff ms"
887 macros are a complete re-implementation,
888 using no original AT&T code.
889 Since they take advantage of the extended features in
891 they cannot be used with AT&T
893 Other differences include:
897 differ from the internals of Unix
899 Documents that depend upon implementation details of Unix
901 may not format properly with
904 The error-handling policy of
906 is to detect and report errors,
907 rather than silently to ignore them.
909 Bell Labs localisms are not implemented.
911 Berkeley localisms, in particular the
919 does not work in compatibility mode (e.g.\& with the
923 There is no support for typewriter-like devices.
926 does not provide cut marks.
928 Multiple line spacing is not supported
929 (use a larger vertical spacing instead).
933 documentation says that the
937 number registers can be used to control the column width and
938 gutter width respectively.
939 These number registers are not used in groff ms.
941 Macros that cause a reset
942 (paragraphs, headings, etc.)
943 may change the indent.
944 Macros that change the indent do not increment or decrement
945 the indent, but rather set it absolutely.
946 This can cause problems for documents that define
947 additional macros of their own.
948 The solution is to use not the
950 request but instead the
961 but is not used by the Unix
964 Documents that need to determine whether
965 they are being formatted with Unix
969 should use this number register.
973 You can redefine the following strings to adapt the
975 macros to languages other than English:
982 REFERENCES References
984 TOC Table of Contents
1002 string produces an em dash \[em] like this.
1007 string sets the default font family.
1008 If this string is undefined at initialization,
1011 The point size, vertical spacing, and inter-paragraph spacing for footnotes
1012 are controlled by the number registers
1017 at initialization these are set to
1023 If any of these registers are defined before initialization,
1024 the initialization macro does not change them.
1026 The hyphenation flags (as set by the
1028 request) are set from the
1033 Improved accent marks
1034 (as originally defined in Berkeley's
1037 are available by specifying the
1039 macro at the beginning of your document.
1040 You can place an accent over most characters
1041 by specifying the string defining the accent
1042 directly after the character.
1045 produces an n with a tilde over it.
1047 .SH "NAMING CONVENTIONS"
1049 The following conventions are used for names of macros, strings and
1051 External names available to documents that use the
1053 macros contain only uppercase letters and digits.
1055 Internally the macros are divided into modules;
1056 naming conventions are as follows:
1058 Names used only within one module are of the form
1059 .IB \%module * name\fR.
1061 Names used outside the module in which they are defined are of the form
1062 .IB \%module @ name\fR.
1064 Names associated with a particular environment are of the form
1065 .IB \%environment : name;
1066 these are used only within the
1071 does not have a module prefix.
1073 Constructed names used to implement arrays are of the form
1074 .IB \%array ! index\fR.
1076 Thus the groff ms macros reserve the following names:
1078 Names containing the characters
1084 Names containing only uppercase letters and digits.
1086 .B @MACRODIR@/ms.tmac
1090 .B @MACRODIR@/s.tmac
1092 .BR groff (@MAN1EXT@),
1093 .BR @g@troff (@MAN1EXT@),
1094 .BR @g@tbl (@MAN1EXT@),
1095 .BR @g@pic (@MAN1EXT@),
1096 .BR @g@eqn (@MAN1EXT@),
1097 .BR @g@refer (@MAN1EXT@),
1098 .I Groff: The GNU Implementation of troff
1099 by Trent Fisher and Werner Lemberg.
1101 Original manual page by James Clark
1103 rewritten by Larry Kollar
1104 (\fIlkollar@despammed.com\fR).
1105 .\" Local Variables: