diff options
Diffstat (limited to 'contrib/groff/doc/groff-2')
| -rw-r--r-- | contrib/groff/doc/groff-2 | 1683 |
1 files changed, 1683 insertions, 0 deletions
diff --git a/contrib/groff/doc/groff-2 b/contrib/groff/doc/groff-2 new file mode 100644 index 0000000..d1f7f99 --- /dev/null +++ b/contrib/groff/doc/groff-2 @@ -0,0 +1,1683 @@ +This is groff, produced by makeinfo version 4.2 from ./groff.texinfo. + +This manual documents GNU `troff' version 1.18. + + Copyright (C) 1994-2000, 2001, 2002 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.1 or any later version published by the Free Software + Foundation; with no Invariant Sections, with the Front-Cover texts + being `A GNU Manual," and with the Back-Cover Texts as in (a) + below. A copy of the license is included in the section entitled + `GNU Free Documentation License." + + (a) The FSF's Back-Cover Text is: `You have freedom to copy and + modify this GNU Manual, like GNU software. Copies published by + the Free Software Foundation raise funds for GNU development." + +INFO-DIR-SECTION Miscellaneous +START-INFO-DIR-ENTRY +* Groff: (groff). The GNU troff document formatting system. +END-INFO-DIR-ENTRY + + +File: groff, Node: Man usage, Next: Man font macros, Prev: Man options, Up: man + +Usage +----- + + This section describes the available macros for manual pages. For +further customization, put additional macros and requests into the file +`man.local' which is loaded immediately after the `man' package. + + - Macro: .TH title section [extra1 [extra2 [extra3]]] + Set the title of the man page to TITLE and the section to SECTION, + which must have a value between 1 and 8. The value of SECTION may + also have a string appended, e.g. `.pm', to indicate a specific + subsection of the man pages. + + Both TITLE and SECTION are positioned at the left and right in the + header line (with SECTION in parentheses immediately appended to + TITLE. EXTRA1 is positioned in the middle of the footer line. + EXTRA2 is positioned at the left in the footer line (or at the + left on even pages and at the right on odd pages if double-sided + printing is active). EXTRA3 is centered in the header line. + + For HTML output, headers and footers are completely suppressed. + + Additionally, this macro starts a new page; the new line number + is 1 again (except if the `-rC1' option is given on the command + line) - this feature is intended only for formatting multiple man + pages; a single man page should contain exactly one `TH' macro at + the beginning of the file. + + - Macro: .SH [heading] + Set up an unnumbered section heading sticking out to the left. + Prints out all the text following `SH' up to the end of the line + (or the text in the next line if there is no argument to `SH') in + bold face, one size larger than the base document size. + Additionally, the left margin for the following text is reset to + its default value. + + - Macro: .SS [heading] + Set up an unnumbered (sub)section heading. Prints out all the text + following `SS' up to the end of the line (or the text in the next + line if there is no argument to `SS') in bold face, at the same + size as the base document size. Additionally, the left margin for + the following text is reset to its default value. + + - Macro: .TP [nnn] + Set up an indented paragraph with label. The indentation is set to + NNN if that argument is supplied (the default unit is `n' if + omitted), otherwise it is set to the default indentation value. + + The first line of text following this macro is interpreted as a + string to be printed flush-left, as it is appropriate for a label. + It is not interpreted as part of a paragraph, so there is no + attempt to fill the first line with text from the following input + lines. Nevertheless, if the label is not as wide as the + indentation, then the paragraph starts at the same line (but + indented), continuing on the following lines. If the label is + wider than the indentation, then the descriptive part of the + paragraph begins on the line following the label, entirely + indented. Note that neither font shape nor font size of the label + is set to a default value; on the other hand, the rest of the text + has default font settings. + + - Macro: .LP + - Macro: .PP + - Macro: .P + These macros are mutual aliases. Any of them causes a line break + at the current position, followed by a vertical space downwards by + the amount specified by the `PD' macro. The font size and shape + are reset to the default value (10pt roman if no `-rS' option is + given on the command line). Finally, the current left margin is + restored. + + - Macro: .IP [designator [nnn]] + Set up an indented paragraph, using DESIGNATOR as a tag to mark + its beginning. The indentation is set to NNN if that argument is + supplied (default unit is `n'), otherwise the default indentation + value is used. Font size and face of the paragraph (but not the + designator) are reset to their default values. To start an + indented paragraph with a particular indentation but without a + designator, use `""' (two double quotes) as the first argument of + `IP'. + + For example, to start a paragraph with bullets as the designator + and 4 en indentation, write + + + .IP \(bu 4 + + + - Macro: .HP [nnn] + Set up a paragraph with hanging left indentation. The indentation + is set to NNN if that argument is supplied (default unit is `n'), + otherwise the default indentation value is used. Font size and + face are reset to their default values. + + - Macro: .RS [nnn] + Move the left margin to the right by the value NNN if specified + (default unit is `n'); otherwise the default indentation value is + used. Calls to the `RS' macro can be nested. + + - Macro: .RE [nnn] + Move the left margin back to level NNN; if no argument is given, + it moves one level back. The first level (i.e., no call to `RS' + yet) has number 1, and each call to `RS' increases the level by 1. + + To summarize, the following macros cause a line break with the +insertion of vertical space (which amount can be changed with the `PD' +macro): `SH', `SS', `TP', `LP' (`PP', `P'), `IP', and `HP'. + + The macros `RS' and `RE' also cause a break but do not insert +vertical space. + + Finally, the macros `SH', `SS', `LP' (`PP', `P'), and `RS' reset the +indentation to its default value. + + +File: groff, Node: Man font macros, Next: Miscellaneous man macros, Prev: Man usage, Up: man + +Macros to set fonts +------------------- + + The standard font is roman; the default text size is 10 point. If +command line option `-rS=N' is given, use Npt as the default text size. + + - Macro: .SM [text] + Set the text on the same line or the text on the next line in a + font that is one point size smaller than the default font. + + - Macro: .SB [text] + Set the text on the same line or the text on the next line in bold + face font, one point size smaller than the default font. + + - Macro: .BI text + Set its arguments alternately in bold face and italic. Thus, + + + .BI this "word and" that + + would set "this" and "that" in bold face, and "word and" in + italics. + + - Macro: .IB text + Set its arguments alternately in italic and bold face. + + - Macro: .RI text + Set its arguments alternately in roman and italic. + + - Macro: .IR text + Set its arguments alternately in italic and roman. + + - Macro: .BR text + Set its arguments alternately in bold face and roman. + + - Macro: .RB text + Set its arguments alternately in roman and bold face. + + - Macro: .B [text] + Set TEXT in bold face. If no text is present on the line where + the macro is called, then the text of the next line appears in bold + face. + + - Macro: .I [text] + Set TEXT in italic. If no text is present on the line where the + macro is called, then the text of the next line appears in italic. + + +File: groff, Node: Miscellaneous man macros, Next: Predefined man strings, Prev: Man font macros, Up: man + +Miscellaneous macros +-------------------- + + The default indentation is 7.2 en for all output devices except for +`grohtml' which ignores indentation. + + - Macro: .DT + Set tabs every 0.5 inches. Since this macro is always executed + during a call to the `TH' macro, it makes sense to call it only if + the tab positions have been changed. + + - Macro: .PD [nnn] + Adjust the empty space before a new paragraph (or section). The + optional argument gives the amount of space (default unit is `v'); + without parameter, the value is reset to its default value (1 line + for TTY devices, 0.4v otherwise). + + This affects the macros `SH', `SS', `TP', `LP' (as well as `PP' and +`P'), `IP', and `HP'. + + +File: groff, Node: Predefined man strings, Next: Preprocessors in man pages, Prev: Miscellaneous man macros, Up: man + +Predefined strings +------------------ + + The following strings are defined: + + - String: \*[S] + Switch back to the default font size. + + - String: \*[R] + The `registered' sign. + + - String: \*[Tm] + The `trademark' sign. + + - String: \*[lq] + - String: \*[rq] + Left and right quote. This is equal to `\(lq' and `\(rq', + respectively. + + +File: groff, Node: Preprocessors in man pages, Prev: Predefined man strings, Up: man + +Preprocessors in `man' pages +---------------------------- + + If a preprocessor like `gtbl' or `geqn' is needed, it has become +common usage to make the first line of the man page look like this: + + + '\" WORD + +Note the single space character after the double quote. WORD consists +of letters for the needed preprocessors: `e' for `geqn', `r' for +`grefer', `t' for `gtbl'. Modern implementations of the `man' program +read this first line and automatically call the right preprocessor(s). + + +File: groff, Node: mdoc, Next: ms, Prev: man, Up: Macro Packages + +`mdoc' +====== + + See the `groff_mdoc(7)' man page (type `man groff_mdoc' at the +command line). + + +File: groff, Node: ms, Next: me, Prev: mdoc, Up: Macro Packages + +`ms' +==== + + The `-ms' macros are suitable for reports, letters, books, user +manuals, and so forth. The package provides macros for cover pages, +section headings, paragraphs, lists, footnotes, pagination, and a table +of contents. + +* Menu: + +* ms Intro:: +* General ms Structure:: +* ms Document Control Registers:: +* ms Cover Page Macros:: +* ms Body Text:: +* ms Page Layout:: +* Differences from AT&T ms:: + + +File: groff, Node: ms Intro, Next: General ms Structure, Prev: ms, Up: ms + +Introduction to `ms' +-------------------- + + The original `-ms' macros were included with AT&T `troff' as well as +the `man' macros. While the `man' package is intended for brief +documents that can be read on-line as well as printed, the `ms' macros +are suitable for longer documents that are meant to be printed rather +than read on-line. + + The `ms' macro package included with `groff' is a complete, +bottom-up re-implementation. Several macros (specific to AT&T or +Berkeley) are not included, while several new commands are. *Note +Differences from AT&T ms::, for more information. + + +File: groff, Node: General ms Structure, Next: ms Document Control Registers, Prev: ms Intro, Up: ms + +General structure of an `ms' document +------------------------------------- + + The `ms' macro package expects a certain amount of structure, but +not as much as packages such as `man' or `mdoc'. + + The simplest documents can begin with a paragraph macro (such as +`LP' or `PP'), and consist of text separated by paragraph macros or +even blank lines. Longer documents have a structure as follows: + +*Document type* + If you invoke the `RP' (report) macro on the first line of the + document, `groff' prints the cover page information on its own + page; otherwise it prints the information on the first page with + your document text immediately following. Other document formats + found in AT&T `troff' are specific to AT&T or Berkeley, and are + not supported in `groff'. + +*Format and layout* + By setting number registers, you can change your document's type + (font and size), margins, spacing, headers and footers, and + footnotes. *Note ms Document Control Registers::, for more + details. + +*Cover page* + A cover page consists of a title, the author's name and + institution, an abstract, and the date. (1) (*note General ms + Structure-Footnote-1::) *Note ms Cover Page Macros::, for more + details. + +*Body* + Following the cover page is your document. You can use the `ms' + macros to write reports, letters, books, and so forth. The + package is designed for structured documents, consisting of + paragraphs interspersed with headings and augmented by lists, + footnotes, tables, and other common constructs. *Note ms Body + Text::, for more details. + +*Table of contents* + Longer documents usually include a table of contents, which you + can invoke by placing the `TC' macro at the end of your document. + The `ms' macros have minimal indexing facilities, consisting of the + `IX' macro, which prints an entry on standard error. Printing the + table of contents at the end is necessary since `groff' is a + single-pass text formatter, thus it cannot determine the page + number of each section until that section has actually been set + and printed. Since `ms' output is intended for hardcopy, you can + manually relocate the pages containing the table of contents + between the cover page and the body text after printing. + + +File: groff, Node: General ms Structure-Footnotes, Up: General ms Structure + + (1) Actually, only the title is required. + + +File: groff, Node: ms Document Control Registers, Next: ms Cover Page Macros, Prev: General ms Structure, Up: ms + +Document control registers +-------------------------- + + The following is a list of document control number registers. For +the sake of consistency, set registers related to margins at the +beginning of your document, or just after the `RP' macro. You can set +other registers later in your document, but you should keep them +together at the beginning to make them easy to find and edit as +necessary. + +Margin Settings +............... + + - Register: \n[PO] + Defines the page offset (i.e. the left margin). There is no + explicit right margin setting; the combination of the `PO' and + `LL' registers implicitly define the right margin width. + + Effective: next page. + + Default value: 1i. + + - Register: \n[LL] + Defines the line length (i.e. the width of the body text). + + Effective: next paragraph. + + Default: 6i. + + - Register: \n[LT] + Defines the title length (i.e. the header and footer width). This + is usually the same as `LL', but not necessarily. + + Effective: next paragraph. + + Default: 6i. + + - Register: \n[HM] + Defines the header margin height at the top of the page. + + Effective: next page. + + Default: 1i. + + - Register: \n[FM] + Defines the footer margin height at the bottom of the page. + + Effective: next page. + + Default: 1i. + +Text Settings +............. + + - Register: \n[PS] + Defines the point size of the body text. + + Effective: next paragraph. + + Default: 10p. + + - Register: \n[VS] + Defines the space between lines (line height plus leading). + + Effective: next paragraph. + + Default: 12p. + +Paragraph Settings +.................. + + - Register: \n[PI] + Defines the initial indent of a `.PP' paragraph. + + Effective: next paragraph. + + Default: 5n. + + - Register: \n[PD] + Defines the space between paragraphs. + + Effective: next paragraph. + + Default: 0.3v. + + - Register: \n[QI] + Defines the indent on both sides of a quoted (`.QP') paragraph. + + Effective: next paragraph. + + Default: 5n. + +Footnote Settings +................. + + - Register: \n[FL] + Defines the length of a footnote. + + Effective: next footnote. + + Default: `\n[LL]' * 5 / 6. + + - Register: \n[FI] + Defines the footnote indent. + + Effective: next footnote. + + Default: 2n. + + - Register: \n[FF] + The footnote format: + `0' + Prints the footnote number as a superscript; indents the + footnote (default). + + `1' + Prints the number followed by a period (like 1.) and indents + the footnote. + + `2' + Like 1, without an indent. + + `3' + Like 1, but prints the footnote number as a hanging paragraph. + + Effective: next footnote. + + Default: 0. + +Miscellaneous Number Registers +.............................. + + - Register: \n[MINGW] + Defines the minimum width between columns in a multi-column + document. + + Effective: next page. + + Default: 2n. + + +File: groff, Node: ms Cover Page Macros, Next: ms Body Text, Prev: ms Document Control Registers, Up: ms + +Cover page macros +----------------- + + Use the following macros to create a cover page for your document in +the order shown. + + - Macro: .RP [`no'] + Specifies the report format for your document. The report format + creates a separate cover page. The default action (no `.RP' + macro) is to print a subset of the cover page on page 1 of your + document. + + If you use the word `no' as an optional argument, `groff' prints a + title page but does not repeat any of the title page information + (title, author, abstract, etc.) on page 1 of the document. + + - Macro: .DA [...] + (optional) Print the current date, or the arguments to the macro + if any, on the title page (if specified) and in the footers. This + is the default for `nroff'. + + - Macro: .ND [...] + (optional) Print the current date, or the arguments to the macro + if any, on the title page (if specified) but not in the footers. + This is the default for `troff'. + + - Macro: .TL + Specifies the document title. `groff' collects text following the + `.TL' macro into the title, until reaching the author name or + abstract. + + - Macro: .AU + Specifies the author's name, which appears on the line (or lines) + immediately following. You can specify multiple authors as + follows: + + + .AU + John Doe + .AI + University of West Bumblefuzz + .AU + Martha Buck + .AI + Monolithic Corporation + + ... + + + - Macro: .AI + Specifies the author's institution. You can specify multiple + institutions in the same way that you specify multiple authors. + + - Macro: .AB [`no'] + Begins the abstract. The default is to print the word ABSTRACT, + centered and in italics, above the text of the abstract. The word + `no' as an optional argument suppresses this heading. + + - Macro: .AE + End the abstract. + + The following is example mark-up for a title page. + + + .RP + .TL + The Inevitability of Code Bloat + in Commercial and Free Software + .AU + J. Random Luser + .AI + University of West Bumblefuzz + .AB + This report examines the long-term growth + of the code bases in two large, popular software + packages; the free Emacs and the commercial + Microsoft Word. + While differences appear in the type or order + of features added, due to the different + methodologies used, the results are the same + in the end. + .PP + The free software approach is shown to be + superior in that while free software can + become as bloated as commercial offerings, + free software tends to have fewer serious + bugs and the added features are in line with + user demand. + .AE + + ... the rest of the paper follows ... + + +File: groff, Node: ms Body Text, Next: ms Page Layout, Prev: ms Cover Page Macros, Up: ms + +Body text +--------- + + This section describes macros used to mark up the body of your +document. Examples include paragraphs, sections, and other groups. + +* Menu: + +* Paragraphs in ms:: +* Headings in ms:: +* Highlighting in ms:: +* Lists in ms:: +* Indents in ms:: +* Tabstops in ms:: +* ms Displays and Keeps:: +* ms Insertions:: +* Example multi-page table:: +* ms Footnotes:: + + +File: groff, Node: Paragraphs in ms, Next: Headings in ms, Prev: ms Body Text, Up: ms Body Text + +Paragraphs +.......... + + The following paragraph types are available. + + - Macro: .PP + Sets a paragraph with an initial indent. + + - Macro: .LP + Sets a paragraph with no initial indent. + + - Macro: .QP + Sets a paragraph that is indented at both left and right margins. + The effect is identical to the HTML `<BLOCKQUOTE>' element. The + next paragraph or heading returns margins to normal. + + - Macro: .XP + Sets a paragraph whose lines are indented, except for the first + line. This is a Berkeley extension. + + The following markup uses all four paragraph macros. + + + .NH 2 + Cases used in the study + .LP + The following software and versions were + considered for this report. + .PP + For commercial software, we chose + .B "Microsoft Word for Windows" , + starting with version 1.0 through the + current version (Word 2000). + .PP + For free software, we chose + .B Emacs , + from its first appearance as a standalone + editor through the current version (v20). + See [Bloggs 2002] for details. + .QP + Franklin's Law applied to software: + software expands to outgrow both + RAM and disk space over time. + .LP + Bibliography: + .XP + Bloggs, Joseph R., + .I "Everyone's a Critic" , + Underground Press, March 2002. + A definitive work that answers all questions + and criticisms about the quality and usability of + free software. + + +File: groff, Node: Headings in ms, Next: Highlighting in ms, Prev: Paragraphs in ms, Up: ms Body Text + +Headings +........ + + Use headings to create a hierarchical structure for your document. +The `ms' macros print headings in *bold*, using the same font family +and point size as the body text. + + The following describes the heading macros: + + - Macro: .NH curr-level + - Macro: .NH S level0 ... + Numbered heading. The argument is either a numeric argument to + indicate the level of the heading, or the letter `S' followed by + numeric arguments to set the heading level explicitly. + + If you specify heading levels out of sequence, such as invoking + `.NH 3' after `.NH 1', `groff' prints a warning on standard error. + + - Macro: .SH + Unnumbered subheading. + + +File: groff, Node: Highlighting in ms, Next: Lists in ms, Prev: Headings in ms, Up: ms Body Text + +Highlighting +............ + + The `ms' macros provide a variety of methods to highlight or +emphasize text: + + - Macro: .B [txt [post [pre]]] + Sets its first argument in *bold type*. If you specify a second + argument, `groff' prints it in the previous font after the bold + text, with no intervening space (this allows you to set + punctuation after the highlighted text without highlighting the + punctuation). Similarly, it prints the third argument (if any) in + the previous font *before* the first argument. For example, + + + .B foo ) ( + + prints (*foo*). + + If you give this macro no arguments, `groff' prints all text + following in bold until the next highlighting, paragraph, or + heading macro. + + - Macro: .R [txt [post [pre]]] + Sets its first argument in roman (or regular) type. It operates + similarly to the `B' macro otherwise. + + - Macro: .I [txt [post [pre]]] + Sets its first argument in _italic type_. It operates similarly + to the `B' macro otherwise. + + - Macro: .CW [txt [post [pre]]] + Sets its first argument in a `constant width face'. It operates + similarly to the `B' macro otherwise. + + - Macro: .BI [txt [post [pre]]] + Sets its first argument in bold italic type. It operates + similarly to the `B' macro otherwise. + + - Macro: .BX [txt] + Prints its argument and draws a box around it. If you want to box + a string that contains spaces, use a digit-width space (`\0'). + + - Macro: .UL [txt [post]] + Prints its first argument with an underline. If you specify a + second argument, `groff' prints it in the previous font after the + underlined text, with no intervening space. + + - Macro: .LG + Prints all text following in larger type (two points larger than + the current point size) until the next font size, highlighting, + paragraph, or heading macro. You can specify this macro multiple + times to enlarge the point size as needed. + + - Macro: .SM + Prints all text following in smaller type (two points smaller than + the current point size) until the next type size, highlighting, + paragraph, or heading macro. You can specify this macro multiple + times to reduce the point size as needed. + + - Macro: .NL + Prints all text following in the normal point size (that is, the + value of the `PS' register). + + +File: groff, Node: Lists in ms, Next: Indents in ms, Prev: Highlighting in ms, Up: ms Body Text + +Lists +..... + + The `.IP' macro handles duties for all lists. + + - Macro: .IP [marker [width]] + The MARKER is usually a bullet glyph (`\[bu]') for unordered + lists, a number (or auto-incrementing number register) for + numbered lists, or a word or phrase for indented (glossary-style) + lists. + + The WIDTH specifies the indent for the body of each list item; its + default unit is `n'. Once specified, the indent remains the same + for all list items in the document until specified again. + + The following is an example of a bulleted list. + + + A bulleted list: + .IP \[bu] 2 + lawyers + .IP \[bu] + guns + .IP \[bu] + money + + Produces: + + + A bulleted list: + + o lawyers + + o guns + + o money + + + The following is an example of a numbered list. + + + .nr step 1 1 + A numbered list: + .IP \n[step] 3 + lawyers + .IP \n+[step] + guns + .IP \n+[step] + money + + Produces: + + + A numbered list: + + 1. lawyers + + 2. guns + + 3. money + + Note the use of the auto-incrementing number register in this +example. + + + The following is an example of a glossary-style list. + + + A glossary-style list: + .IP lawyers 0.4i + Two or more attorneys. + .IP guns + Firearms, preferably + large-caliber. + .IP money + Gotta pay for those + lawyers and guns! + + Produces: + + + A glossary-style list: + + lawyers + Two or more attorneys. + + guns Firearms, preferably large-caliber. + + money + Gotta pay for those lawyers and guns! + + In the last example, the `IP' macro places the definition on the +same line as the term if it has enough space; otherwise, it breaks to +the next line and starts the definition below the term. This may or +may not be the effect you want, especially if some of the definitions +break and some do not. The following examples show two possible ways +to force a break. + + The first workaround uses the `br' request to force a break after +printing the term or label. + + + A glossary-style list: + .IP lawyers 0.4i + Two or more attorneys. + .IP guns + .br + Firearms, preferably large-caliber. + .IP money + Gotta pay for those lawyers and guns! + + + The second workaround uses the `\p' escape to force the break. Note +the space following the escape; this is important. If you omit the +space, `groff' prints the first word on the same line as the term or +label (if it fits) *then* breaks the line. + + + A glossary-style list: + .IP lawyers 0.4i + Two or more attorneys. + .IP guns + \p Firearms, preferably large-caliber. + .IP money + Gotta pay for those lawyers and guns! + + + To set nested lists, use the `RS' and `RE' macros. *Note Indents in +ms::, for more information. + + For example: + + + .IP \[bu] 2 + Lawyers: + .RS + .IP \[bu] + Dewey, + .IP \[bu] + Cheatham, + .IP \[bu] + and Howe. + .RE + .IP \[bu] + Guns + + Produces: + + + o Lawyers: + + o Dewey, + + o Cheatham, + + o and Howe. + + o Guns + + +File: groff, Node: Indents in ms, Next: Tabstops in ms, Prev: Lists in ms, Up: ms Body Text + +Indents +....... + + In many situations, you may need to indent a section of text while +still wrapping and filling. *Note Lists in ms::, for an example of +nested lists. + + - Macro: .RS + - Macro: .RE + These macros begin and end an indented section. The `PI' register + controls the amount of indent, allowing the indented text to line + up under hanging and indented paragraphs. + + *Note ms Displays and Keeps::, for macros to indent and turn off +filling. + + +File: groff, Node: Tabstops in ms, Next: ms Displays and Keeps, Prev: Indents in ms, Up: ms Body Text + +Tab Stops +......... + + Use the `ta' request to define tab stops as needed. *Note Tabs and +Fields::. + + - Macro: .TA + Use this macro to reset the tab stops to the default for `ms' + (every 5n). You can redefine the `TA' macro to create a different + set of default tab stops. + + +File: groff, Node: ms Displays and Keeps, Next: ms Insertions, Prev: Tabstops in ms, Up: ms Body Text + +Displays and keeps +.................. + + Use displays to show text-based examples or figures (such as code +listings). + + Displays turn off filling, so lines of code are displayed as-is +without inserting `br' requests in between each line. Displays can be +"kept" on a single page, or allowed to break across pages. + + - Macro: .DS L + - Macro: .LD + - Macro: .DE + Left-justified display. The `.DS L' call generates a page break, + if necessary, to keep the entire display on one page. The `LD' + macro allows the display to break across pages. The `DE' macro + ends the display. + + - Macro: .DS I + - Macro: .ID + - Macro: .DE + Indents the display as defined by the `DI' register. The `.DS I' + call generates a page break, if necessary, to keep the entire + display on one page. The `ID' macro allows the display to break + across pages. The `DE' macro ends the display. + + - Macro: .DS B + - Macro: .BD + - Macro: .DE + Sets a block-centered display: the entire display is + left-justified, but indented so that the longest line in the + display is centered on the page. The `.DS B' call generates a + page break, if necessary, to keep the entire display on one page. + The `BD' macro allows the display to break across pages. The `DE' + macro ends the display. + + - Macro: .DS C + - Macro: .CD + - Macro: .DE + Sets a centered display: each line in the display is centered. + The `.DS C' call generates a page break, if necessary, to keep the + entire display on one page. The `CD' macro allows the display to + break across pages. The `DE' macro ends the display. + + - Macro: .DS R + - Macro: .RD + - Macro: .DE + Right-justifies each line in the display. The `.DS R' call + generates a page break, if necessary, to keep the entire display + on one page. The `RD' macro allows the display to break across + pages. The `DE' macro ends the display. + + + On occasion, you may want to "keep" other text together on a page. +For example, you may want to keep two paragraphs together, or a +paragraph that refers to a table (or list, or other item) immediately +following. The `ms' macros provide the `KS' and `KE' macros for this +purpose. + + - Macro: .KS + - Macro: .KE + The `KS' macro begins a block of text to be kept on a single page, + and the `KE' macro ends the block. + + - Macro: .KF + - Macro: .KE + Specifies a "floating keep"; if the keep cannot fit on the current + page, `groff' holds the contents of the keep and allows text + following the keep (in the source file) to fill in the remainder of + the current page. When the page breaks, whether by an explicit + `bp' request or by reaching the end of the page, `groff' prints + the floating keep at the top of the new page. This is useful for + printing large graphics or tables that do not need to appear + exactly where specified. + + You can also use the `ne' request to force a page break if there is +not enough vertical space remaining on the page. + + + Use the following macros to draw a box around a section of text +(such as a display). + + - Macro: .B1 + - Macro: .B2 + Marks the beginning and ending of text that is to have a box drawn + around it. The `B1' macro begins the box; the `B2' macro ends it. + Text in the box is automatically placed in a diversion (keep). + + +File: groff, Node: ms Insertions, Next: Example multi-page table, Prev: ms Displays and Keeps, Up: ms Body Text + +Tables, figures, equations, and references +.......................................... + + The `ms' macros support the standard `groff' preprocessors: `tbl', +`pic', `eqn', and `refer'. You mark text meant for preprocessors by +enclosing it in pairs of tags as follows. + + - Macro: .TS [`H'] + - Macro: .TE + Denotes a table, to be processed by the `tbl' preprocessor. The + optional argument `H' to `TS' instructs `groff' to create a + running header with the information up to the `TH' macro. `groff' + prints the header at the beginning of the table; if the table runs + onto another page, `groff' prints the header on the next page as + well. + + - Macro: .PS + - Macro: .PE + Denotes a graphic, to be processed by the `pic' preprocessor. You + can create a `pic' file by hand, using the AT&T `pic' manual + available on the Web as a reference, or by using a graphics + program such as `xfig'. + + - Macro: .EQ [align] + - Macro: .EN + Denotes an equation, to be processed by the `eqn' preprocessor. + The optional ALIGN argument can be `C', `L', or `I' to center (the + default), left-justify, or indent the equation. + + - Macro: .[ + - Macro: .] + Denotes a reference, to be processed by the `refer' preprocessor. + The GNU `refer(1)' man page provides a comprehensive reference to + the preprocessor and the format of the bibliographic database. + +* Menu: + +* Example multi-page table:: + + +File: groff, Node: Example multi-page table, Next: ms Footnotes, Prev: ms Insertions, Up: ms Body Text + +An example multi-page table +........................... + + The following is an example of how to set up a table that may print +across two or more pages. + + + .TS H + allbox expand; + cb | cb . + Text ...of heading... + _ + .TH + .T& + l | l . + ... the rest of the table follows... + .CW + .TE + + +File: groff, Node: ms Footnotes, Prev: Example multi-page table, Up: ms Body Text + +Footnotes +......... + + The `ms' macro package has a flexible footnote system. You can +specify either numbered footnotes or symbolic footnotes (that is, using +a marker such as a dagger symbol). + + - String: \*[*] + Specifies the location of a numbered footnote marker in the text. + + - Macro: .FS + - Macro: .FE + Specifies the text of the footnote. The default action is to + create a numbered footnote; you can create a symbolic footnote by + specifying a "mark" glyph (such as `\[dg]' for the dagger glyph) + in the body text and as an argument to the `FS' macro, followed by + the text of the footnote and the `FE' macro. + + You can control how `groff' prints footnote numbers by changing the +value of the `FF' register. *Note ms Document Control Registers::. + + +File: groff, Node: ms Page Layout, Next: Differences from AT&T ms, Prev: ms Body Text, Up: ms + +Page layout +----------- + + The default output from the `ms' macros provides a minimalist page +layout: it prints a single column, with the page number centered at the +top of each page. It prints no footers. + + You can change the layout by setting the proper number registers and +strings. + +* Menu: + +* ms Headers and Footers:: +* ms Margins:: +* ms Multiple Columns:: +* ms TOC:: +* ms Strings and Special Characters:: + + +File: groff, Node: ms Headers and Footers, Next: ms Margins, Prev: ms Page Layout, Up: ms Page Layout + +Headers and footers +................... + + For documents that do not distinguish between odd and even pages, +set the following strings: + + - String: \*[LH] + - String: \*[CH] + - String: \*[RH] + Sets the left, center, and right headers. + + - String: \*[LF] + - String: \*[CF] + - String: \*[RF] + Sets the left, center, and right footers. + + + For documents that need different information printed in the even +and odd pages, use the following macros: + + - Macro: .OH 'left'center'right' + - Macro: .EH 'left'center'right' + - Macro: .OF 'left'center'right' + - Macro: .EF 'left'center'right' + The `OH' and `EH' macros define headers for the odd and even pages; + the `OF' and `EF' macros define footers for the odd and even pages. + This is more flexible than defining the individual strings. + + You can replace the quote (`'') marks with any character not + appearing in the header or footer text. + + +File: groff, Node: ms Margins, Next: ms Multiple Columns, Prev: ms Headers and Footers, Up: ms Page Layout + +Margins +....... + + You control margins using a set of number registers. *Note ms +Document Control Registers::, for details. + + +File: groff, Node: ms Multiple Columns, Next: ms TOC, Prev: ms Margins, Up: ms Page Layout + +Multiple columns +................ + + The `ms' macros can set text in as many columns as will reasonably +fit on the page. The following macros are available; all of them force +a page break if a multi-column mode is already set. However, if the +current mode is single-column, starting a multi-column mode does *not* +force a page break. + + - Macro: .1C + Single-column mode. + + - Macro: .2C + Two-column mode. + + - Macro: .MC [width [gutter]] + Multi-column mode. If you specify no arguments, it is equivalent + to the `2C' macro. Otherwise, WIDTH is the width of each column + and GUTTER is the space between columns. The `MINGW' number + register controls the default gutter width. + + +File: groff, Node: ms TOC, Next: ms Strings and Special Characters, Prev: ms Multiple Columns, Up: ms Page Layout + +Creating a table of contents +............................ + + The facilities in the `ms' macro package for creating a table of +contents are semi-automated at best. Assuming that you want the table +of contents to consist of the document's headings, you need to repeat +those headings wrapped in `XS' and `XE' macros. + + - Macro: .XS [page] + - Macro: .XA [page] + - Macro: .XE + These macros define a table of contents or an individual entry in + the table of contents, depending on their use. The macros are + very simple; they cannot indent a heading based on its level. The + easiest way to work around this is to add tabs to the table of + contents string. The following is an example: + + + .NH 1 + Introduction + .XS + Introduction + .XE + .LP + ... + .CW + .NH 2 + Methodology + .XS + Methodology + .XE + .LP + ... + + You can manually create a table of contents by beginning with the + `XS' macro for the first entry, specifying the page number for + that entry as the argument to `XS'. Add subsequent entries using + the `XA' macro, specifying the page number for that entry as the + argument to `XA'. The following is an example: + + + .XS 1 + Introduction + .XA 2 + A Brief History of the Universe + .XA 729 + Details of Galactic Formation + ... + .XE + + + - Macro: .TC [`no'] + Prints the table of contents on a new page, setting the page + number to *i* (Roman numeral one). You should usually place this + macro at the end of the file, since `groff' is a single-pass + formatter and can only print what has been collected up to the + point that the `TC' macro appears. + + The optional argument `no' suppresses printing the title specified + by the string register `TOC'. + + - Macro: .PX [`no'] + Prints the table of contents on a new page, using the current page + numbering sequence. Use this macro to print a manually-generated + table of contents at the beginning of your document. + + The optional argument `no' suppresses printing the title specified + by the string register `TOC'. + + The `Groff and Friends HOWTO' includes a `sed' script that +automatically inserts `XS' and `XE' macro entries after each heading in +a document. + + Altering the `NH' macro to automatically build the table of contents +is perhaps initially more difficult, but would save a great deal of +time in the long run if you use `ms' regularly. + + +File: groff, Node: ms Strings and Special Characters, Prev: ms TOC, Up: ms Page Layout + +Strings and Special Characters +.............................. + + The `ms' macros provide the following predefined strings. You can +change the string definitions to help in creating documents in +languages other than English. + + - String: \*[REFERENCES] + Contains the string printed at the beginning of the references + (bibliography) page. The default is `References'. + + - String: \*[ABSTRACT] + Contains the string printed at the beginning of the abstract. The + default is `ABSTRACT'. + + - String: \*[TOC] + Contains the string printed at the beginning of the table of + contents. + + - String: \*[MONTH1] + - String: \*[MONTH2] + - String: \*[MONTH3] + - String: \*[MONTH4] + - String: \*[MONTH5] + - String: \*[MONTH6] + - String: \*[MONTH7] + - String: \*[MONTH8] + - String: \*[MONTH9] + - String: \*[MONTH10] + - String: \*[MONTH11] + - String: \*[MONTH12] + Prints the full name of the month in dates. The default is + `January', `February', etc. + + The following special characters are available(1) (*note ms Strings +and Special Characters-Footnote-1::): + + - String: \*[-] + Prints an em dash. + + - String: \*[*Q] + - String: \*[*U] + Prints typographer's quotes in troff, plain quotes in nroff. `*Q' + is the left quote and `*U' is the right quote. + + Improved accent marks are available in the `ms' macros. + + - Macro: .AM + Specify this macro at the beginning of your document to enable + extended accent marks and special characters. This is a Berkeley + extension. + + To use the accent marks, place them *after* the character being + accented. + + The following accent marks are available after invoking the `AM' +macro: + + - String: \*['] + Acute accent. + + - String: \*[`] + Grave accent. + + - String: \*[^] + Circumflex. + + - String: \*[,] + Cedilla. + + - String: \*[~] + Tilde. + + - String: \*[:] + Umlaut. + + - String: \*[v] + Hacek. + + - String: \*[_] + Macron (overbar). + + - String: \*[.] + Underdot. + + - String: \*[o] + Ring above. + + The following are standalone characters available after invoking the +`AM' macro: + + - String: \*[?] + Upside-down question mark. + + - String: \*[!] + Upside-down exclamation point. + + - String: \*[8] + German ss ligature. + + - String: \*[3] + Yogh. + + - String: \*[Th] + Uppercase thorn. + + - String: \*[th] + Lowercase thorn. + + - String: \*[D-] + Uppercase eth. + + - String: \*[d-] + Lowercase eth. + + - String: \*[q] + Hooked o. + + - String: \*[ae] + Lowercase ae ligature. + + - String: \*[Ae] + Uppercase AE ligature. + + +File: groff, Node: ms Strings and Special Characters-Footnotes, Up: ms Strings and Special Characters + + (1) For an explanation what special characters are see *Note Special +Characters::. + + +File: groff, Node: Differences from AT&T ms, Prev: ms Page Layout, Up: ms + +Differences from AT&T `ms' +-------------------------- + + This section lists the (minor) differences between the `groff -ms' +macros and AT&T `troff -ms' macros. + +* Menu: + +* Missing ms Macros:: +* Additional ms Macros:: + + +File: groff, Node: Missing ms Macros, Next: Additional ms Macros, Prev: Differences from AT&T ms, Up: Differences from AT&T ms + +`troff' macros not appearing in `groff' +....................................... + + Macros missing from `groff -ms' are cover page macros specific to +Bell Labs. The macros known to be missing are: + +`.TM' + Technical memorandum; a cover sheet style + +`.IM' + Internal memorandum; a cover sheet style + +`.MR' + Memo for record; a cover sheet style + +`.MF' + Memo for file; a cover sheet style + +`.EG' + Engineer's notes; a cover sheet style + +`.TR' + Computing Science Tech Report; a cover sheet style + +`.OK' + Other keywords + +`.CS' + Cover sheet information + +`.MH' + A cover sheet macro + + +File: groff, Node: Additional ms Macros, Prev: Missing ms Macros, Up: Differences from AT&T ms + +`groff' macros not appearing in AT&T `troff' +............................................ + + The `groff -ms' macros have a few minor extensions compared to the +AT&T `troff -ms' macros. + + - Macro: .AM + Improved accent marks. *Note ms Strings and Special Characters::, + for details. + + - Macro: .DS I + Indented display. The default behavior of AT&T `troff -ms' was to + indent; the `groff' default prints displays flush left with the + body text. + + - Macro: .CW + Print text in `constant width' (Courier) font. + + - Macro: .IX + Indexing term (printed on standard error). You can write a script + to capture and process an index generated in this manner. + + + The following additional number registers appear in `groff -ms': + + - Register: \n[MINGW] + Specifies a minimum space between columns (for multi-column + output); this takes the place of the `GW' register that was + documented but apparently not implemented in AT&T `troff'. + + + Several new string registers are available as well. You can change +these to handle (for example) the local language. *Note ms Strings and +Special Characters::, for details. + + +File: groff, Node: me, Next: mm, Prev: ms, Up: Macro Packages + +`me' +==== + + See the `meintro.me' and `meref.me' documents in groff's `doc' +directory. + + +File: groff, Node: mm, Prev: me, Up: Macro Packages + +`mm' +==== + + See the `groff_mm(7)' man page (type `man groff_mm' at the command +line). + + +File: groff, Node: gtroff Reference, Next: Preprocessors, Prev: Macro Packages, Up: Top + +`gtroff' Reference +****************** + + This chapter covers *all* of the facilities of `gtroff'. Users of +macro packages may skip it if not interested in details. + +* Menu: + +* Text:: +* Input Conventions:: +* Measurements:: +* Expressions:: +* Identifiers:: +* Embedded Commands:: +* Registers:: +* Manipulating Filling and Adjusting:: +* Manipulating Hyphenation:: +* Manipulating Spacing:: +* Tabs and Fields:: +* Character Translations:: +* Troff and Nroff Mode:: +* Line Layout:: +* Line Control:: +* Page Layout:: +* Page Control:: +* Fonts:: +* Sizes:: +* Strings:: +* Conditionals and Loops:: +* Writing Macros:: +* Page Motions:: +* Drawing Requests:: +* Traps:: +* Diversions:: +* Environments:: +* Suppressing output:: +* Colors:: +* I/O:: +* Postprocessor Access:: +* Miscellaneous:: +* Gtroff Internals:: +* Debugging:: +* Implementation Differences:: + + +File: groff, Node: Text, Next: Input Conventions, Prev: gtroff Reference, Up: gtroff Reference + +Text +==== + + `gtroff' input files contain text with control commands interspersed +throughout. But, even without control codes, `gtroff' still does +several things with the input text: + + * filling and adjusting + + * adding additional space after sentences + + * hyphenating + + * inserting implicit line breaks + +* Menu: + +* Filling and Adjusting:: +* Hyphenation:: +* Sentences:: +* Tab Stops:: +* Implicit Line Breaks:: + + +File: groff, Node: Filling and Adjusting, Next: Hyphenation, Prev: Text, Up: Text + +Filling and Adjusting +--------------------- + + When `gtroff' reads text, it collects words from the input and fits +as many of them together on one output line as it can. This is known as +"filling". + + Once `gtroff' has a "filled" line, it tries to "adjust" it. This +means it widens the spacing between words until the text reaches the +right margin (in the default adjustment mode). Extra spaces between +words are preserved, but spaces at the end of lines are ignored. +Spaces at the front of a line cause a "break" (breaks are explained in +*Note Implicit Line Breaks::). + + *Note Manipulating Filling and Adjusting::. + + +File: groff, Node: Hyphenation, Next: Sentences, Prev: Filling and Adjusting, Up: Text + +Hyphenation +----------- + + Since the odds are not great for finding a set of words, for every +output line, which fit nicely on a line without inserting excessive +amounts of space between words, `gtroff' hyphenates words so that it +can justify lines without inserting too much space between words. It +uses an internal hyphenation algorithm (a simplified version of the +algorithm used within TeX) to indicate which words can be hyphenated +and how to do so. When a word is hyphenated, the first part of the +word is added to the current filled line being output (with an attached +hyphen), and the other portion is added to the next line to be filled. + + *Note Manipulating Hyphenation::. + + +File: groff, Node: Sentences, Next: Tab Stops, Prev: Hyphenation, Up: Text + +Sentences +--------- + + Although it is often debated, some typesetting rules say there +should be different amounts of space after various punctuation marks. +For example, the `Chicago typsetting manual' says that a period at the +end of a sentence should have twice as much space following it as would +a comma or a period as part of an abbreviation. + + `gtroff' does this by flagging certain characters (normally `!', +`?', and `.') as "end-of-sentence" characters. When `gtroff' +encounters one of these characters at the end of a line, it appends a +normal space followed by a "sentence space" in the formatted output. +(This justifies one of the conventions mentioned in *Note Input +Conventions::.) + + In addition, the following characters and symbols are treated +transparently while handling end-of-sentence characters: `"', `'', `)', +`]', `*', `\[dg]', and `\[rq]'. + + See the `cflags' request in *Note Using Symbols::, for more details. + + To prevent the insertion of extra space after an end-of-sentence +character (at the end of a line), append `\&'. + |
