You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
resolves#4012 use man page and manpage terminology consistently in docs (PR #4121)
- use "manpage" when referring to backend or doctype value
- use "man page" in all other cases
- improve description of warnings that pertain to manpage doctype
- revise documentation for manpage backend
@@ -36,4 +36,4 @@ You can generate the full documentation (i.e., man page) for the `asciidoctor` c
36
36
37
37
$ asciidoctor --help manpage | man -l -
38
38
39
-
You can find the AsciiDoc source for the {url-manpage}[Asciidoctor man page^] online in the Asciidoctor repository, which you can preview in a browser.
39
+
You can find the AsciiDoc source for the {url-asciidoctor-1}[Asciidoctor man page^] online in the Asciidoctor repository, which you can preview in a browser.
The AsciiDoc language defines a doctype named `manpage` for composing manual pages (man pages) in AsciiDoc.
8
-
Asciidoctor provides a converter that converts this AsciiDoc structure into a roff-formatted man page.
9
+
Asciidoctor provides a converter for converting this AsciiDoc structure into a roff-formatted man page.
9
10
10
-
This page introduces man pages, examines the AsciiDoc structure of a man page, and shows how to convert it to roff-formatted man page and other formats using Asciidoctor.
11
+
This page introduces **man**ual 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.
11
12
12
13
== What is a manual page?
13
14
14
-
A manual page, often abbreviated [.term]_man page_, is a form of software documentation that typically accompanies software on Unix-like operating systems.
15
+
A {url-man-page}[manual page^], typically abbreviated as [.term]_man page_, is a form of software documentation that typically accompanies software on Unix-like operating systems.
15
16
Its formalized structure allows the `man` command to present the man page as a formatted document in a terminal pager.
16
17
17
-
The benefit of compose a man page in AsciiDoc is that you can convert it to other output formats as well, including HTML and PDF.
18
+
The benefit of composing a man page in AsciiDoc is that you can convert it to multiple formats, including HTML and PDF.
18
19
That makes the source of the man page reusable.
19
20
20
21
[#doctype]
21
22
== manpage doctype
22
23
23
-
The `manpage` doctype has the following required parts:
24
+
The `manpage` doctype declares that the AsciiDoc structure serves as the source of a man page and conforms to the man page structure.
25
+
Notice the absense of the space in the doctype value.
26
+
27
+
By declaring the `manpage` doctype, the AsciiDoc processor expects the document to conform to the following structure.
24
28
25
29
Document Header::
26
30
In a man page, the document header is mandatory.
27
-
The doctitle consists of the program name (i.e., progname) followed by the manual volume number in round brackets (e.g., `progname(1)`).
31
+
The doctitle consists of the program name followed by the volume number in round brackets (e.g., `progname(1)`).
28
32
The doctitle must not contain spaces.
29
33
The volume number is a single digit optionally followed by a single character.
30
34
@@ -33,41 +37,45 @@ There are several built-in document attributes that impact how the source is par
33
37
Refer to the <<document-attributes>> section.
34
38
35
39
The NAME Section::
36
-
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.
40
+
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`).
37
41
The dash must have at least one space character on either side.
38
42
39
43
The SYNOPSIS Section::
40
44
The second section is recommended and, if present, must be titled "`SYNOPSIS`" (or "`Synopsis`").
41
45
42
46
Subsequent sections are optional, but typical sections include "`SEE ALSO`", "`BUGS REPORTS`", "`AUTHORS`" and "`COPYRIGHT`".
43
47
48
+
TIP: Since the structure required by the `manpage` doctype is standard AsciiDoc, you can opt to declare the `manpage` doctype at runtime.
49
+
When the `doctype` attribute is not set, Asciidoctor will parse the document as an article and not give it any special treatment.
50
+
44
51
Here's an example man page composed in AsciiDoc for the `eve` command.
45
-
Notice that it declares the `manpage` doctype and adheres to the aforementioned structure.
52
+
Notice that it declares the `manpage` doctype and conforms to the described structure.
46
53
47
54
.progname.adoc
48
55
[,asciidoc]
49
56
----
50
57
include::example$manpage.adoc[]
51
58
----
52
59
53
-
Although the source document is named [.path]_progname.adoc_, you can name it whatever you like.
60
+
Although the source document is named [.path]_progname.adoc_, you can name the file whatever you like.
54
61
The output filename is determined by the `manname` and `manvolnum` attributes implicitly defined by the doctitle.
55
62
In this example, the output filename is [.path]_eve.1_.
56
63
57
64
== manpage backend and converter
58
65
59
-
Asciidoctor provides a built-in manpage converter to generate {url-man7}[roff-formatted^] man pages from AsciiDoc documents that declare and adhere to the manpage doctype.
60
-
This converter is bound to the `manpage` backend (not to be confused with the `manpage` document).
66
+
Asciidoctor provides a built-in converter to generate {url-man-7}[roff-formatted^] man pages for AsciiDoc documents that declare and conform to the manpage doctype.
67
+
This converter is bound to the `manpage` backend (not to be confused with the `manpage` doctype).
68
+
Notice the absense of the space in the backend value.
61
69
62
-
The manpage converter is typically used to generate man pages that accompanies software on Unix-like operating systems.
63
-
In fact, Asciidoctor's own man page (i.e., `man asciidoctor`) is generated this way from {url-manpage-raw}[this AsciiDoc source].
70
+
The man page converter is typically used to generate man pages that accompany software on Unix-like operating systems.
71
+
In fact, Asciidoctor's own man page (i.e., `man asciidoctor`) is generated in this way from {url-asciidoctor-1-raw}[this AsciiDoc source].
64
72
65
-
To use the manpage converter, assign `manpage` to the `backend` option.
66
-
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 (e.g., `progname(1)`).
73
+
To use the man page converter, assign `manpage` to the `backend` option.
74
+
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)`).
67
75
68
-
== Generate a man page with the manpage converter
76
+
== Generate a man page
69
77
70
-
Before running Asciidoctor, make sure your source document adheres to the <<doctype,manpage doctype structure>> and the `doctype` attribute is assigned the value `manpage`.
78
+
Before running Asciidoctor, make sure your source document conforms to the <<doctype,manpage doctype structure>> and the `doctype` attribute is set and has the value `manpage`.
71
79
72
80
To generate a man page, run:
73
81
@@ -81,18 +89,18 @@ If the titles are uppercased in the source, that casing ends up getting used in
81
89
CAUTION: Prior to Ruby 2.4, Ruby could only uppercase Latin letters.
82
90
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.
83
91
84
-
Recall that you're not limited to using the manpage converter to convert an AsciiDoc document that uses the `manpage` doctype.
92
+
Recall that you're not limited to using the man page converter to convert an AsciiDoc document that uses the `manpage` doctype.
85
93
You can just as well convert it to HTML, as shown here.
86
94
87
95
$ asciidoctor progname.adoc
88
96
89
97
The structure of the source document is still enforced, but the output document will look like the output of any other AsciiDoc document.
90
98
91
-
== Convert the man page to PostScript or PDF
99
+
== Convert the man page to PostScript / PDF
92
100
93
101
Once you have created a man page, you can convert it to PostScript using the `man` command.
94
102
95
-
Let's assume that the output file produced by the Asciidoctor manpage converter is `progname.1`, where `progname` is the name of the command and `1` is the volume number.
103
+
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.
96
104
You can convert `progname.1` to PostScript and redirect the output to `progname.ps` using the following `man` command:
97
105
98
106
$ man -t ./progname.1 > progname.ps
@@ -116,12 +124,12 @@ If you want to generate PDF files directly from Asciidoctor, you may be interest
116
124
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.
117
125
118
126
[#document-attributes]
119
-
== manpage document attributes
127
+
== Document attributes
120
128
121
-
Several built-in document attributes only affect man pages.
129
+
Several built-in document attributes only affect the manpage doctype and output.
122
130
These attributes must be set in the document header.
123
131
124
-
.Built-in manpage document attributes
132
+
.Built-in document attributes for man pages
125
133
[%autowidth]
126
134
|===
127
135
|Attribute |Description |Value (as parsed from example above)
@@ -143,13 +151,13 @@ These attributes must be set in the document header.
143
151
|converts AsciiDoc source files
144
152
145
153
|`man-linkstyle`
146
-
|Style the links in the manpage output.
154
+
|Style the links in the man page output.
147
155
A valid link format sequence.
148
156
// Needs a reference to this.
149
157
|[.pre-wrap]#blue R < >#
150
158
151
159
|`mansource`
152
-
|The source to which the manpage pertains.
160
+
|The source to which the man page pertains.
153
161
When producing DocBook, it becomes a DocBook {url-docbook-refmisc}[refmiscinfo^] attribute and appears in the footer.
154
162
|Asciidoctor
155
163
@@ -168,6 +176,6 @@ When producing DocBook, it becomes a DocBook {url-docbook-refmisc}[refmiscinfo^]
168
176
169
177
== See also
170
178
171
-
Refer to {url-manpage-raw}[the AsciiDoc source of the Asciidoctor man page^] to see a complete example.
172
-
The man page for Asciidoctor is produced using the `manpage` converter.
179
+
Refer to the {url-asciidoctor-1-raw}[AsciiDoc source of the Asciidoctor man page^] to see a complete example.
180
+
The man page for Asciidoctor is produced using the man page converter.
173
181
The man pages for git are also produced from AsciiDoc documents, so you can use those as another example to follow.
0 commit comments