path: root/contrib/groff/doc/groff-2

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 `\&'.