& - troff

A “man-page” is a piece of on-line documentation for Unix programs. Normally every program available on the command line has one, and it is accessed by typing man followed by the program name. If we want to read the page for the bash shell, we enter:

man bash

Below are five practical topics connected with man-pages.

1. Navigation and searching within a man-page

Man-pages are displayed in the terminal by way of a “pager”, usually a program such as less that has search and other navigation functionality. The most immediately useful commands in less are

navigation:

q : quit
u : page up
d : page down
g : to top of document
G : to bottom of document

searching:

/ : incremental forward-search
? : incremental backward-search
n : find next in the original direction
N : find next in the opposite direction

2. Dealing with multiple pages for the same program

By default man returns only the first page it finds with a given name; you can open all that are found, in sequence, using the -a option. But I prefer first to get a listing of all pages found, by location in the file-system, and then choose the one or ones I want.

Not all man-pages are found in the same place; the location of a given page can be requested using option -w (mnemonic as “where”; equivalent to --path). Combine -w and -a to return the locations of all pages with a given name:

$ man -aw groff
/usr/share/man/man1/groff.1
/usr/share/man/man7/groff.7

The numbers at the end of these filenames are the “section” numbers in the overall man-page collection. The manual sections mostly likely to be used by ordinary programmers are 1 (executable shell commands) and 7 (miscellaneous). You can specify which sections you want with the -S option, followed by one or more (colon-separated) section numbers. So on (Ubuntu and Darwin, at least) either of the following

man groff -S 1
man -S 1 groff

will bring up the first of the files listed above, labelled GROFF(1), while

man groff -S 7
man -S 7 groff

will bring up GROFF(7).

3. Searching for relevant man-pages

Option -k (or --apropos) will search the one-line descriptions in the NAME section of all man-pages for some string. The output is the same as that of the apropos command:

$ man -k markdown
pandoc_markdown(5)       - markdown syntax for pandoc(1)

Option -K will search the full content of all man-pages for a given string, always giving you the option of opening each page, as found, or quitting before continuing the search. Below is an example of searching for pages containing “markdown” — the letter n at the end of each line is my response to the program’s request as to how to proceed:

$ man -K markdown
/usr/local/share/man/man1/pandoc-citeproc.1? [ynq] n
/usr/local/share/man/man1/pandoc.1? [ynq] n
/usr/local/share/man/man5/pandoc_markdown.5? [ynq] n

This can be a long procedure (any pages compressed with gzip are being decompressed and searched) so it is useful to restrict the search domain to some subset of sections, using option -S. Also, be aware that if spacing within a desired phrase varies in different man-pages, or if it is hyphenated or spread over more than one line, not all the desired output may actually be found.

4. The internal format of a man-page

Man-pages are natively formatted using roff, a kind of markup dating from the 1960s and modelled on linotype practices. There is a résumé of the history of this protocol in the man-page for roff, whose name is a reduction of the name of an older program, runoff; runoff itself comes from the ordinary English “run off”, to reproduce a document mechanically.

The roff family of programs (mainly troff [“typesetter roff”], nroff [“new roff”] and groff [“GNU roff”]) rely on a pipeline of preprocessor, formatter, post-processor, and an output “device” or “target”. The markup protocol itself is well documented, though it may not be of much interest to the casual user. Its two most distinctive features are

“requests”, prefixed by . and occupying a full line; generally having higher-level functionality;
“commands”, prefixed by \; generally producing or affecting sequences of characters.

These give it a fairly archaic look by contemporary standards of markup. Here are a few lines from the bash.1 man-page:

...

.SH DESCRIPTION
.B Bash
is an \fBsh\fR-compatible command language interpreter that
executes commands read from the standard input or from a file.
.B Bash
also incorporates useful features from the \fIKorn\fP and \fIC\fP
shells (\fBksh\fP and \fBcsh\fP).
.PP

...

.PD 0
.TP 10
.BI \-c "\| string\^"
If the
.B \-c
option is present, then commands are read from
.IR string .
If there are arguments after the
.IR string ,
they are assigned to the positional parameters, starting with
.BR $0 .
.TP

...

See the groff_diff man-page for a comprehensive discussion of the rules.

5. Accessing man-pages outside of the terminal window

A man-page is normally read within the terminal window where it is displayed by man. But there are other options.

5a. As text files

Formatting by man for stdout is hard to read when not processed by a terminal device interface. Exporting directly to a text file, say using the man-page for bash itself, as

man bash > bash_man_page.txt

produces messiness wherever boldface and other character-formatting is in use. Instead, pipe man output through the col or colcrt programs, the former with option -b (“eliminate backspacing”):

man bash | col -b > bash_man_page.txt

man bash | colcrt > bash_man_page.txt

(The name col appears to derive from “column”, but the program has functionality not limited to columnization and the name perhaps condenses “correct output lines”; its man-page declares its function to be “filter reverse line feeds from input.” The name colcrt is a variety of col originally intended for use with CRT terminals. The two programs produce slightly different output: col uses tabs, while colcrt uses only spaces.)

5b. As PostScript

A man-page can also be converted to PostScript and read with any PS-reader — most PDF readers will read PostScript without trouble. Use

man -t bash > bash_man_page.ps

Option -t runs groff -Tps -mandoc, meaning take the output “target” to be PostScript and then use a macro package appropriate to whichever man-page format is found. Program man itself outputs to stdout by default; you can pipe that output to your PS-reader. On the current Mac operating system (Darwin v. 13.4) the full command would be

man -t bash | open -fa /Applications/Preview.app

although Ghostscript, gv, Acrobat Reader, and many other tools are also available as the direct objects of open. There is another program pdfroff for converting man-pages to PDF, but I have not been able to get the output to look right and simply use PostScript pages, instead.

5c. As HTML

There is a program man2html that generates HTML easily from man-pages:

man bash | man2html > bash_man_page.html

[end]

Comments are enabled.