Generate Manual Pages from AsciiDoc

A manual page, abbreviated as man page, is a form of software documentation that typically accompanies software on Unix-like operating systems. Its formalized structure allows the man command to present the man page as a formatted document in a terminal pager, such as less.

The benefit of composing a man page in AsciiDoc is that you can convert it to multiple formats, including HTML and PDF. That makes the source of the man page reusable.

The manpage doctype declares that the AsciiDoc structure serves as the source of a man page and conforms to the man page structure. Note the absence of the space in the doctype value.

By declaring the manpage doctype, the AsciiDoc processor expects the document to conform to the following structure.

Subsequent sections are optional, but typical sections include “Description”, “Options”, “Bugs”, “See Also”, “Copyright”, and “Author”. You can write the section titles in all uppercase, but it’s better to let the man page converter handle that for you. See Generate a man page for details.

Here’s an example man page composed in AsciiDoc for the eve command. Observe that it declares the manpage doctype and conforms to the described structure.

Although the source document is named progname.adoc, you can name the file whatever you like. The output filename is determined by the manname and manvolnum attributes implicitly defined by the doctitle. In this example, the output filename is eve.1.

Asciidoctor provides a built-in converter to generate groff-formatted man pages for AsciiDoc documents that declare the manpage doctype and conform to it. Asciidoctor’s own man page (i.e., man asciidoctor) is generated using this converter from this AsciiDoc source.

The man page converter is bound to the manpage backend (not to be confused with the manpage doctype). Note the absence of the space in the backend value.

First, ensure your source document conforms to the manpage doctype structure and the doctype attribute is set to the value manpage. Then, to activate the man page converter, you must assign manpage to the backend option. Doing so will instruct the processor to use the man page converter to convert the document.

For the purpose of this example, we’ll assue that the doctitle in progname.adoc is progname(1), where progname is the name of the command and 1 is the volume number. Based on this information, the man page converter will set the output file name to progname.1.

To generate a man page, run:

You can then view the resulting man page using the man command:

When converting to the man page format, Asciidoctor uppercases the titles of all level-0 and level-1 sections. This transformation is applied to conform to the widely adopted convention used by most man pages found on *nix systems. By applying this transform in the converter, it saves you from having to type section titles in all uppercase in the source document. It also makes the document portable to other output formats since this style is only needed for the man page output. If the titles are uppercased in the source, that casing ends up getting used in all output formats.

Recall that you’re not limited to using the man page converter to convert an AsciiDoc document that uses the manpage doctype. You can just as well convert it to HTML, as shown here.

The structure of the source document is still enforced, but the output document will look like the output of any other AsciiDoc document.

You may have a man page that you want to repurpose for documenting equivalent commands (but not aliases). You can do so by supplying an alternate man title, name, and/or purpose when converting the document.

If you want to change mantitle and manvolnum attributes, you must override the doctitle attribute when invoking Asciidoctor.

This command sets the mantitle to “othername”, the manvolnum to “7”, and generates the file progname.7. However, the mantitle is only used in the hidden info section at the top of the man page. What you probably want to do is change the manname too, which is the name used in the header, the Name section, and the output filename.

One way to change the manname is to set both the manname and manpurpose attributes when calling Asciidoctor. But first, you need to hide the default Name section in this case so you don’t end up with two Name sections.

Now, you can replace the information in the Name section when calling Asciidoctor:

This command generates the file othername.7.

If you only want to override the manname attribute and not the manpurpose attribute, reconfigure the Name section as shown in the next example.

Now, you can override the manname attribute without having to override the manpurpose attribute.

It’s important to remember that Asciidoctor derives the manname and manpurpose attributes from the Name section by default. That’s why it’s not enough just to override the attributes when calling Asciidoctor.

However, if you want to make a well-formed man page from a document that doesn’t have a Name section, you can effectively insert one by setting the manname and manpurpose attributes from the CLI:

You can now view the README as a man page using the man command:

Just remember that a well-formed man page requires both a name and a purpose.

Once you have created a man page, you can convert it to PostScript using the man command.

Let’s assume that the output file produced by the Asciidoctor man page converter is progname.1, where progname is the name of the command and 1 is the volume number. You can convert progname.1 to PostScript and redirect the output to progname.ps using the following man command:

Alternately, you can redirect the output of the man command to ps2pdf to further convert it to PDF:

Let’s now convert the example from earlier to PDF in this way:

Using the same sequence of commands, you can convert Asciidoctor’s own man page to PDF:

In this case, the -l - reads the man page content generated by the help mode of the asciidoctor command.

Keep in mind that the files in this section are not generated using Asciidoctor. If you want to generate PDF files directly from Asciidoctor, you may be interested in checking out Asciidoctor PDF. Another approach is to convert the AsciiDoc document to DocBook using the built-in DocBook converter (e.g., -b docbook), then convert that document to PDF using the DocBook toolchain.

Several built-in document attributes only affect the manpage doctype and output. These attributes (or the attributes from which they are derived) must be set in the document header.

Refer to the AsciiDoc source of the Asciidoctor man page to see a complete example. The man page for Asciidoctor is produced using the man page converter. The man pages for git are also produced from AsciiDoc documents, so you can use those as another example to follow.