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

6 files changed, 60 insertions, 52 deletions

diff --git a/docs/modules/ROOT/pages/errors-and-warnings.adoc b/docs/modules/ROOT/pages/errors-and-warnings.adoc
index 7799f7ce..16c8dec9 100644
--- a/docs/modules/ROOT/pages/errors-and-warnings.adoc
+++ b/docs/modules/ROOT/pages/errors-and-warnings.adoc
@@ -200,11 +200,11 @@ In source listings, is the callout the last thing on the line?
 |#book-parts-and-chapters#
 
 |<docname> malformed manpage title
-|Invalid manpage document structure.
+|Document does not conform to the structure required by the declared manpage doctype.
 |#man-pages#
 
 |<docname> malformed name section body
-|Invalid manpage document structure.
+|Document does not conform to the structure required by the declared manpage doctype.
 |#man-pages#
 
 |<docname> maximum include depth of 64 exceeded
@@ -216,11 +216,11 @@ In source listings, is the callout the last thing on the line?
 |#ifdef-directive#
 
 |<docname> name section expected
-|Invalid manpage document structure.
+|Document does not conform to the structure required by the declared manpage doctype.
 |#man-pages#
 
 |<docname> name section title must be at level 1
-|Invalid manpage document structure.
+|Document does not conform to the structure required by the declared manpage doctype.
 |#man-pages#
 
 |<docname> only book doctypes can contain level 0 sections
diff --git a/docs/modules/ROOT/pages/whats-new.adoc b/docs/modules/ROOT/pages/whats-new.adoc
index 821aa5de..7b51c112 100644
--- a/docs/modules/ROOT/pages/whats-new.adoc
+++ b/docs/modules/ROOT/pages/whats-new.adoc
@@ -26,7 +26,7 @@ _**Release date:** 2021.04.27_
 
 == Improvements
 
-* Format keyboard references in monospace in manpage output
+* Format keyboard references in monospace in man page output
 
 == Build and infrastructure
 
@@ -70,20 +70,20 @@ _**Release date:** 2021.04.10_
 * Honor list of tags following negated wildcard on include directive (#3932)
 * Update default stylesheet to remove the dash in front of cite on nested quote block (#3847)
 * Don't mangle formatting macros when uppercasing section titles in man page output (#3892)
-* Don't escape hyphen in `manname` in manpage output
-* Remove extra `.sp` line before content of verse block in manpage output
-* Fix layout of footnotes in manpage output (#3989)
-* Fix formatting of footnote text with URL in manpage output (#3988)
+* Don't escape hyphen in `manname` in man page output
+* Remove extra `.sp` line before content of verse block in man page output
+* Fix layout of footnotes in man page output (#3989)
+* Fix formatting of footnote text with URL in man page output (#3988)
 * Remove redundant trailing space on URL followed by non-adjacent text in man page output (#4004)
-* Use `.bp` macro at location of page break in manpage output (#3992)
+* Use `.bp` macro at location of page break in man page output (#3992)
 
 == Improvements
 
 * Extract method to create lexer and formatter in Rouge adapter (#3953) (*@Oblomov*)
 * Add support for pygments.rb 2.x (#3969) (*@slonopotamus*)
 * Allow `NullLogger` to be enabled by setting the `:logger` option to a falsy value (#3982)
-* Substitute attributes in manpurpose part of NAME section in manpage doctype (#4000)
-* Output all mannames in name section of HTML output for manpage doctype (#3757)
+* Substitute attributes in manpurpose part of NAME section in man page doctype (#4000)
+* Output all mannames in name section of HTML output for man page doctype (#3757)
 
 == Build and infrastructure
 
@@ -137,7 +137,7 @@ _**Release date:** 2020.11.02_
 == Bug fixes
 
 * Fix infinite loop when callout list with obsolete syntax is found inside list item (#3472)
-* Fix infinite loop when xreftext contains a circular reference path in HTML and manpage converters (#3543)
+* Fix infinite loop when xreftext contains a circular reference path in HTML and man page converters (#3543)
 * Apply text formatting to table cells in implicit header row when column has the `a` or `l` style (#3760)
 * Fix errant reference warning for valid reference when running in compat mode (#3555)
 * 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_
 * Remove excess hard line break in multi-line AsciiMath blocks (#3407)
 * Only strip trailing spaces from lines of AsciiDoc include file (#3436)
 * Remove errant optional flag in regexp for menu macro that breaks Asciidoctor.js (#3433)
-* Preserve repeating backslashes when generating manpage output (#3456)
+* Preserve repeating backslashes when generating man page output (#3456)
 * Honor percentage width specified on macro of inline SVG (#3464)
 * Removing leading and trailing blank lines in AsciiDoc include file to match assumption of parser (#3470)
 * Activate extensions when `:extensions` option is set, even if Extensions API is not yet loaded (#3570)
 * Don't activate global extensions if `:extensions` option is `false` (#3570)
-* Escape ellipsis at start of line in manpage output (#3645) (*@jnavila*)
+* Escape ellipsis at start of line in man page output (#3645) (*@jnavila*)
 * Don't register footnote with ID if a footnote is already registered with that ID (#3690)
-* Honor `start` attribute on ordered list in manpage output (#3714)
+* Honor `start` attribute on ordered list in man page output (#3714)
 * Warn instead of crashing if SVG to inline is empty (#3638) (*@mogztter*)
 * Compute highlight line ranges on source block relative to value of `start` attribute (#3519) (*@mogztter*)
 * Prevent collapsible block from incrementing example number by assigning an empty caption (#3639)
@@ -189,7 +189,7 @@ _**Release date:** 2020.11.02_
 * Allow `nobreak` and `nowrap` roles to be used on any inline element (#3544)
 * Add CSS class to support `pre-wrap` role to preserve leading, trailing, and repeating spaces in phrase (#3815)
 * Preserve guard around XML-style callout when icons are not enabled (#3319)
-* Use `.fam C` command to switch font family for verbatim blocks to monospaced text in manpage output (#3561)
+* Use `.fam C` command to switch font family for verbatim blocks to monospaced text in man page output (#3561)
 * Remove redundant test for `halign` and `valign` attributes on table cell in DocBook converter
 * Allow encoding of include file to be specified using `encoding` attribute (#3248)
 * Allow template to be used to override outline by only specifying the outline template (#3491)
@@ -393,7 +393,7 @@ _**Release date:** 2019.03.22_
 * If the target of a formal xref macro has a file extension, assume it's a path reference (#3021)
 * Never assume target of a formal xref macro is a path reference unless a file extension or fragment is present (#3021)
 * Encode characters in URI to comply with RFC-3986
-* Implement full support for styled xreftext in manpage converter (#3077)
+* Implement full support for styled xreftext in man page converter (#3077)
 * Allow the `id` and `role` properties to be set on a list item of ordered and unordered lists via the API (#2840)
 * Yield processor instance to registration block for document processor if block has non-zero arity (i.e., has parameters)
 * Add `Document#parsed?` method to check whether document has been parsed
diff --git a/docs/modules/cli/pages/index.adoc b/docs/modules/cli/pages/index.adoc
index ac6af138..d2b7dab9 100644
--- a/docs/modules/cli/pages/index.adoc
+++ b/docs/modules/cli/pages/index.adoc
@@ -1,5 +1,5 @@
 = Process AsciiDoc Using the CLI
-:url-manpage: https://github.com/asciidoctor/asciidoctor/blob/v{release-version}/man/asciidoctor.adoc
+:url-asciidoctor-1: https://github.com/asciidoctor/asciidoctor/blob/v{release-version}/man/asciidoctor.adoc
 
 ////
 command-line-usage.adoc
@@ -36,4 +36,4 @@ You can generate the full documentation (i.e., man page) for the `asciidoctor` c
 
  $ asciidoctor --help manpage | man -l -
 
-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.
+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.
diff --git a/docs/modules/extensions/pages/inline-macro-processor.adoc b/docs/modules/extensions/pages/inline-macro-processor.adoc
index 7f45ff6e..4201c1ed 100644
--- a/docs/modules/extensions/pages/inline-macro-processor.adoc
+++ b/docs/modules/extensions/pages/inline-macro-processor.adoc
@@ -2,7 +2,7 @@
 :navtitle: Inline Macro Processor
 
 Purpose::
-Create an inline macro named `man` that links to a manpage.
+Create an inline macro named `man` that links to another man page.
 
 == sample-with-man-link.adoc
 
diff --git a/docs/modules/manpage-backend/pages/index.adoc b/docs/modules/manpage-backend/pages/index.adoc
index cb27195b..b8817bff 100644
--- a/docs/modules/manpage-backend/pages/index.adoc
+++ b/docs/modules/manpage-backend/pages/index.adoc
@@ -1,30 +1,34 @@
 = Generate Manual Pages from AsciiDoc
 :navtitle: Generate Manual Pages
-:url-man7: https://man7.org/linux/man-pages/man7/roff.7.html
+:url-man-page: https://en.wikipedia.org/wiki/Man_page
+:url-man-7: https://man7.org/linux/man-pages/man7/roff.7.html
 :url-docbook-refmisc: https://tdg.docbook.org/tdg/5.0/refmiscinfo.html
-:url-manpage-raw: https://raw.githubusercontent.com/asciidoctor/asciidoctor/v{release-version}/man/asciidoctor.adoc
+:url-asciidoctor-1-raw: https://raw.githubusercontent.com/asciidoctor/asciidoctor/v{release-version}/man/asciidoctor.adoc
 
 The AsciiDoc language defines a doctype named `manpage` for composing manual pages (man pages) in AsciiDoc.
-Asciidoctor provides a converter that converts this AsciiDoc structure into a roff-formatted man page.
+Asciidoctor provides a converter for converting this AsciiDoc structure into a roff-formatted man page.
 
-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.
+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.
 
 == What is a manual page?
 
-A manual page, often abbreviated [.term]_man page_, is a form of software documentation that typically accompanies software on Unix-like operating systems.
+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.
 Its formalized structure allows the `man` command to present the man page as a formatted document in a terminal pager.
 
-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.
+The benefit of composing a man page in AsciiDoc is that you can convert it to multiple formats, including HTML and PDF.
 That makes the source of the man page reusable.
 
 [#doctype]
 == manpage doctype
 
-The `manpage` doctype has the following required parts:
+The `manpage` doctype declares that the AsciiDoc structure serves as the source of a man page and conforms to the man page structure.
+Notice the absense of the space in the doctype value.
+
+By declaring the `manpage` doctype, the AsciiDoc processor expects the document to conform to the following structure.
 
 Document Header::
 In a man page, the document header is mandatory.
-The doctitle consists of the program name (i.e., progname) followed by the manual volume number in round brackets (e.g., `progname(1)`).
+The doctitle consists of the program name followed by the volume number in round brackets (e.g., `progname(1)`).
 The doctitle must not contain spaces.
 The volume number is a single digit optionally followed by a single character.
 
@@ -33,7 +37,7 @@ There are several built-in document attributes that impact how the source is par
 Refer to the <<document-attributes>> section.
 
 The NAME Section::
-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.
+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`).
 The dash must have at least one space character on either side.
 
 The SYNOPSIS Section::
@@ -41,8 +45,11 @@ The second section is recommended and, if present, must be titled "`SYNOPSIS`" (
 
 Subsequent sections are optional, but typical sections include "`SEE ALSO`", "`BUGS REPORTS`", "`AUTHORS`" and "`COPYRIGHT`".
 
+TIP: Since the structure required by the `manpage` doctype is standard AsciiDoc, you can opt to declare the `manpage` doctype at runtime.
+When the `doctype` attribute is not set, Asciidoctor will parse the document as an article and not give it any special treatment.
+
 Here's an example man page composed in AsciiDoc for the `eve` command.
-Notice that it declares the `manpage` doctype and adheres to the aforementioned structure.
+Notice that it declares the `manpage` doctype and conforms to the described structure.
 
 .progname.adoc
 [,asciidoc]
@@ -50,24 +57,25 @@ Notice that it declares the `manpage` doctype and adheres to the aforementioned
 include::example$manpage.adoc[]
 ----
 
-Although the source document is named [.path]_progname.adoc_, you can name it whatever you like.
+Although the source document is named [.path]_progname.adoc_, you can name the file whatever you like.
 The output filename is determined by the `manname` and `manvolnum` attributes implicitly defined by the doctitle.
 In this example, the output filename is [.path]_eve.1_.
 
 == manpage backend and converter
 
-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.
-This converter is bound to the `manpage` backend (not to be confused with the `manpage` document).
+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.
+This converter is bound to the `manpage` backend (not to be confused with the `manpage` doctype).
+Notice the absense of the space in the backend value.
 
-The manpage converter is typically used to generate man pages that accompanies software on Unix-like operating systems.
-In fact, Asciidoctor's own man page (i.e., `man asciidoctor`) is generated this way from {url-manpage-raw}[this AsciiDoc source].
+The man page converter is typically used to generate man pages that accompany software on Unix-like operating systems.
+In fact, Asciidoctor's own man page (i.e., `man asciidoctor`) is generated in this way from {url-asciidoctor-1-raw}[this AsciiDoc source].
 
-To use the manpage converter, assign `manpage` to the `backend` option.
-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)`).
+To use the man page converter, assign `manpage` to the `backend` option.
+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)`).
 
-== Generate a man page with the manpage converter
+== Generate a man page
 
-Before running Asciidoctor, make sure your source document adheres to the <<doctype,manpage doctype structure>> and the `doctype` attribute is assigned the value `manpage`.
+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`.
 
 To generate a man page, run:
 
@@ -81,18 +89,18 @@ If the titles are uppercased in the source, that casing ends up getting used in
 CAUTION: Prior to Ruby 2.4, Ruby could only uppercase Latin letters.
 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.
 
-Recall that you're not limited to using the manpage converter to convert an AsciiDoc document that uses the `manpage` doctype.
+Recall that you're not limited to using the man page converter to convert an AsciiDoc document that uses the `manpage` doctype.
 You can just as well convert it to HTML, as shown here.
 
  $ asciidoctor progname.adoc
 
 The structure of the source document is still enforced, but the output document will look like the output of any other AsciiDoc document.
 
-== Convert the man page to PostScript or PDF
+== Convert the man page to PostScript / PDF
 
 Once you have created a man page, you can convert it to PostScript using the `man` command.
 
-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.
+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.
 You can convert `progname.1` to PostScript and redirect the output to `progname.ps` using the following `man` command:
 
  $ man -t ./progname.1 > progname.ps
@@ -116,12 +124,12 @@ If you want to generate PDF files directly from Asciidoctor, you may be interest
 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.
 
 [#document-attributes]
-== manpage document attributes
+== Document attributes
 
-Several built-in document attributes only affect man pages.
+Several built-in document attributes only affect the manpage doctype and output.
 These attributes must be set in the document header.
 
-.Built-in manpage document attributes
+.Built-in document attributes for man pages
 [%autowidth]
 |===
 |Attribute |Description |Value (as parsed from example above)
@@ -143,13 +151,13 @@ These attributes must be set in the document header.
 |converts AsciiDoc source files
 
 |`man-linkstyle`
-|Style the links in the manpage output.
+|Style the links in the man page output.
 A valid link format sequence.
 // Needs a reference to this.
 |[.pre-wrap]#blue R < >#
 
 |`mansource`
-|The source to which the manpage pertains.
+|The source to which the man page pertains.
 When producing DocBook, it becomes a DocBook {url-docbook-refmisc}[refmiscinfo^] attribute and appears in the footer.
 |Asciidoctor
 
@@ -168,6 +176,6 @@ When producing DocBook, it becomes a DocBook {url-docbook-refmisc}[refmiscinfo^]
 
 == See also
 
-Refer to {url-manpage-raw}[the AsciiDoc source of the Asciidoctor man page^] to see a complete example.
-The man page for Asciidoctor is produced using the `manpage` converter.
+Refer to the {url-asciidoctor-1-raw}[AsciiDoc source of the Asciidoctor man page^] to see a complete example.
+The man page for Asciidoctor is produced using the man page converter.
 The man pages for git are also produced from AsciiDoc documents, so you can use those as another example to follow.
diff --git a/docs/modules/migrate/pages/asciidoc-py.adoc b/docs/modules/migrate/pages/asciidoc-py.adoc
index a284072b..2255d9c6 100644
--- a/docs/modules/migrate/pages/asciidoc-py.adoc
+++ b/docs/modules/migrate/pages/asciidoc-py.adoc
@@ -1,7 +1,7 @@
 = Migrate from AsciiDoc.py
 :url-tests: {url-org}/asciidoctor/tree/master/test
 :url-doctest: {url-org}/asciidoctor-doctest
-:url-manpage: {url-project}/man/asciidoctor
+:url-asciidoctor-1: {url-project}/man/asciidoctor
 
 AsciiDoc.py is the original and legacy Python-based processor for the AsciiDoc language.
 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
 
  $ asciidoctor --help manpage | man -l - | col -bx
 
-Alternately, you can view the manpage for Asciidoctor online at {url-manpage}[asciidoctor(1)].
+Alternately, you can view the man page for Asciidoctor online at {url-asciidoctor-1}[asciidoctor(1)].
 
 ////
 This content needs to be move to the specific subject docs pages if applicable