1 This is groff, produced by makeinfo version 4.2 from ./groff.texinfo.
3 This manual documents GNU `troff' version 1.18.
5 Copyright (C) 1994-2000, 2001, 2002 Free Software Foundation, Inc.
7 Permission is granted to copy, distribute and/or modify this
8 document under the terms of the GNU Free Documentation License,
9 Version 1.1 or any later version published by the Free Software
10 Foundation; with no Invariant Sections, with the Front-Cover texts
11 being `A GNU Manual," and with the Back-Cover Texts as in (a)
12 below. A copy of the license is included in the section entitled
13 `GNU Free Documentation License."
15 (a) The FSF's Back-Cover Text is: `You have freedom to copy and
16 modify this GNU Manual, like GNU software. Copies published by
17 the Free Software Foundation raise funds for GNU development."
19 INFO-DIR-SECTION Miscellaneous
21 * Groff: (groff). The GNU troff document formatting system.
25 File: groff, Node: Man usage, Next: Man font macros, Prev: Man options, Up: man
30 This section describes the available macros for manual pages. For
31 further customization, put additional macros and requests into the file
32 `man.local' which is loaded immediately after the `man' package.
34 - Macro: .TH title section [extra1 [extra2 [extra3]]]
35 Set the title of the man page to TITLE and the section to SECTION,
36 which must have a value between 1 and 8. The value of SECTION may
37 also have a string appended, e.g. `.pm', to indicate a specific
38 subsection of the man pages.
40 Both TITLE and SECTION are positioned at the left and right in the
41 header line (with SECTION in parentheses immediately appended to
42 TITLE. EXTRA1 is positioned in the middle of the footer line.
43 EXTRA2 is positioned at the left in the footer line (or at the
44 left on even pages and at the right on odd pages if double-sided
45 printing is active). EXTRA3 is centered in the header line.
47 For HTML output, headers and footers are completely suppressed.
49 Additionally, this macro starts a new page; the new line number
50 is 1 again (except if the `-rC1' option is given on the command
51 line) - this feature is intended only for formatting multiple man
52 pages; a single man page should contain exactly one `TH' macro at
53 the beginning of the file.
55 - Macro: .SH [heading]
56 Set up an unnumbered section heading sticking out to the left.
57 Prints out all the text following `SH' up to the end of the line
58 (or the text in the next line if there is no argument to `SH') in
59 bold face, one size larger than the base document size.
60 Additionally, the left margin for the following text is reset to
63 - Macro: .SS [heading]
64 Set up an unnumbered (sub)section heading. Prints out all the text
65 following `SS' up to the end of the line (or the text in the next
66 line if there is no argument to `SS') in bold face, at the same
67 size as the base document size. Additionally, the left margin for
68 the following text is reset to its default value.
71 Set up an indented paragraph with label. The indentation is set to
72 NNN if that argument is supplied (the default unit is `n' if
73 omitted), otherwise it is set to the default indentation value.
75 The first line of text following this macro is interpreted as a
76 string to be printed flush-left, as it is appropriate for a label.
77 It is not interpreted as part of a paragraph, so there is no
78 attempt to fill the first line with text from the following input
79 lines. Nevertheless, if the label is not as wide as the
80 indentation, then the paragraph starts at the same line (but
81 indented), continuing on the following lines. If the label is
82 wider than the indentation, then the descriptive part of the
83 paragraph begins on the line following the label, entirely
84 indented. Note that neither font shape nor font size of the label
85 is set to a default value; on the other hand, the rest of the text
86 has default font settings.
91 These macros are mutual aliases. Any of them causes a line break
92 at the current position, followed by a vertical space downwards by
93 the amount specified by the `PD' macro. The font size and shape
94 are reset to the default value (10pt roman if no `-rS' option is
95 given on the command line). Finally, the current left margin is
98 - Macro: .IP [designator [nnn]]
99 Set up an indented paragraph, using DESIGNATOR as a tag to mark
100 its beginning. The indentation is set to NNN if that argument is
101 supplied (default unit is `n'), otherwise the default indentation
102 value is used. Font size and face of the paragraph (but not the
103 designator) are reset to their default values. To start an
104 indented paragraph with a particular indentation but without a
105 designator, use `""' (two double quotes) as the first argument of
108 For example, to start a paragraph with bullets as the designator
109 and 4 en indentation, write
116 Set up a paragraph with hanging left indentation. The indentation
117 is set to NNN if that argument is supplied (default unit is `n'),
118 otherwise the default indentation value is used. Font size and
119 face are reset to their default values.
122 Move the left margin to the right by the value NNN if specified
123 (default unit is `n'); otherwise the default indentation value is
124 used. Calls to the `RS' macro can be nested.
127 Move the left margin back to level NNN; if no argument is given,
128 it moves one level back. The first level (i.e., no call to `RS'
129 yet) has number 1, and each call to `RS' increases the level by 1.
131 To summarize, the following macros cause a line break with the
132 insertion of vertical space (which amount can be changed with the `PD'
133 macro): `SH', `SS', `TP', `LP' (`PP', `P'), `IP', and `HP'.
135 The macros `RS' and `RE' also cause a break but do not insert
138 Finally, the macros `SH', `SS', `LP' (`PP', `P'), and `RS' reset the
139 indentation to its default value.
142 File: groff, Node: Man font macros, Next: Miscellaneous man macros, Prev: Man usage, Up: man
147 The standard font is roman; the default text size is 10 point. If
148 command line option `-rS=N' is given, use Npt as the default text size.
151 Set the text on the same line or the text on the next line in a
152 font that is one point size smaller than the default font.
155 Set the text on the same line or the text on the next line in bold
156 face font, one point size smaller than the default font.
159 Set its arguments alternately in bold face and italic. Thus,
162 .BI this "word and" that
164 would set "this" and "that" in bold face, and "word and" in
168 Set its arguments alternately in italic and bold face.
171 Set its arguments alternately in roman and italic.
174 Set its arguments alternately in italic and roman.
177 Set its arguments alternately in bold face and roman.
180 Set its arguments alternately in roman and bold face.
183 Set TEXT in bold face. If no text is present on the line where
184 the macro is called, then the text of the next line appears in bold
188 Set TEXT in italic. If no text is present on the line where the
189 macro is called, then the text of the next line appears in italic.
192 File: groff, Node: Miscellaneous man macros, Next: Predefined man strings, Prev: Man font macros, Up: man
197 The default indentation is 7.2 en for all output devices except for
198 `grohtml' which ignores indentation.
201 Set tabs every 0.5 inches. Since this macro is always executed
202 during a call to the `TH' macro, it makes sense to call it only if
203 the tab positions have been changed.
206 Adjust the empty space before a new paragraph (or section). The
207 optional argument gives the amount of space (default unit is `v');
208 without parameter, the value is reset to its default value (1 line
209 for TTY devices, 0.4v otherwise).
211 This affects the macros `SH', `SS', `TP', `LP' (as well as `PP' and
212 `P'), `IP', and `HP'.
215 File: groff, Node: Predefined man strings, Next: Preprocessors in man pages, Prev: Miscellaneous man macros, Up: man
220 The following strings are defined:
223 Switch back to the default font size.
226 The `registered' sign.
229 The `trademark' sign.
233 Left and right quote. This is equal to `\(lq' and `\(rq',
237 File: groff, Node: Preprocessors in man pages, Prev: Predefined man strings, Up: man
239 Preprocessors in `man' pages
240 ----------------------------
242 If a preprocessor like `gtbl' or `geqn' is needed, it has become
243 common usage to make the first line of the man page look like this:
248 Note the single space character after the double quote. WORD consists
249 of letters for the needed preprocessors: `e' for `geqn', `r' for
250 `grefer', `t' for `gtbl'. Modern implementations of the `man' program
251 read this first line and automatically call the right preprocessor(s).
254 File: groff, Node: mdoc, Next: ms, Prev: man, Up: Macro Packages
259 See the `groff_mdoc(7)' man page (type `man groff_mdoc' at the
263 File: groff, Node: ms, Next: me, Prev: mdoc, Up: Macro Packages
268 The `-ms' macros are suitable for reports, letters, books, user
269 manuals, and so forth. The package provides macros for cover pages,
270 section headings, paragraphs, lists, footnotes, pagination, and a table
276 * General ms Structure::
277 * ms Document Control Registers::
278 * ms Cover Page Macros::
281 * Differences from AT&T ms::
284 File: groff, Node: ms Intro, Next: General ms Structure, Prev: ms, Up: ms
289 The original `-ms' macros were included with AT&T `troff' as well as
290 the `man' macros. While the `man' package is intended for brief
291 documents that can be read on-line as well as printed, the `ms' macros
292 are suitable for longer documents that are meant to be printed rather
295 The `ms' macro package included with `groff' is a complete,
296 bottom-up re-implementation. Several macros (specific to AT&T or
297 Berkeley) are not included, while several new commands are. *Note
298 Differences from AT&T ms::, for more information.
301 File: groff, Node: General ms Structure, Next: ms Document Control Registers, Prev: ms Intro, Up: ms
303 General structure of an `ms' document
304 -------------------------------------
306 The `ms' macro package expects a certain amount of structure, but
307 not as much as packages such as `man' or `mdoc'.
309 The simplest documents can begin with a paragraph macro (such as
310 `LP' or `PP'), and consist of text separated by paragraph macros or
311 even blank lines. Longer documents have a structure as follows:
314 If you invoke the `RP' (report) macro on the first line of the
315 document, `groff' prints the cover page information on its own
316 page; otherwise it prints the information on the first page with
317 your document text immediately following. Other document formats
318 found in AT&T `troff' are specific to AT&T or Berkeley, and are
319 not supported in `groff'.
322 By setting number registers, you can change your document's type
323 (font and size), margins, spacing, headers and footers, and
324 footnotes. *Note ms Document Control Registers::, for more
328 A cover page consists of a title, the author's name and
329 institution, an abstract, and the date. (1) (*note General ms
330 Structure-Footnote-1::) *Note ms Cover Page Macros::, for more
334 Following the cover page is your document. You can use the `ms'
335 macros to write reports, letters, books, and so forth. The
336 package is designed for structured documents, consisting of
337 paragraphs interspersed with headings and augmented by lists,
338 footnotes, tables, and other common constructs. *Note ms Body
339 Text::, for more details.
342 Longer documents usually include a table of contents, which you
343 can invoke by placing the `TC' macro at the end of your document.
344 The `ms' macros have minimal indexing facilities, consisting of the
345 `IX' macro, which prints an entry on standard error. Printing the
346 table of contents at the end is necessary since `groff' is a
347 single-pass text formatter, thus it cannot determine the page
348 number of each section until that section has actually been set
349 and printed. Since `ms' output is intended for hardcopy, you can
350 manually relocate the pages containing the table of contents
351 between the cover page and the body text after printing.
354 File: groff, Node: General ms Structure-Footnotes, Up: General ms Structure
356 (1) Actually, only the title is required.
359 File: groff, Node: ms Document Control Registers, Next: ms Cover Page Macros, Prev: General ms Structure, Up: ms
361 Document control registers
362 --------------------------
364 The following is a list of document control number registers. For
365 the sake of consistency, set registers related to margins at the
366 beginning of your document, or just after the `RP' macro. You can set
367 other registers later in your document, but you should keep them
368 together at the beginning to make them easy to find and edit as
375 Defines the page offset (i.e. the left margin). There is no
376 explicit right margin setting; the combination of the `PO' and
377 `LL' registers implicitly define the right margin width.
379 Effective: next page.
384 Defines the line length (i.e. the width of the body text).
386 Effective: next paragraph.
391 Defines the title length (i.e. the header and footer width). This
392 is usually the same as `LL', but not necessarily.
394 Effective: next paragraph.
399 Defines the header margin height at the top of the page.
401 Effective: next page.
406 Defines the footer margin height at the bottom of the page.
408 Effective: next page.
416 Defines the point size of the body text.
418 Effective: next paragraph.
423 Defines the space between lines (line height plus leading).
425 Effective: next paragraph.
433 Defines the initial indent of a `.PP' paragraph.
435 Effective: next paragraph.
440 Defines the space between paragraphs.
442 Effective: next paragraph.
447 Defines the indent on both sides of a quoted (`.QP') paragraph.
449 Effective: next paragraph.
457 Defines the length of a footnote.
459 Effective: next footnote.
461 Default: `\n[LL]' * 5 / 6.
464 Defines the footnote indent.
466 Effective: next footnote.
473 Prints the footnote number as a superscript; indents the
477 Prints the number followed by a period (like 1.) and indents
481 Like 1, without an indent.
484 Like 1, but prints the footnote number as a hanging paragraph.
486 Effective: next footnote.
490 Miscellaneous Number Registers
491 ..............................
493 - Register: \n[MINGW]
494 Defines the minimum width between columns in a multi-column
497 Effective: next page.
502 File: groff, Node: ms Cover Page Macros, Next: ms Body Text, Prev: ms Document Control Registers, Up: ms
507 Use the following macros to create a cover page for your document in
511 Specifies the report format for your document. The report format
512 creates a separate cover page. The default action (no `.RP'
513 macro) is to print a subset of the cover page on page 1 of your
516 If you use the word `no' as an optional argument, `groff' prints a
517 title page but does not repeat any of the title page information
518 (title, author, abstract, etc.) on page 1 of the document.
521 (optional) Print the current date, or the arguments to the macro
522 if any, on the title page (if specified) and in the footers. This
523 is the default for `nroff'.
526 (optional) Print the current date, or the arguments to the macro
527 if any, on the title page (if specified) but not in the footers.
528 This is the default for `troff'.
531 Specifies the document title. `groff' collects text following the
532 `.TL' macro into the title, until reaching the author name or
536 Specifies the author's name, which appears on the line (or lines)
537 immediately following. You can specify multiple authors as
544 University of West Bumblefuzz
548 Monolithic Corporation
554 Specifies the author's institution. You can specify multiple
555 institutions in the same way that you specify multiple authors.
558 Begins the abstract. The default is to print the word ABSTRACT,
559 centered and in italics, above the text of the abstract. The word
560 `no' as an optional argument suppresses this heading.
565 The following is example mark-up for a title page.
570 The Inevitability of Code Bloat
571 in Commercial and Free Software
575 University of West Bumblefuzz
577 This report examines the long-term growth
578 of the code bases in two large, popular software
579 packages; the free Emacs and the commercial
581 While differences appear in the type or order
582 of features added, due to the different
583 methodologies used, the results are the same
586 The free software approach is shown to be
587 superior in that while free software can
588 become as bloated as commercial offerings,
589 free software tends to have fewer serious
590 bugs and the added features are in line with
594 ... the rest of the paper follows ...
597 File: groff, Node: ms Body Text, Next: ms Page Layout, Prev: ms Cover Page Macros, Up: ms
602 This section describes macros used to mark up the body of your
603 document. Examples include paragraphs, sections, and other groups.
609 * Highlighting in ms::
613 * ms Displays and Keeps::
615 * Example multi-page table::
619 File: groff, Node: Paragraphs in ms, Next: Headings in ms, Prev: ms Body Text, Up: ms Body Text
624 The following paragraph types are available.
627 Sets a paragraph with an initial indent.
630 Sets a paragraph with no initial indent.
633 Sets a paragraph that is indented at both left and right margins.
634 The effect is identical to the HTML `<BLOCKQUOTE>' element. The
635 next paragraph or heading returns margins to normal.
638 Sets a paragraph whose lines are indented, except for the first
639 line. This is a Berkeley extension.
641 The following markup uses all four paragraph macros.
645 Cases used in the study
647 The following software and versions were
648 considered for this report.
650 For commercial software, we chose
651 .B "Microsoft Word for Windows" ,
652 starting with version 1.0 through the
653 current version (Word 2000).
655 For free software, we chose
657 from its first appearance as a standalone
658 editor through the current version (v20).
659 See [Bloggs 2002] for details.
661 Franklin's Law applied to software:
662 software expands to outgrow both
663 RAM and disk space over time.
668 .I "Everyone's a Critic" ,
669 Underground Press, March 2002.
670 A definitive work that answers all questions
671 and criticisms about the quality and usability of
675 File: groff, Node: Headings in ms, Next: Highlighting in ms, Prev: Paragraphs in ms, Up: ms Body Text
680 Use headings to create a hierarchical structure for your document.
681 The `ms' macros print headings in *bold*, using the same font family
682 and point size as the body text.
684 The following describes the heading macros:
686 - Macro: .NH curr-level
687 - Macro: .NH S level0 ...
688 Numbered heading. The argument is either a numeric argument to
689 indicate the level of the heading, or the letter `S' followed by
690 numeric arguments to set the heading level explicitly.
692 If you specify heading levels out of sequence, such as invoking
693 `.NH 3' after `.NH 1', `groff' prints a warning on standard error.
696 Unnumbered subheading.
699 File: groff, Node: Highlighting in ms, Next: Lists in ms, Prev: Headings in ms, Up: ms Body Text
704 The `ms' macros provide a variety of methods to highlight or
707 - Macro: .B [txt [post [pre]]]
708 Sets its first argument in *bold type*. If you specify a second
709 argument, `groff' prints it in the previous font after the bold
710 text, with no intervening space (this allows you to set
711 punctuation after the highlighted text without highlighting the
712 punctuation). Similarly, it prints the third argument (if any) in
713 the previous font *before* the first argument. For example,
720 If you give this macro no arguments, `groff' prints all text
721 following in bold until the next highlighting, paragraph, or
724 - Macro: .R [txt [post [pre]]]
725 Sets its first argument in roman (or regular) type. It operates
726 similarly to the `B' macro otherwise.
728 - Macro: .I [txt [post [pre]]]
729 Sets its first argument in _italic type_. It operates similarly
730 to the `B' macro otherwise.
732 - Macro: .CW [txt [post [pre]]]
733 Sets its first argument in a `constant width face'. It operates
734 similarly to the `B' macro otherwise.
736 - Macro: .BI [txt [post [pre]]]
737 Sets its first argument in bold italic type. It operates
738 similarly to the `B' macro otherwise.
741 Prints its argument and draws a box around it. If you want to box
742 a string that contains spaces, use a digit-width space (`\0').
744 - Macro: .UL [txt [post]]
745 Prints its first argument with an underline. If you specify a
746 second argument, `groff' prints it in the previous font after the
747 underlined text, with no intervening space.
750 Prints all text following in larger type (two points larger than
751 the current point size) until the next font size, highlighting,
752 paragraph, or heading macro. You can specify this macro multiple
753 times to enlarge the point size as needed.
756 Prints all text following in smaller type (two points smaller than
757 the current point size) until the next type size, highlighting,
758 paragraph, or heading macro. You can specify this macro multiple
759 times to reduce the point size as needed.
762 Prints all text following in the normal point size (that is, the
763 value of the `PS' register).
766 File: groff, Node: Lists in ms, Next: Indents in ms, Prev: Highlighting in ms, Up: ms Body Text
771 The `.IP' macro handles duties for all lists.
773 - Macro: .IP [marker [width]]
774 The MARKER is usually a bullet glyph (`\[bu]') for unordered
775 lists, a number (or auto-incrementing number register) for
776 numbered lists, or a word or phrase for indented (glossary-style)
779 The WIDTH specifies the indent for the body of each list item; its
780 default unit is `n'. Once specified, the indent remains the same
781 for all list items in the document until specified again.
783 The following is an example of a bulleted list.
806 The following is an example of a numbered list.
829 Note the use of the auto-incrementing number register in this
833 The following is an example of a glossary-style list.
836 A glossary-style list:
838 Two or more attorneys.
849 A glossary-style list:
852 Two or more attorneys.
854 guns Firearms, preferably large-caliber.
857 Gotta pay for those lawyers and guns!
859 In the last example, the `IP' macro places the definition on the
860 same line as the term if it has enough space; otherwise, it breaks to
861 the next line and starts the definition below the term. This may or
862 may not be the effect you want, especially if some of the definitions
863 break and some do not. The following examples show two possible ways
866 The first workaround uses the `br' request to force a break after
867 printing the term or label.
870 A glossary-style list:
872 Two or more attorneys.
875 Firearms, preferably large-caliber.
877 Gotta pay for those lawyers and guns!
880 The second workaround uses the `\p' escape to force the break. Note
881 the space following the escape; this is important. If you omit the
882 space, `groff' prints the first word on the same line as the term or
883 label (if it fits) *then* breaks the line.
886 A glossary-style list:
888 Two or more attorneys.
890 \p Firearms, preferably large-caliber.
892 Gotta pay for those lawyers and guns!
895 To set nested lists, use the `RS' and `RE' macros. *Note Indents in
896 ms::, for more information.
928 File: groff, Node: Indents in ms, Next: Tabstops in ms, Prev: Lists in ms, Up: ms Body Text
933 In many situations, you may need to indent a section of text while
934 still wrapping and filling. *Note Lists in ms::, for an example of
939 These macros begin and end an indented section. The `PI' register
940 controls the amount of indent, allowing the indented text to line
941 up under hanging and indented paragraphs.
943 *Note ms Displays and Keeps::, for macros to indent and turn off
947 File: groff, Node: Tabstops in ms, Next: ms Displays and Keeps, Prev: Indents in ms, Up: ms Body Text
952 Use the `ta' request to define tab stops as needed. *Note Tabs and
956 Use this macro to reset the tab stops to the default for `ms'
957 (every 5n). You can redefine the `TA' macro to create a different
958 set of default tab stops.
961 File: groff, Node: ms Displays and Keeps, Next: ms Insertions, Prev: Tabstops in ms, Up: ms Body Text
966 Use displays to show text-based examples or figures (such as code
969 Displays turn off filling, so lines of code are displayed as-is
970 without inserting `br' requests in between each line. Displays can be
971 "kept" on a single page, or allowed to break across pages.
976 Left-justified display. The `.DS L' call generates a page break,
977 if necessary, to keep the entire display on one page. The `LD'
978 macro allows the display to break across pages. The `DE' macro
984 Indents the display as defined by the `DI' register. The `.DS I'
985 call generates a page break, if necessary, to keep the entire
986 display on one page. The `ID' macro allows the display to break
987 across pages. The `DE' macro ends the display.
992 Sets a block-centered display: the entire display is
993 left-justified, but indented so that the longest line in the
994 display is centered on the page. The `.DS B' call generates a
995 page break, if necessary, to keep the entire display on one page.
996 The `BD' macro allows the display to break across pages. The `DE'
997 macro ends the display.
1002 Sets a centered display: each line in the display is centered.
1003 The `.DS C' call generates a page break, if necessary, to keep the
1004 entire display on one page. The `CD' macro allows the display to
1005 break across pages. The `DE' macro ends the display.
1010 Right-justifies each line in the display. The `.DS R' call
1011 generates a page break, if necessary, to keep the entire display
1012 on one page. The `RD' macro allows the display to break across
1013 pages. The `DE' macro ends the display.
1016 On occasion, you may want to "keep" other text together on a page.
1017 For example, you may want to keep two paragraphs together, or a
1018 paragraph that refers to a table (or list, or other item) immediately
1019 following. The `ms' macros provide the `KS' and `KE' macros for this
1024 The `KS' macro begins a block of text to be kept on a single page,
1025 and the `KE' macro ends the block.
1029 Specifies a "floating keep"; if the keep cannot fit on the current
1030 page, `groff' holds the contents of the keep and allows text
1031 following the keep (in the source file) to fill in the remainder of
1032 the current page. When the page breaks, whether by an explicit
1033 `bp' request or by reaching the end of the page, `groff' prints
1034 the floating keep at the top of the new page. This is useful for
1035 printing large graphics or tables that do not need to appear
1036 exactly where specified.
1038 You can also use the `ne' request to force a page break if there is
1039 not enough vertical space remaining on the page.
1042 Use the following macros to draw a box around a section of text
1043 (such as a display).
1047 Marks the beginning and ending of text that is to have a box drawn
1048 around it. The `B1' macro begins the box; the `B2' macro ends it.
1049 Text in the box is automatically placed in a diversion (keep).
1052 File: groff, Node: ms Insertions, Next: Example multi-page table, Prev: ms Displays and Keeps, Up: ms Body Text
1054 Tables, figures, equations, and references
1055 ..........................................
1057 The `ms' macros support the standard `groff' preprocessors: `tbl',
1058 `pic', `eqn', and `refer'. You mark text meant for preprocessors by
1059 enclosing it in pairs of tags as follows.
1063 Denotes a table, to be processed by the `tbl' preprocessor. The
1064 optional argument `H' to `TS' instructs `groff' to create a
1065 running header with the information up to the `TH' macro. `groff'
1066 prints the header at the beginning of the table; if the table runs
1067 onto another page, `groff' prints the header on the next page as
1072 Denotes a graphic, to be processed by the `pic' preprocessor. You
1073 can create a `pic' file by hand, using the AT&T `pic' manual
1074 available on the Web as a reference, or by using a graphics
1075 program such as `xfig'.
1077 - Macro: .EQ [align]
1079 Denotes an equation, to be processed by the `eqn' preprocessor.
1080 The optional ALIGN argument can be `C', `L', or `I' to center (the
1081 default), left-justify, or indent the equation.
1085 Denotes a reference, to be processed by the `refer' preprocessor.
1086 The GNU `refer(1)' man page provides a comprehensive reference to
1087 the preprocessor and the format of the bibliographic database.
1091 * Example multi-page table::
1094 File: groff, Node: Example multi-page table, Next: ms Footnotes, Prev: ms Insertions, Up: ms Body Text
1096 An example multi-page table
1097 ...........................
1099 The following is an example of how to set up a table that may print
1100 across two or more pages.
1106 Text ...of heading...
1111 ... the rest of the table follows...
1116 File: groff, Node: ms Footnotes, Prev: Example multi-page table, Up: ms Body Text
1121 The `ms' macro package has a flexible footnote system. You can
1122 specify either numbered footnotes or symbolic footnotes (that is, using
1123 a marker such as a dagger symbol).
1126 Specifies the location of a numbered footnote marker in the text.
1130 Specifies the text of the footnote. The default action is to
1131 create a numbered footnote; you can create a symbolic footnote by
1132 specifying a "mark" glyph (such as `\[dg]' for the dagger glyph)
1133 in the body text and as an argument to the `FS' macro, followed by
1134 the text of the footnote and the `FE' macro.
1136 You can control how `groff' prints footnote numbers by changing the
1137 value of the `FF' register. *Note ms Document Control Registers::.
1140 File: groff, Node: ms Page Layout, Next: Differences from AT&T ms, Prev: ms Body Text, Up: ms
1145 The default output from the `ms' macros provides a minimalist page
1146 layout: it prints a single column, with the page number centered at the
1147 top of each page. It prints no footers.
1149 You can change the layout by setting the proper number registers and
1154 * ms Headers and Footers::
1156 * ms Multiple Columns::
1158 * ms Strings and Special Characters::
1161 File: groff, Node: ms Headers and Footers, Next: ms Margins, Prev: ms Page Layout, Up: ms Page Layout
1166 For documents that do not distinguish between odd and even pages,
1167 set the following strings:
1172 Sets the left, center, and right headers.
1177 Sets the left, center, and right footers.
1180 For documents that need different information printed in the even
1181 and odd pages, use the following macros:
1183 - Macro: .OH 'left'center'right'
1184 - Macro: .EH 'left'center'right'
1185 - Macro: .OF 'left'center'right'
1186 - Macro: .EF 'left'center'right'
1187 The `OH' and `EH' macros define headers for the odd and even pages;
1188 the `OF' and `EF' macros define footers for the odd and even pages.
1189 This is more flexible than defining the individual strings.
1191 You can replace the quote (`'') marks with any character not
1192 appearing in the header or footer text.
1195 File: groff, Node: ms Margins, Next: ms Multiple Columns, Prev: ms Headers and Footers, Up: ms Page Layout
1200 You control margins using a set of number registers. *Note ms
1201 Document Control Registers::, for details.
1204 File: groff, Node: ms Multiple Columns, Next: ms TOC, Prev: ms Margins, Up: ms Page Layout
1209 The `ms' macros can set text in as many columns as will reasonably
1210 fit on the page. The following macros are available; all of them force
1211 a page break if a multi-column mode is already set. However, if the
1212 current mode is single-column, starting a multi-column mode does *not*
1221 - Macro: .MC [width [gutter]]
1222 Multi-column mode. If you specify no arguments, it is equivalent
1223 to the `2C' macro. Otherwise, WIDTH is the width of each column
1224 and GUTTER is the space between columns. The `MINGW' number
1225 register controls the default gutter width.
1228 File: groff, Node: ms TOC, Next: ms Strings and Special Characters, Prev: ms Multiple Columns, Up: ms Page Layout
1230 Creating a table of contents
1231 ............................
1233 The facilities in the `ms' macro package for creating a table of
1234 contents are semi-automated at best. Assuming that you want the table
1235 of contents to consist of the document's headings, you need to repeat
1236 those headings wrapped in `XS' and `XE' macros.
1241 These macros define a table of contents or an individual entry in
1242 the table of contents, depending on their use. The macros are
1243 very simple; they cannot indent a heading based on its level. The
1244 easiest way to work around this is to add tabs to the table of
1245 contents string. The following is an example:
1264 You can manually create a table of contents by beginning with the
1265 `XS' macro for the first entry, specifying the page number for
1266 that entry as the argument to `XS'. Add subsequent entries using
1267 the `XA' macro, specifying the page number for that entry as the
1268 argument to `XA'. The following is an example:
1274 A Brief History of the Universe
1276 Details of Galactic Formation
1282 Prints the table of contents on a new page, setting the page
1283 number to *i* (Roman numeral one). You should usually place this
1284 macro at the end of the file, since `groff' is a single-pass
1285 formatter and can only print what has been collected up to the
1286 point that the `TC' macro appears.
1288 The optional argument `no' suppresses printing the title specified
1289 by the string register `TOC'.
1292 Prints the table of contents on a new page, using the current page
1293 numbering sequence. Use this macro to print a manually-generated
1294 table of contents at the beginning of your document.
1296 The optional argument `no' suppresses printing the title specified
1297 by the string register `TOC'.
1299 The `Groff and Friends HOWTO' includes a `sed' script that
1300 automatically inserts `XS' and `XE' macro entries after each heading in
1303 Altering the `NH' macro to automatically build the table of contents
1304 is perhaps initially more difficult, but would save a great deal of
1305 time in the long run if you use `ms' regularly.
1308 File: groff, Node: ms Strings and Special Characters, Prev: ms TOC, Up: ms Page Layout
1310 Strings and Special Characters
1311 ..............................
1313 The `ms' macros provide the following predefined strings. You can
1314 change the string definitions to help in creating documents in
1315 languages other than English.
1317 - String: \*[REFERENCES]
1318 Contains the string printed at the beginning of the references
1319 (bibliography) page. The default is `References'.
1321 - String: \*[ABSTRACT]
1322 Contains the string printed at the beginning of the abstract. The
1323 default is `ABSTRACT'.
1326 Contains the string printed at the beginning of the table of
1329 - String: \*[MONTH1]
1330 - String: \*[MONTH2]
1331 - String: \*[MONTH3]
1332 - String: \*[MONTH4]
1333 - String: \*[MONTH5]
1334 - String: \*[MONTH6]
1335 - String: \*[MONTH7]
1336 - String: \*[MONTH8]
1337 - String: \*[MONTH9]
1338 - String: \*[MONTH10]
1339 - String: \*[MONTH11]
1340 - String: \*[MONTH12]
1341 Prints the full name of the month in dates. The default is
1342 `January', `February', etc.
1344 The following special characters are available(1) (*note ms Strings
1345 and Special Characters-Footnote-1::):
1352 Prints typographer's quotes in troff, plain quotes in nroff. `*Q'
1353 is the left quote and `*U' is the right quote.
1355 Improved accent marks are available in the `ms' macros.
1358 Specify this macro at the beginning of your document to enable
1359 extended accent marks and special characters. This is a Berkeley
1362 To use the accent marks, place them *after* the character being
1365 The following accent marks are available after invoking the `AM'
1398 The following are standalone characters available after invoking the
1402 Upside-down question mark.
1405 Upside-down exclamation point.
1429 Lowercase ae ligature.
1432 Uppercase AE ligature.
1435 File: groff, Node: ms Strings and Special Characters-Footnotes, Up: ms Strings and Special Characters
1437 (1) For an explanation what special characters are see *Note Special
1441 File: groff, Node: Differences from AT&T ms, Prev: ms Page Layout, Up: ms
1443 Differences from AT&T `ms'
1444 --------------------------
1446 This section lists the (minor) differences between the `groff -ms'
1447 macros and AT&T `troff -ms' macros.
1451 * Missing ms Macros::
1452 * Additional ms Macros::
1455 File: groff, Node: Missing ms Macros, Next: Additional ms Macros, Prev: Differences from AT&T ms, Up: Differences from AT&T ms
1457 `troff' macros not appearing in `groff'
1458 .......................................
1460 Macros missing from `groff -ms' are cover page macros specific to
1461 Bell Labs. The macros known to be missing are:
1464 Technical memorandum; a cover sheet style
1467 Internal memorandum; a cover sheet style
1470 Memo for record; a cover sheet style
1473 Memo for file; a cover sheet style
1476 Engineer's notes; a cover sheet style
1479 Computing Science Tech Report; a cover sheet style
1485 Cover sheet information
1491 File: groff, Node: Additional ms Macros, Prev: Missing ms Macros, Up: Differences from AT&T ms
1493 `groff' macros not appearing in AT&T `troff'
1494 ............................................
1496 The `groff -ms' macros have a few minor extensions compared to the
1497 AT&T `troff -ms' macros.
1500 Improved accent marks. *Note ms Strings and Special Characters::,
1504 Indented display. The default behavior of AT&T `troff -ms' was to
1505 indent; the `groff' default prints displays flush left with the
1509 Print text in `constant width' (Courier) font.
1512 Indexing term (printed on standard error). You can write a script
1513 to capture and process an index generated in this manner.
1516 The following additional number registers appear in `groff -ms':
1518 - Register: \n[MINGW]
1519 Specifies a minimum space between columns (for multi-column
1520 output); this takes the place of the `GW' register that was
1521 documented but apparently not implemented in AT&T `troff'.
1524 Several new string registers are available as well. You can change
1525 these to handle (for example) the local language. *Note ms Strings and
1526 Special Characters::, for details.
1529 File: groff, Node: me, Next: mm, Prev: ms, Up: Macro Packages
1534 See the `meintro.me' and `meref.me' documents in groff's `doc'
1538 File: groff, Node: mm, Prev: me, Up: Macro Packages
1543 See the `groff_mm(7)' man page (type `man groff_mm' at the command
1547 File: groff, Node: gtroff Reference, Next: Preprocessors, Prev: Macro Packages, Up: Top
1552 This chapter covers *all* of the facilities of `gtroff'. Users of
1553 macro packages may skip it if not interested in details.
1558 * Input Conventions::
1562 * Embedded Commands::
1564 * Manipulating Filling and Adjusting::
1565 * Manipulating Hyphenation::
1566 * Manipulating Spacing::
1568 * Character Translations::
1569 * Troff and Nroff Mode::
1577 * Conditionals and Loops::
1580 * Drawing Requests::
1584 * Suppressing output::
1587 * Postprocessor Access::
1589 * Gtroff Internals::
1591 * Implementation Differences::
1594 File: groff, Node: Text, Next: Input Conventions, Prev: gtroff Reference, Up: gtroff Reference
1599 `gtroff' input files contain text with control commands interspersed
1600 throughout. But, even without control codes, `gtroff' still does
1601 several things with the input text:
1603 * filling and adjusting
1605 * adding additional space after sentences
1609 * inserting implicit line breaks
1613 * Filling and Adjusting::
1617 * Implicit Line Breaks::
1620 File: groff, Node: Filling and Adjusting, Next: Hyphenation, Prev: Text, Up: Text
1622 Filling and Adjusting
1623 ---------------------
1625 When `gtroff' reads text, it collects words from the input and fits
1626 as many of them together on one output line as it can. This is known as
1629 Once `gtroff' has a "filled" line, it tries to "adjust" it. This
1630 means it widens the spacing between words until the text reaches the
1631 right margin (in the default adjustment mode). Extra spaces between
1632 words are preserved, but spaces at the end of lines are ignored.
1633 Spaces at the front of a line cause a "break" (breaks are explained in
1634 *Note Implicit Line Breaks::).
1636 *Note Manipulating Filling and Adjusting::.
1639 File: groff, Node: Hyphenation, Next: Sentences, Prev: Filling and Adjusting, Up: Text
1644 Since the odds are not great for finding a set of words, for every
1645 output line, which fit nicely on a line without inserting excessive
1646 amounts of space between words, `gtroff' hyphenates words so that it
1647 can justify lines without inserting too much space between words. It
1648 uses an internal hyphenation algorithm (a simplified version of the
1649 algorithm used within TeX) to indicate which words can be hyphenated
1650 and how to do so. When a word is hyphenated, the first part of the
1651 word is added to the current filled line being output (with an attached
1652 hyphen), and the other portion is added to the next line to be filled.
1654 *Note Manipulating Hyphenation::.
1657 File: groff, Node: Sentences, Next: Tab Stops, Prev: Hyphenation, Up: Text
1662 Although it is often debated, some typesetting rules say there
1663 should be different amounts of space after various punctuation marks.
1664 For example, the `Chicago typsetting manual' says that a period at the
1665 end of a sentence should have twice as much space following it as would
1666 a comma or a period as part of an abbreviation.
1668 `gtroff' does this by flagging certain characters (normally `!',
1669 `?', and `.') as "end-of-sentence" characters. When `gtroff'
1670 encounters one of these characters at the end of a line, it appends a
1671 normal space followed by a "sentence space" in the formatted output.
1672 (This justifies one of the conventions mentioned in *Note Input
1675 In addition, the following characters and symbols are treated
1676 transparently while handling end-of-sentence characters: `"', `'', `)',
1677 `]', `*', `\[dg]', and `\[rq]'.
1679 See the `cflags' request in *Note Using Symbols::, for more details.
1681 To prevent the insertion of extra space after an end-of-sentence
1682 character (at the end of a line), append `\&'.
nant's projects / dragonfly.git / blob