Generate Manual Pages from AsciiDoc

Manual page converter

Asciidoctor’s built-in man page converter generates roff-formatted manual pages from AsciiDoc documents.

manpage: The man page converter generates manual pages for software used on Unix and Unix-like operating systems. To use the man page converter, assign manpage to the backend option.

What is a manual page?

A manual page, often abbreviated to man page, is a form of software documentation found on Unix-based operating systems. The formalized structure of its content allows the man command to present the manual page as a formatted document in a terminal pager.

Generate a man page with the manpage converter

Before running Asciidoctor, make sure your source document adheres to the manpage doctype structure and the doctype attribute is assigned the value manpage.

To generate a man page, run:

$ asciidoctor -b manpage source.adoc

The manpage 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.

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. It also makes the document portable to other output formats since this style is only needed in the man page output to align with conventions.

If you’re using Ruby 2.4 or greater, Asciidoctor will uppercase any letter in the title that is recognized by the Unicode specification as having an uppercase equivalent (which includes non-Latin letters). Prior to Ruby 2.4, Ruby could only uppercase Latin letters.

Asciidoctor can also produce HTML and PDF versions similar to the manpage output for viewing in other contexts. To see the man page in HTML, run:

$ asciidoctor source.adoc

Here is an example man page composed in AsciiDoc for the eve command:

= 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.

Man page doctype

The manpage doctype has the following required parts:

Document Header: A manpage document header is mandatory. The title line contains the man page name followed immediately by the manual section number in round brackets. The title name should not contain white space. 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.
The SYNOPSIS Section: The second manpage section is mandatory and must be titled “SYNOPSIS”.

Subsequent sections are optional, but typical sections include “SEE ALSO”, “BUGS REPORTS”, “AUTHORS” and “COPYRIGHT”.

Man page attributes

Several built-in document attributes only affect man pages. These attributes must be set in the document header.

Built-in manpage document attributes
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 manpage output. A valid link format sequence.	blue R <>
`mansource`	The source to which the manpage 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.	1.5.4
`manmanual`	Manual name. When producing DocBook, it becomes a DocBook refmiscinfo attribute and appears in the footer.	Asciidoctor Manual

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