Convert AsciiDoc to Man Pages

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

What is a man 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 man 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 has the doctype attribute set to 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:* http://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 document attributes specific to the manpage doctype
Attribute name 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 man page for Asciidoctor is produced using the manpage converter. The man pages for git are also produced from AsciiDoc documents, so you can use those as another example to follow.