Generate Manual Pages from AsciiDoc

The AsciiDoc language defines a doctype named manpage for composing manual pages (man pages) in AsciiDoc. Asciidoctor provides a converter for converting this AsciiDoc structure into a roff-formatted man page.

This page introduces manual pages, examines the AsciiDoc structure of a man page, and shows how to convert an AsciiDoc document to roff-formatted man page and other formats using Asciidoctor.

What is a manual page?

A manual page, typically 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.

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.

manpage doctype

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

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

Document Header

In a man page, the document header is mandatory. The doctitle consists of the program name followed by the volume number in round brackets (e.g., progname(1)). The doctitle must not contain spaces. The volume number is a single digit optionally followed by a single character.

Document Attributes

There are several built-in document attributes that impact how the source is parsed and converted when the manpage doctype is in use. Refer to the Document attributes section.

The NAME Section

The first section is mandatory, must be titled “Name” (or “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 (e.g., progname - does stuff). The dash must have at least one space character on either side.

The SYNOPSIS Section

The second section is recommended and, if present, must be titled “Synopsis” (or “SYNOPSIS”).

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.

Since the structure required by the manpage doctype is standard AsciiDoc, you can opt to declare the manpage doctype at runtime. When the doctype attribute is not set, Asciidoctor will parse the document as an article and not give it any special treatment.

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

Example 1. progname.adoc
= eve(1)
Andrew Stanton
v1.0.0
:doctype: manpage
:manmanual: EVE
:mansource: EVE
:man-linkstyle: pass:[blue R < >]

== Name

eve - analyzes an image to determine if it's a picture of a life form

== Synopsis

*eve* [_OPTION_]... _FILE_...

== Options

*-o, --out-file*=_OUT_FILE_::
  Write result to file _OUT_FILE_.

*-c, --capture*::
  Capture specimen if it's a picture of a life form.

== Exit status

*0*::
  Success.
  Image is a picture of a life form.

*1*::
  Failure.
  Image is not a picture of a life form.

== Resources

*Project web site:* https://eve.example.org

== Copying

Copyright (C) 2008 {author}. +
Free use of this software is granted under the terms of the MIT License.

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.

manpage backend and converter

Asciidoctor provides a built-in converter to generate roff-formatted man pages for AsciiDoc documents that declare and conform to the manpage doctype. This converter is bound to the manpage backend (not to be confused with the manpage doctype). Notice the absense of the space in the backend value.

The man page converter is typically used to generate man pages that accompany software on Unix-like operating systems. In fact, Asciidoctor’s own man page (i.e., man asciidoctor) is generated in this way from this AsciiDoc source.

To use the man page converter, assign manpage to the backend option. The man page converter sets the output file name to progname.1, where progname is the name of the command and 1 is the volume number, as defined by the doctitle of the source document (e.g., progname(1)).

Generate a man page

Before running Asciidoctor, make sure your source document conforms to the manpage doctype structure and the doctype attribute is set and has the value manpage.

To generate a man page, run:

$ asciidoctor -b manpage progname.adoc

When converting to the man page format, Asciidoctor uppercases the titles of all level-0 and level-1 sections. This 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 used for the man page output to align with conventions. If the titles are uppercased in the source, that casing ends up getting used in all output formats.

Prior to Ruby 2.4, Ruby could only uppercase Latin letters. If you’re using Ruby 2.4 or greater, Asciidoctor will uppercase any letter in the title that’s recognized by the Unicode specification as having an uppercase equivalent, which extends beyond Latin letters.

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.

$ asciidoctor progname.adoc

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

Convert the man page to PostScript / PDF

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:

$ man -t ./progname.1 > progname.ps

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

$ man -t ./progname.1 | ps2pdf - progname.pdf

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

$ man -t ./eve.1 | ps2pdf - eve.pdf

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

$ asciidoctor -h manpage | man -t -l - | ps2pdf - asciidoctor.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.

Document attributes

Several built-in document attributes only affect the manpage doctype and output. These attributes must be set in the document header.

Built-in document attributes for man pages
Attribute Description Value (as parsed from example above)

mantitle

Alternative way to set the man page name.

ASCIIDOCTOR(1)

manvolnum

Manual section number.

1

manname

Alternative way to set the command name.

asciidoctor

manpurpose

Alternative way to set the command purpose.

converts AsciiDoc source files

man-linkstyle

Style the links in the man page output. A valid link format sequence.

blue R < >

mansource

The source to which the man page pertains. When producing DocBook, it becomes a DocBook refmiscinfo attribute and appears in the footer.

Asciidoctor

manversion

The version of the man page. Defaults to revnumber if not specified. When producing DocBook, it becomes a DocBook refmiscinfo attribute and appears in the footer. Not used by Asciidoctor.

2.0.16

manmanual

Manual name. When producing DocBook, it becomes a DocBook refmiscinfo attribute and appears in the footer.

Asciidoctor Manual

See also

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.