Chapter 24. Manpage Documents

Sooner or later, if you program in a UNIX environment, you’re going to have to write a man page.

By observing a couple of additional conventions (detailed below) you can write AsciiDoc files that will generate HTML and PDF man pages plus the native manpage roff format. The easiest way to generate roff manpages from AsciiDoc source is to use the a2x(1) command. The following example generates a roff formatted manpage file called asciidoc.1 (a2x(1) uses asciidoc(1) to convert asciidoc.1.txt to DocBook which it then converts to roff using DocBook XSL Stylesheets):

a2x --doctype manpage --format manpage asciidoc.1.txt

Viewing and printing manpage files

Use the man(1) command to view the manpage file:

$ man -l asciidoc.1

To print a high quality man page to a postscript printer:

$ man -l -Tps asciidoc.1 | lpr

You could also create a PDF version of the man page by converting PostScript to PDF using ps2pdf(1):

$ man -l -Tps asciidoc.1 | ps2pdf - asciidoc.1.pdf

The ps2pdf(1) command is included in the Ghostscript distribution.

To find out more about man pages view the man(7) manpage (man 7 man and man man-pages commands).

24.1. Document Header

A manpage document Header is mandatory. The title line contains the man page name followed immediately by the manual section number in brackets, for example ASCIIDOC(1). The title name should not contain white space and the manual section number is a single digit optionally followed by a single character.

24.2. The NAME Section

The first manpage section is mandatory, must be titled NAME and must contain a single paragraph (usually a single line) consisting of a list of one or more comma separated command name(s) separated from the command purpose by a dash character. The dash must have at least one white space character on either side. For example:

printf, fprintf, sprintf - print formatted output

24.3. The SYNOPSIS Section

The second manpage section is mandatory and must be titled SYNOPSIS.

24.4. refmiscinfo attributes

In addition to the automatically created man page intrinsic attributes you can assign DocBook refmiscinfo element source, version and manual values using AsciiDoc {mansource}, {manversion} and {manmanual} attributes respectively. This example is from the AsciiDoc header of a man page source file:

:man source:   AsciiDoc
:man version:  {revnumber}
:man manual:   AsciiDoc Manual