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]*}
453 macro handles duties for all lists.
454 Its syntax is as follows:
456 .BI ".IP [" marker " [" width ]]
460 is usually a bullet character
463 a number (or auto-incrementing number register) for numbered lists,
464 or a word or phrase for indented (glossary-style) lists.
468 specifies the indent for the body of each list item.
469 Once specified, the indent remains the same for all
470 list items in the document until specified again.
472 .SS "Displays and keeps"
473 Use displays to show text-based examples or figures
474 (such as code listings).
475 Displays turn off filling, so lines of code can be
476 displayed as-is without inserting
478 requests in between each line.
481 on a single page, or allowed to break across pages.
482 The following table shows the display types available.
490 Display macro Type of display
493 \&.DS L \&.LD Left-justified.
494 \&.DS I [\fIindent\fP] \&.ID T{
495 Indented (default indent in the \fBDI\fP register).
498 Block-centered (left-justified, longest line centered).
500 \&.DS C \&.CD Centered.
501 \&.DS R \&.RD Right-justified.
509 macro to end any display type.
513 text together on a page,
515 a paragraph that refers to a table (or list, or other item)
516 immediately following, use the
523 macro begins a block of text to be kept on a single page,
526 macro ends the block.
535 If the keep cannot fit on the current page,
537 holds the contents of the keep and allows text following
538 the keep (in the source file) to fill in the remainder of
540 When the page breaks,
541 whether by an explicit
543 request or by reaching the end of the page,
545 prints the floating keep at the top of the new page.
546 This is useful for printing large graphics or tables
547 that do not need to appear exactly where specified.
549 .SS "Tables, figures, equations, and references"
552 macros support the standard
560 Mark text meant for preprocessors by enclosing it
561 in pairs of tags as follows:
563 .BR "\&.TS [H]" " and " \&.TE
564 Denotes a table, to be processed by the
571 to create a running header with the information
576 prints the header at the beginning of the table;
577 if the table runs onto another page,
579 prints the header on the next page as well.
581 .BR \&.PS " and " \&.PE
582 Denotes a graphic, to be processed by the
587 file by hand, using the
590 manual available on the Web as a reference,
591 or by using a graphics program such as
594 .BR "\&.EQ [\fI\,align\/\fP]" " and " \&.EN
595 Denotes an equation, to be processed by the
605 to center (the default), left-justify, or indent
608 .BR \&.[ " and " \&.]
609 Denotes a reference, to be processed by the
613 .IR @g@refer (@MAN1EXT@)
614 manual page provides a comprehensive reference
615 to the preprocessor and the format of the
616 bibliographic database.
621 macros provide a flexible footnote system.
622 You can specify a numbered footnote by using the
624 escape, followed by the text of the footnote
631 You can specify symbolic footnotes
632 by placing the mark character (such as
634 for the dagger character) in the body text,
635 followed by the text of the footnote
644 prints footnote numbers by changing the value of the
651 Prints the footnote number as a superscript; indents the footnote (default).
654 Prints the number followed by a period (like\~1.\&)
655 and indents the footnote.
658 Like\~1, without an indent.
661 Like\~1, but prints the footnote number as a hanging paragraph.
664 You can use footnotes safely within keeps and displays,
665 but avoid using numbered footnotes within floating keeps.
670 and its corresponding
678 and the occurrences of
680 are in the same order as the corresponding occurrences of
683 .SS "Headers and footers"
684 There are two ways to define headers and footers:
691 to set the left, center, and right headers; use
696 to set the left, center, and right footers.
697 This works best for documents that do not distinguish
698 between odd and even pages.
704 macros to define headers for the odd and even pages; and
708 macros to define footers for the odd and even pages.
709 This is more flexible than defining the individual strings.
710 The syntax for these macros is as follows:
713 .BI "\&.OH '" left ' center ' right '
716 You can replace the quote (') marks with any character not
717 appearing in the header or footer text.
720 You control margins using a set of number registers.
721 The following table lists the register names and defaults:
726 cb s cb s s cb s cb s
727 afCW s l s s l s l s.
728 Reg. Definition Effective Default
731 Page offset (left margin)
743 Bottom (footer) margin
750 Note that there is no right margin setting.
751 The combination of page offset and line length
752 provide the information necessary to
753 derive the right margin.
755 .SS "Multiple columns"
758 macros can set text in as many columns as will reasonably
760 The following macros are available.
761 All of them force a page break if a multi-column mode is already set.
762 However, if the current mode is single-column, starting a multi-column
773 .BI "\&.MC [" width " [" gutter ]]
775 If you specify no arguments, it is equivalent to the
780 is the width of each column and
782 is the space between columns.
785 number register is the default gutter width.
787 .SS "Creating a table of contents"
788 Wrap text that you want to appear in the
796 macro to print the table of contents at the end of the document,
797 resetting the page number to\~\c
801 You can manually create a table of contents
802 by specifying a page number as the first argument to
804 Add subsequent entries using the
815 A Brief History of the Universe
817 Details of Galactic Formation
825 macro to print a manually-generated table of contents
826 without resetting the page number.
828 If you give the argument
835 suppresses printing the title
840 .SH "DIFFERENCES FROM troff ms"
843 macros are a complete re-implementation,
844 using no original AT&T code.
845 Since they take advantage of the extended features in
847 they cannot be used with AT&T
849 Other differences include:
853 differ from the internals of Unix
855 Documents that depend upon implementation details of Unix
857 may not format properly with
860 The error-handling policy of
862 is to detect and report errors,
863 rather than silently to ignore them.
865 Bell Labs localisms are not implemented.
867 Berkeley localisms, in particular the
875 does not work in compatibility mode (e.g.\& with the
879 There is no support for typewriter-like devices.
882 does not provide cut marks.
884 Multiple line spacing is not supported
885 (use a larger vertical spacing instead).
889 documentation says that the
893 number registers can be used to control the column width and
894 gutter width respectively.
895 These number registers are not used in groff ms.
897 Macros that cause a reset
898 (paragraphs, headings, etc.)
899 may change the indent.
900 Macros that change the indent do not increment or decrement
901 the indent, but rather set it absolutely.
902 This can cause problems for documents that define
903 additional macros of their own.
904 The solution is to use not the
906 request but instead the
917 but is not used by the Unix
920 Documents that need to determine whether
921 they are being formatted with Unix
925 should use this number register.
929 You can redefine the following strings to adapt the
931 macros to languages other than English:
938 REFERENCES References
940 TOC Table of Contents
958 string produces an em dash \[em] like this.
963 string sets the default font family.
964 If this string is undefined at initialization,
967 The point size, vertical spacing, and inter-paragraph spacing for footnotes
968 are controlled by the number registers
973 at initialization these are set to
979 If any of these registers are defined before initialization,
980 the initialization macro does not change them.
982 The hyphenation flags (as set by the
984 request) are set from the
989 Improved accent marks
990 (as originally defined in Berkeley's
993 are available by specifying the
995 macro at the beginning of your document.
996 You can place an accent over most characters
997 by specifying the string defining the accent
998 directly after the character.
1001 produces an n with a tilde over it.
1003 .SH "NAMING CONVENTIONS"
1005 The following conventions are used for names of macros, strings and
1007 External names available to documents that use the
1009 macros contain only uppercase letters and digits.
1011 Internally the macros are divided into modules;
1012 naming conventions are as follows:
1014 Names used only within one module are of the form
1015 .IB \%module * name\fR.
1017 Names used outside the module in which they are defined are of the form
1018 .IB \%module @ name\fR.
1020 Names associated with a particular environment are of the form
1021 .IB \%environment : name;
1022 these are used only within the
1027 does not have a module prefix.
1029 Constructed names used to implement arrays are of the form
1030 .IB \%array ! index\fR.
1032 Thus the groff ms macros reserve the following names:
1034 Names containing the characters
1040 Names containing only uppercase letters and digits.
1042 .B @MACRODIR@/ms.tmac
1046 .B @MACRODIR@/s.tmac
1048 .BR groff (@MAN1EXT@),
1049 .BR @g@troff (@MAN1EXT@),
1050 .BR @g@tbl (@MAN1EXT@),
1051 .BR @g@pic (@MAN1EXT@),
1052 .BR @g@eqn (@MAN1EXT@),
1053 .BR @g@refer (@MAN1EXT@),
1054 .I Groff: The GNU Implementation of troff
1055 by Trent Fisher and Werner Lemberg.
1057 Original manual page by James Clark
1059 rewritten by Larry Kollar
1060 (\fIlkollar@despammed.com\fR).
1061 .\" Local Variables: