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 you can compose AsciiDoc files that will generate DocBook refentry (man page) documents. The resulting DocBook file can then be translated to the native roff man page format (or other formats).
For example, the asciidoc.1.txt file in the AsciiDoc distribution
./doc directory was used to generate both the
asciidoc.1.css-embedded.html HTML file the asciidoc.1 roff
formatted asciidoc(1) man page.
To find out more about man pages view the man(7) manpage
(man 7 man and man man-pages commands).
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.
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
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