AsciiDoc User Guide

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.

Viewing and printing manpage files

Use the man(1) command to view the manpage file (you must include a file path even if it's only

./ otherwise man(1) will look for the file in the system manpage locations):

$ man ./asciidoc.1

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

$ groff -mandoc -Tps asciidoc.1 | lpr

To find out more about man pages view the man(7) manpage (man 7 man command).

Document Header

A 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 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

The SYNOPSIS Section

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

Configuration Files

AsciiDoc source file syntax and output file markup is largely controlled by a set of cascading, text based, configuration files. At runtime The AsciiDoc default configuration files are combined with optional user and document specific configuration files.

Configuration File Format

Configuration files contain named sections. Each section begins with a section name in square brackets []. The section body consists of the lines of text between adjacent section headings.

46