rework the backend and converter sections for each of the built-in converters

3 files changed, 52 insertions, 26 deletions

diff --git a/docs/modules/docbook-backend/pages/index.adoc b/docs/modules/docbook-backend/pages/index.adoc
index f4ee2a77..97565e8c 100644
--- a/docs/modules/docbook-backend/pages/index.adoc
+++ b/docs/modules/docbook-backend/pages/index.adoc
@@ -3,16 +3,23 @@
 :url-docbook45: https://github.com/asciidoctor/asciidoctor-docbook45
 :url-yelp: https://wiki.gnome.org/action/show/Apps/Yelp
 
-== DocBook 5.0 converter
+Asciidoctor can produce the DocBook 5 XML output format from an AsciiDoc document.
+Although DocBook XML is not a publishable format, it can be used to tie into an existing publishing toolchain that processes DocBook.
+This page explains how to use Asciidoctor to convert AsciiDoc to DocBook.
 
-Asciidoctor can produce DocBook 5.0 XML output.
-There's a corresponding DocBook element for each AsciiDoc element.
+== Backend and converter
 
-`docbook`::
-The DocBook 5.0 converter generates DocBook 5.0 XML.
-To use the DocBook converter, assign `docbook` or `docbook5` to the `backend` option.
+Asciidoctor's built-in DocBook converter is registered for the `docbook` and `docbook5` backends.
+The DocBook converter generates XML that adheres to the DocBook XML schema.
+There's a corresponding DocBook tag for each AsciiDoc element.
 
-== Generate DocBook with the docbook converter
+[horizontal]
+Backend names:: `docbook`, `docbook5`
+Converter class:: `Asciidoctor::Converter::DocBook5Converter`
+Output format:: XML
+Output file extension:: .xml
+
+== Generate DocBook
 
 . To follow along with the steps below, use your own AsciiDoc file or copy the contents of <<ex-my-doc>> into a new plain text file.
 +
diff --git a/docs/modules/html-backend/pages/index.adoc b/docs/modules/html-backend/pages/index.adoc
index 0bef296c..1de65ff6 100644
--- a/docs/modules/html-backend/pages/index.adoc
+++ b/docs/modules/html-backend/pages/index.adoc
@@ -1,11 +1,21 @@
 = Generate HTML from AsciiDoc
 :navtitle: Generate HTML
 
-== HTML 5 converter
+Asciidoctor's default output format is HTML (specifically HTML 5).
+That means when you run Asciidoctor without any parameters, it will produce HTML.
+This page explains how to use Asciidoctor to convert AsciiDoc to HTML.
 
-Asciidoctor's default output format is HTML.
+== Backend and converter
 
-`html`:: The HTML 5 converter (`html` or `html5`) generates HTML 5 styled with CSS3.
+Asciidoctor's built-in HTML converter is registered for the `html` and `html5` backends.
+The HTML converter generates HTML 5 that's styled with CSS3.
+It may include JavaScript to support additional integrations, such as client-side syntax highlighting.
+
+[horizontal]
+Backend names:: `html`, `html5`
+Converter class:: `Asciidoctor::Converter::Html5Converter`
+Output format:: HTML
+Output file extension:: .html
 
 WARNING: A standalone HTML document generated by the built-in HTML converter loads web fonts from Google Fonts, which are then referenced by the default stylesheet.
 The xref:default-stylesheet.adoc[default stylesheet] makes use of web fonts to ensure the document renders consistently across platforms.
@@ -14,7 +24,9 @@ If this presents a problem, you can xref:default-stylesheet.adoc#disable-or-modi
 When this is done, the default stylesheet reverts to using generic font families (e.g., sans-serif), which are mapped to system fonts by your browser.
 The consequence is that the appearance of the document will be different and system dependent due to a reliance on system fonts.
 
-== Generate HTML using the html5 converter
+If the backend name is prefixed with `x` (e.g., `xhtml`), the converter will <<xhtml,generate XHTML>>, the XML variant of HTML.
+
+== Generate HTML
 
 In this section, we'll create a sample document, then process and convert it with Asciidoctor's built-in HTML converter.
 
@@ -72,8 +84,11 @@ As a result, you could save [.path]_my-document.html_ to any computer and it wil
 [#xhtml]
 == Generate XHTML
 
-`xhtml`:: The XHTML variant of the HTML 5 converter.
-To use the XHTML converter, assign `xhtml` or `xhtml5` to the `backend` option.
+[horizontal]
+Backend names:: `xhtml`, `xhtml5`
+Converter class:: `Asciidoctor::Converter::Html5Converter`
+Output format:: XML variant of HTML
+Output file extension:: .html
 
 .Produce XHTML using the xhtml5 backend option
  $ asciidoctor -b xhtml5 my-document.adoc
diff --git a/docs/modules/manpage-backend/pages/index.adoc b/docs/modules/manpage-backend/pages/index.adoc
index 38e60c1b..122b8861 100644
--- a/docs/modules/manpage-backend/pages/index.adoc
+++ b/docs/modules/manpage-backend/pages/index.adoc
@@ -7,14 +7,13 @@
 :url-git-man: https://github.com/git/git/tree/master/Documentation
 
 The AsciiDoc language defines a doctype named `manpage` for composing manual pages (man pages) in AsciiDoc.
-Asciidoctor provides a converter for converting this AsciiDoc structure into a roff-formatted man page.
+Asciidoctor provides a converter for converting this AsciiDoc structure into a groff-formatted man page.
+This page introduces **man**ual pages, examines the AsciiDoc structure of a man page, and shows how to convert an AsciiDoc document to groff-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?
+== What's a manual page?
 
 A {url-man-page}[manual page^], 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.
+Its formalized structure allows the `man` command to present the man page as a formatted document in a terminal pager, such as `less`.
 
 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.
@@ -23,7 +22,7 @@ That makes the source of the man page reusable.
 == manpage doctype
 
 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 absence of the space in the doctype value.
+Note the absence of the space in the doctype value.
 
 By declaring the `manpage` doctype, the AsciiDoc processor expects the document to conform to the following structure.
 
@@ -53,7 +52,7 @@ TIP: Since the structure required by the `manpage` doctype is standard AsciiDoc,
 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 conforms to the described structure.
+Observe that it declares the `manpage` doctype and conforms to the described structure.
 
 .progname.adoc
 [,asciidoc]
@@ -65,14 +64,19 @@ Although the source document is named [.path]_progname.adoc_, you can name the f
 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
+== Backend and converter
+
+Asciidoctor provides a built-in converter to generate {url-man-7}[groff-formatted^] man pages for AsciiDoc documents that declare the `manpage` doctype and conform to it.
+Asciidoctor's own man page (i.e., `man asciidoctor`) is generated using this converter from {url-asciidoctor-1-raw}[this AsciiDoc source].
 
-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 absence of the space in the backend value.
+The man page converter is bound to the `manpage` backend (not to be confused with the `manpage` doctype).
+Note the absence of the space in the backend value.
 
-The man page converter is 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].
+[horizontal]
+Backend name:: `manpage`
+Converter class:: `Asciidoctor::Converter::ManpageConverter`
+Output format:: groff
+Output file extension:: .\{manvolnum} (e.g., .1)
 
 [#generate]
 == Generate a man page