Skip to content

Commit d4e2659

Browse files
committed
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
1 parent e3c6ab4 commit d4e2659

File tree

6 files changed

+60
-52
lines changed

6 files changed

+60
-52
lines changed

docs/modules/ROOT/pages/errors-and-warnings.adoc

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -200,11 +200,11 @@ In source listings, is the callout the last thing on the line?
200200
|#book-parts-and-chapters#
201201

202202
|<docname> malformed manpage title
203-
|Invalid manpage document structure.
203+
|Document does not conform to the structure required by the declared manpage doctype.
204204
|#man-pages#
205205

206206
|<docname> malformed name section body
207-
|Invalid manpage document structure.
207+
|Document does not conform to the structure required by the declared manpage doctype.
208208
|#man-pages#
209209

210210
|<docname> maximum include depth of 64 exceeded
@@ -216,11 +216,11 @@ In source listings, is the callout the last thing on the line?
216216
|#ifdef-directive#
217217

218218
|<docname> name section expected
219-
|Invalid manpage document structure.
219+
|Document does not conform to the structure required by the declared manpage doctype.
220220
|#man-pages#
221221

222222
|<docname> name section title must be at level 1
223-
|Invalid manpage document structure.
223+
|Document does not conform to the structure required by the declared manpage doctype.
224224
|#man-pages#
225225

226226
|<docname> only book doctypes can contain level 0 sections

docs/modules/ROOT/pages/whats-new.adoc

Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ _**Release date:** 2021.04.27_
2626

2727
== Improvements
2828

29-
* Format keyboard references in monospace in manpage output
29+
* Format keyboard references in monospace in man page output
3030

3131
== Build and infrastructure
3232

@@ -70,20 +70,20 @@ _**Release date:** 2021.04.10_
7070
* Honor list of tags following negated wildcard on include directive (#3932)
7171
* Update default stylesheet to remove the dash in front of cite on nested quote block (#3847)
7272
* Don't mangle formatting macros when uppercasing section titles in man page output (#3892)
73-
* Don't escape hyphen in `manname` in manpage output
74-
* Remove extra `.sp` line before content of verse block in manpage output
75-
* Fix layout of footnotes in manpage output (#3989)
76-
* Fix formatting of footnote text with URL in manpage output (#3988)
73+
* Don't escape hyphen in `manname` in man page output
74+
* Remove extra `.sp` line before content of verse block in man page output
75+
* Fix layout of footnotes in man page output (#3989)
76+
* Fix formatting of footnote text with URL in man page output (#3988)
7777
* Remove redundant trailing space on URL followed by non-adjacent text in man page output (#4004)
78-
* Use `.bp` macro at location of page break in manpage output (#3992)
78+
* Use `.bp` macro at location of page break in man page output (#3992)
7979

8080
== Improvements
8181

8282
* Extract method to create lexer and formatter in Rouge adapter (#3953) (*@Oblomov*)
8383
* Add support for pygments.rb 2.x (#3969) (*@slonopotamus*)
8484
* Allow `NullLogger` to be enabled by setting the `:logger` option to a falsy value (#3982)
85-
* Substitute attributes in manpurpose part of NAME section in manpage doctype (#4000)
86-
* Output all mannames in name section of HTML output for manpage doctype (#3757)
85+
* Substitute attributes in manpurpose part of NAME section in man page doctype (#4000)
86+
* Output all mannames in name section of HTML output for man page doctype (#3757)
8787

8888
== Build and infrastructure
8989

@@ -137,7 +137,7 @@ _**Release date:** 2020.11.02_
137137
== Bug fixes
138138

139139
* Fix infinite loop when callout list with obsolete syntax is found inside list item (#3472)
140-
* Fix infinite loop when xreftext contains a circular reference path in HTML and manpage converters (#3543)
140+
* Fix infinite loop when xreftext contains a circular reference path in HTML and man page converters (#3543)
141141
* Apply text formatting to table cells in implicit header row when column has the `a` or `l` style (#3760)
142142
* Fix errant reference warning for valid reference when running in compat mode (#3555)
143143
* Initialize backend traits for converter (if not previously initialized) using assigned basebackend; mimics Asciidoctor < 2 behavior (#3341)
@@ -153,14 +153,14 @@ _**Release date:** 2020.11.02_
153153
* Remove excess hard line break in multi-line AsciiMath blocks (#3407)
154154
* Only strip trailing spaces from lines of AsciiDoc include file (#3436)
155155
* Remove errant optional flag in regexp for menu macro that breaks Asciidoctor.js (#3433)
156-
* Preserve repeating backslashes when generating manpage output (#3456)
156+
* Preserve repeating backslashes when generating man page output (#3456)
157157
* Honor percentage width specified on macro of inline SVG (#3464)
158158
* Removing leading and trailing blank lines in AsciiDoc include file to match assumption of parser (#3470)
159159
* Activate extensions when `:extensions` option is set, even if Extensions API is not yet loaded (#3570)
160160
* Don't activate global extensions if `:extensions` option is `false` (#3570)
161-
* Escape ellipsis at start of line in manpage output (#3645) (*@jnavila*)
161+
* Escape ellipsis at start of line in man page output (#3645) (*@jnavila*)
162162
* Don't register footnote with ID if a footnote is already registered with that ID (#3690)
163-
* Honor `start` attribute on ordered list in manpage output (#3714)
163+
* Honor `start` attribute on ordered list in man page output (#3714)
164164
* Warn instead of crashing if SVG to inline is empty (#3638) (*@mogztter*)
165165
* Compute highlight line ranges on source block relative to value of `start` attribute (#3519) (*@mogztter*)
166166
* Prevent collapsible block from incrementing example number by assigning an empty caption (#3639)
@@ -189,7 +189,7 @@ _**Release date:** 2020.11.02_
189189
* Allow `nobreak` and `nowrap` roles to be used on any inline element (#3544)
190190
* Add CSS class to support `pre-wrap` role to preserve leading, trailing, and repeating spaces in phrase (#3815)
191191
* Preserve guard around XML-style callout when icons are not enabled (#3319)
192-
* Use `.fam C` command to switch font family for verbatim blocks to monospaced text in manpage output (#3561)
192+
* Use `.fam C` command to switch font family for verbatim blocks to monospaced text in man page output (#3561)
193193
* Remove redundant test for `halign` and `valign` attributes on table cell in DocBook converter
194194
* Allow encoding of include file to be specified using `encoding` attribute (#3248)
195195
* Allow template to be used to override outline by only specifying the outline template (#3491)
@@ -393,7 +393,7 @@ _**Release date:** 2019.03.22_
393393
* If the target of a formal xref macro has a file extension, assume it's a path reference (#3021)
394394
* Never assume target of a formal xref macro is a path reference unless a file extension or fragment is present (#3021)
395395
* Encode characters in URI to comply with RFC-3986
396-
* Implement full support for styled xreftext in manpage converter (#3077)
396+
* Implement full support for styled xreftext in man page converter (#3077)
397397
* Allow the `id` and `role` properties to be set on a list item of ordered and unordered lists via the API (#2840)
398398
* Yield processor instance to registration block for document processor if block has non-zero arity (i.e., has parameters)
399399
* Add `Document#parsed?` method to check whether document has been parsed

docs/modules/cli/pages/index.adoc

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
= Process AsciiDoc Using the CLI
2-
:url-manpage: https://github.com/asciidoctor/asciidoctor/blob/v{release-version}/man/asciidoctor.adoc
2+
:url-asciidoctor-1: https://github.com/asciidoctor/asciidoctor/blob/v{release-version}/man/asciidoctor.adoc
33

44
////
55
command-line-usage.adoc
@@ -36,4 +36,4 @@ You can generate the full documentation (i.e., man page) for the `asciidoctor` c
3636

3737
$ asciidoctor --help manpage | man -l -
3838

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.

docs/modules/extensions/pages/inline-macro-processor.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
:navtitle: Inline Macro Processor
33

44
Purpose::
5-
Create an inline macro named `man` that links to a manpage.
5+
Create an inline macro named `man` that links to another man page.
66

77
== sample-with-man-link.adoc
88

docs/modules/manpage-backend/pages/index.adoc

Lines changed: 37 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,34 @@
11
= Generate Manual Pages from AsciiDoc
22
:navtitle: Generate Manual Pages
3-
:url-man7: https://man7.org/linux/man-pages/man7/roff.7.html
3+
:url-man-page: https://en.wikipedia.org/wiki/Man_page
4+
:url-man-7: https://man7.org/linux/man-pages/man7/roff.7.html
45
:url-docbook-refmisc: https://tdg.docbook.org/tdg/5.0/refmiscinfo.html
5-
:url-manpage-raw: https://raw.githubusercontent.com/asciidoctor/asciidoctor/v{release-version}/man/asciidoctor.adoc
6+
:url-asciidoctor-1-raw: https://raw.githubusercontent.com/asciidoctor/asciidoctor/v{release-version}/man/asciidoctor.adoc
67

78
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.
910

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

1213
== What is a manual page?
1314

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.
1516
Its formalized structure allows the `man` command to present the man page as a formatted document in a terminal pager.
1617

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.
1819
That makes the source of the man page reusable.
1920

2021
[#doctype]
2122
== manpage doctype
2223

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

2529
Document Header::
2630
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)`).
2832
The doctitle must not contain spaces.
2933
The volume number is a single digit optionally followed by a single character.
3034

@@ -33,41 +37,45 @@ There are several built-in document attributes that impact how the source is par
3337
Refer to the <<document-attributes>> section.
3438

3539
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`).
3741
The dash must have at least one space character on either side.
3842

3943
The SYNOPSIS Section::
4044
The second section is recommended and, if present, must be titled "`SYNOPSIS`" (or "`Synopsis`").
4145

4246
Subsequent sections are optional, but typical sections include "`SEE ALSO`", "`BUGS REPORTS`", "`AUTHORS`" and "`COPYRIGHT`".
4347

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+
4451
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.
4653

4754
.progname.adoc
4855
[,asciidoc]
4956
----
5057
include::example$manpage.adoc[]
5158
----
5259

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.
5461
The output filename is determined by the `manname` and `manvolnum` attributes implicitly defined by the doctitle.
5562
In this example, the output filename is [.path]_eve.1_.
5663

5764
== manpage backend and converter
5865

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

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].
6472

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)`).
6775

68-
== Generate a man page with the manpage converter
76+
== Generate a man page
6977

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`.
7179

7280
To generate a man page, run:
7381

@@ -81,18 +89,18 @@ If the titles are uppercased in the source, that casing ends up getting used in
8189
CAUTION: Prior to Ruby 2.4, Ruby could only uppercase Latin letters.
8290
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.
8391

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.
8593
You can just as well convert it to HTML, as shown here.
8694

8795
$ asciidoctor progname.adoc
8896

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

91-
== Convert the man page to PostScript or PDF
99+
== Convert the man page to PostScript / PDF
92100

93101
Once you have created a man page, you can convert it to PostScript using the `man` command.
94102

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.
96104
You can convert `progname.1` to PostScript and redirect the output to `progname.ps` using the following `man` command:
97105

98106
$ man -t ./progname.1 > progname.ps
@@ -116,12 +124,12 @@ If you want to generate PDF files directly from Asciidoctor, you may be interest
116124
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.
117125

118126
[#document-attributes]
119-
== manpage document attributes
127+
== Document attributes
120128

121-
Several built-in document attributes only affect man pages.
129+
Several built-in document attributes only affect the manpage doctype and output.
122130
These attributes must be set in the document header.
123131

124-
.Built-in manpage document attributes
132+
.Built-in document attributes for man pages
125133
[%autowidth]
126134
|===
127135
|Attribute |Description |Value (as parsed from example above)
@@ -143,13 +151,13 @@ These attributes must be set in the document header.
143151
|converts AsciiDoc source files
144152

145153
|`man-linkstyle`
146-
|Style the links in the manpage output.
154+
|Style the links in the man page output.
147155
A valid link format sequence.
148156
// Needs a reference to this.
149157
|[.pre-wrap]#blue R < >#
150158

151159
|`mansource`
152-
|The source to which the manpage pertains.
160+
|The source to which the man page pertains.
153161
When producing DocBook, it becomes a DocBook {url-docbook-refmisc}[refmiscinfo^] attribute and appears in the footer.
154162
|Asciidoctor
155163

@@ -168,6 +176,6 @@ When producing DocBook, it becomes a DocBook {url-docbook-refmisc}[refmiscinfo^]
168176

169177
== See also
170178

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.
173181
The man pages for git are also produced from AsciiDoc documents, so you can use those as another example to follow.

docs/modules/migrate/pages/asciidoc-py.adoc

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
= Migrate from AsciiDoc.py
22
:url-tests: {url-org}/asciidoctor/tree/master/test
33
:url-doctest: {url-org}/asciidoctor-doctest
4-
:url-manpage: {url-project}/man/asciidoctor
4+
:url-asciidoctor-1: {url-project}/man/asciidoctor
55

66
AsciiDoc.py is the original and legacy Python-based processor for the AsciiDoc language.
77
It has been superseded by Asciidoctor.
@@ -392,7 +392,7 @@ If you want to view the plaintext version with Asciidoctor, you can route the ou
392392

393393
$ asciidoctor --help manpage | man -l - | col -bx
394394

395-
Alternately, you can view the manpage for Asciidoctor online at {url-manpage}[asciidoctor(1)].
395+
Alternately, you can view the man page for Asciidoctor online at {url-asciidoctor-1}[asciidoctor(1)].
396396

397397
////
398398
This content needs to be move to the specific subject docs pages if applicable

0 commit comments

Comments
 (0)