Man pages

about_man.md

Creating your own manual (MAN) page

UNIX systems tools are typically accompanied by a man page. These provide a brief description of the command, it's optional parameters and modes, and any other related information that may be of use to the user.

Formatting Customs

• Almost all Unix MAN pages use the section numbering: (1) NAME, (2) SYNOPSIS, (3) DESCRIPTION, (4) FILES - files the command might use to do work, (5) SEE ALSO, (6) NOTES, (7) AUTHOR, (8) BUGS, with extra and optional sections as needed.
• You normally have an initial line: Foo /- Does foo things with this dash that gives a short description. This allows the man-page to be added to the 'whatis' database used by man -k and apropos commands, if applicable.
• Boldface is typically used to denote program and filenames

Basic commands

1. \fB : Change font to boldface
2. \fI : Change font to italics
3. \fR : Change font to roman type
4. \fP : Set font to previous selection
5. .TH FOO 1 "2023-02-24" : Set the title of the page to "foo" with the date, and use section 1 for user-commands (section 2 is system calls, etc.)
6. .SH "Bar" : Start a section called "Bar"
7. .TP Creates a tag. The line following is the tag, and the one thereafter the tag description or text. Use this for options to the program
8. .br : Cause a break to force following text to appear on next line. Good for splitting long titles.
9. .ce : Center the next line
10. .sN : Make the text N point size. Return to default with .s0.

Special characters

1. \(*a : 'a' for alpha symbol, 'b' for beta, 'c' for squiggly thing, 'p' for pi. etc
2. \(em : em dash
3. \(bu : bullet symbol
4. \(dg : dagger symbol

In general, troff/groff uses the backslash symbol to introduce a command, with the most common being f for font and s for point size.

Building and viewing a manual page

Build as follows:

groff -Tascii -man <name>.man | more

The option -man tells groff to build a manual page using the man macro, and -Tascii to produce plain ASCII output. Other options might be:

• -Tps: Produce postscript which you can save to a file, and view or print.
• -Tdvi will produce device-independent .dvi output similar to Tex

Installing manual pages

Depends on your system, but you can just copy manual.man (assuming that's your new manual file to install to:

1. macOS: In /usr/local/share you can find different subdirectories depending on what kind of manual you're providing (man1,man2,man3,...). Place your document into that directory with the format: <name-of-utility>.N where N is the manual number entry for your manual.

If you can't edit the manpage directory, update the MANPATH variable in your profile to include a local man-page directory. In my case, I updated ~/.zshrc with export MANPATH=$PATH:/Users/$USER/doc/man.

Example

.TH COFFEE 1 "24 Feb 2023"
.ce
\s14The coffee command line utility\s0
.SH NAME
coffee /- Control remote coffee machine
.SH SYNOPSIS
\fBcoffee\fP [ -h | -b ] [ -t \fItype\fP ]
\fIamount\fP
.SH DESCRIPTION
\fBcoffee\fP queues a request to the remote coffee machine at the device \fB/dev/cf0\fR.
The required \fIamount\fP arugment specifies the number of cups, generally between 0 and 12 on ISO standard coffee machines.
.SS Options
.TP
\fB-h\fP
Brew hot coffee. Cold is the default.
.TP
\fB-h\fP
Burn coffee. Especially useful when executing \fBcoffee\fP on behalf of your boss.
.TP
\fB-t \fItype\fR
Specify the type of coffee to brew, where \fItype\fP is one of \fBcolumbian\fP, \fBregular\fP, or \fBdecaf\fP.
.SH FILES
.TP
\fC/dev/cf0\fR
\(bu The remote coffee machine device
.SH "SEE ALSO"
milk(5), sugar(5)
.SH BUGS
May require human intervention if coffee supply is exhausted

.DS
expr:    | number
         | variable
         | ( expr )
         | expr binop expr
         | unop expr
         | function ( arguments )
.DE