man.macros(7)

NAME
man.macros - quick reference guide for the -mman macro package

SYNOPSIS
groff -mman file(s) ...

DESCRIPTION
The -mman macro set is set of macros which assist with the creation of man pages.

OVERVIEW
The -mman macro package can be invoked by passing -mman, -man, or -mandoc as an argument to nroff/troff/groff.

The -mman macro package has the following macros:

.TH Title of man page

.SH Section heading

.SS Sub-section heading

.B  Bold

.I  Italics

.SM Smaller (9/10 normal size) text

.SB Smaller bold text

.BI Bold and Italics alternating

.BR Bold and Roman (normal text) alternating

.IB Italics and Bold alternating

.IR Italics and Roman alternating

.RB Roman and Bold alternating

.RI Roman and Italics alternating

.TP List element (on same line as description)

.IP List element (on line before description)

.LP End list

.PP Alias for .LP

.P  Another alias for .LP

.RS Shift text over to the right

.RE Shift text (one level of nesting) back

.HP One unshifted line followed by shifted lines

.DT Set tab stops every .5 inches

USAGE

  Title, sections, and sub sections

The following macros process the title of the man page, the names of sections, and the names of sub-sections:

.TH name number Date Program Section
    Name is the name of the man page, number is the section number, date is the date the man page was written, Program is the name of the program, and section (optional) is the "Section" this manual page falls under.

    Example:

    The .TH for this manual page is as follows:

     .TH man.macros 7 "October 2001" MAN.MACROS "Linux reference manual"

    TH needs to be the first uncommented line in the man page. Due to a bug in groff's -mandoc macro, formatting commands (no hyphenation, etc.) should be placed after the initial .TH.

Section heading
     .SH "Name of section"

    SH is a section heading, where "Name of section" is the name of the section in question.

Sub-section heading
     .SS "Name of subsection"

    SS is a sub-section heading, where "Name of subsection" is the name of the sub-section in question.

  Font changes

The text that one wishes to have rendered in a different font is placed on the same line as the macro, like this:

 .B This is some bold text

The -mman macros which perform temporarily font changes are .B, .I, .BI, .BR, .IB, .IR, .RB, .RI, .SM, and .SB. These macros are described in the proceeding overview section.

  Lists

The first kind of list is a list where the name of the list item is small enough to fit on the same line as the description of the list item, as follows:

 .TP #
 Name of item
 Description of item
 .PP

Starts this type of list. The # shown above is the number of characters (points with troff) we use for the name of the item. The data is formatted like this:

Name
    Description. If the description is long enough that we need to wrap a line, we do so, as one can see in this example.

    In addition, the description can be longer than one paragraph long

We terminate the description with either a .PP macro, or by having another .TP macro

This example shows how to use .TP to make a bulleted list:

 .TP 2
 *
 This is item one in the list.
 .TP
 *
 This is item two
 .TP
 *
 And so on
 .PP
 Until we finish the list.

Which renders as follows:

---

*   This is item one in the list.

*   This is item two

*   And so on

Until we finish the list.

---

By default, subsequent .TPs will use the same size for the name as the last .TP which defined the item size

In cases where list item names are long enough that the name and the description can not fit on the same line, the format is as follows:

 .IP "Name of item" #
 Description of item, which is shifted over by # characters
 .IP "Another name"
 Another description.  Since # was not specified, we use the previous
 definition of #
 .PP
 End of list

Example:

 .IP "Name of item" 2
 Description of item, shifted over two characters
 .IP "Another name"
 Another description
 .PP
 End of list

Which renders as follows:

---

Name of item
    Description of item, shifted over two characters

Another name
    Another description

End of list

---

  Shifting

 .RS and .RE allow for nested shifts

Example:

 Unshifted
 .RS 5
 Shifted over five characters (or points)
 .RS 2
 And over two move
 .RE
 back again
 .RE
 and back to the top

Which renders as:

---

Unshifted
    Shifted over five characters (or points)
        And over two move
    back again
and back to the top

---

The .HP macro has one line of text which is at the standard margin for a man page. All subsequent lines are indented over by the amount given as an argument to .HP until a .LP, .PP, or .P macro.

Example:

 .HP 2
 HP # has unshifted text, for one line, then shifts all subsequent
 lines so that they are shifted to the right # characters (or points).
 This is an example of a lot of text which shows what HP does.
 .PP

Renders as:

---

HP # has unshifted text, for one line, then shifts all subsequent lines so that they are shifted to the right # characters (or points). This is an example of a lot of text which shows what HP does.

---

USEFUL *ROFF COMMANDS
While a full description of all of the raw nroff/troff/groff commands available is beyond the scope of this document, follows is a quick overview of some of the more useful *roff commands.

Comments
    Comments (lines not visible in the rendered man page) are available by starting a line with .\". For example:

     .\" This is a comment

Unformatted text
    The .nf tag passes all subsequent text unformatted until a .fi tag.

    When a man page is rendered with troff or groff instead of nroff, the \fC tag changes the font to a fixed-width font, and the \f(TR tag changes the font back to a proportional font.

    Example:

     .nf
     \fC
     This is some text
     which we want to
     preserve the form of
     (ASCII art, simple tables, etc.)
     \f(TR
     .fi

    Renders as:

    ---

    This is some text
    which we want to
    preserve the form of
    (ASCII art, simple tables, etc.)

    ---

SEE ALSO

The groff_man(7) manual page is one reference on the -mman macros. A more detailed reference is available with the man(7) manual page.

The Linux Man Page HOWTO is a tutorial which describes how to make man pages with the -mman set of macros, and has pointers to the troff documentation.

The -mdoc macro set is another set of macros which assist in the creation of man pages. For information on how to use the -mdoc macros, read the mdoc(7) and the mdoc.samples(7) man pages.

AUTHOR
Sam Trenholme http://www.samiam.org/