You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
110 lines
4.5 KiB
110 lines
4.5 KiB
4 years ago
|
////
|
||
|
|
Included in:
|
||
|
|
|
||
|
|
- user-manual: Man pages
|
||
|
|
////
|
||
|
|
|
||
|
|
One of the more specialized uses of AsciiDoc is to serve as a shorthand for generating man pages (short for manual pages) for Unix and Unix-like operating systems.
|
||
|
|
|
||
|
|
A man page is coded in the roff typesetting language.
|
||
|
|
By adhering to a specific structure in the man page file, the `man` command can parse the content and present a formatted document in a textual (command line) pager.
|
||
|
|
Manual pages provide a unified help catalog for all commands in the system.
|
||
|
|
For a full description, see the http://man7.org/linux/man-pages/man7/roff.7.html[roff man page] (or type `man roff` or `man 7 man`).
|
||
|
|
|
||
|
|
{adr} can produce roff-formatted man pages if the structure of the AsciiDoc document adheres to the manpage doctype structure (described later in this section).
|
||
|
|
|
||
|
|
To produce a roff-formatted man page from an AsciiDoc file that declares the manpage doctype, run:
|
||
|
|
|
||
|
|
$ asciidoctor -b manpage source.adoc
|
||
|
|
|
||
|
|
Note that 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.
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
CAUTION: If you're use Ruby 2.4 or better, 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.
|
||
|
|
|
||
|
|
{adr} can also produce HTML and PDF versions similar to the `man` output for viewing in other contexts.
|
||
|
|
To see the man page in HTML instead, run:
|
||
|
|
|
||
|
|
$ asciidoctor source.adoc
|
||
|
|
|
||
|
|
Here is an example man page composed in AsciiDoc for the `eve` command:
|
||
|
|
|
||
|
|
[source]
|
||
|
|
----
|
||
|
|
include::ex-manpage.adoc[]
|
||
|
|
----
|
||
|
|
|
||
|
|
The manpage doctype has the following required parts:
|
||
|
|
|
||
|
|
Document Header::
|
||
|
|
A man page 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 man page 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 man page section is mandatory and must be titled "`SYNOPSIS`".
|
||
|
|
|
||
|
|
Subsequent sections are optional, but typical sections include "`SEE ALSO`", "`BUGS REPORTS`", "`AUTHORS`" and "`COPYRIGHT`".
|
||
|
|
|
||
|
|
There are several built-in document attributes that affect only man pages.
|
||
|
|
If used, they must be set in the document header.
|
||
|
|
|
||
|
|
[cols="<15,<30,<30"]
|
||
|
|
.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.
|
||
|
|
// Needs a reference to this.
|
||
|
|
|blue R <>
|
||
|
|
|
||
|
|
|mansource
|
||
|
|
|The source to which the man page pertains.
|
||
|
|
When producing DocBook, it becomes a DocBook https://tdg.docbook.org/tdg/5.0/refmiscinfo.html[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 https://tdg.docbook.org/tdg/5.0/refmiscinfo.html[refmiscinfo] attribute and appears in the footer.
|
||
|
|
Not used by Asciidoctor.
|
||
|
|
|1.5.4
|
||
|
|
|
||
|
|
|manmanual
|
||
|
|
|Manual name.
|
||
|
|
When producing DocBook, it becomes a DocBook https://tdg.docbook.org/tdg/5.0/refmiscinfo.html[refmiscinfo] attribute and appears in the footer.
|
||
|
|
|Asciidoctor Manual
|
||
|
|
|===
|
||
|
|
|
||
|
|
Refer to {man-raw}[the AsciiDoc source of the Asciidoctor man page] to see a complete example.
|
||
|
|
The man page for Asciidoctor is produced using the built-in man page converter in Asciidoctor.
|
||
|
|
The man pages for git are also produced from AsciiDoc documents, so you can use those as another example to follow.
|