Docbook: Documentation toolchain documentation updates.

Move some of the documentation about documentation toolchain itself from
docbook/README.adoc to the documentation toolchain chapter in the WSDG.

Fix the Debugger section level.

Change-Id: I8db92d334dd479324453f7b0bd25b33ea770c532
Reviewed-on: https://code.wireshark.org/review/36843
Reviewed-by: Gerald Combs <gerald@wireshark.org>
Petri-Dish: Gerald Combs <gerald@wireshark.org>
Tested-by: Petri Dish Buildbot
Reviewed-by: Anders Broman <a.broman58@gmail.com>

docbook/README.adoc

@@ -1,3 +1,5 @@
+
+:experimental:
 = Introduction
 
 This directory contains the source files needed to build the:
@@ -15,54 +17,11 @@ The guides and release notes are written in
 https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[Asciidoctor syntax].
 For more information see https://asciidoctor.org.
 
-Conversions from Asciidoctor markup to each of our supported output
-formats is done via the following steps:
-
-- HTML: Asciidoctor → DocBook XML → xsltproc + DocBook XSL
-- Chunked HTML: Asciidoctor → DocBook XML → xsltproc + DocBook XSL
-- PDF: Asciidoctor
-- HTMLHelp: Asciidoctor → DocBook XML → xsltproc + DocBook XSL → HHC
-- Text: [HTML output] → elinks
-
 = Requirements
 
-Ultimately we'd like to reduce the toolchain requirements to AsciidoctorJ
+Ultimately we'd like to reduce the toolchain requirements to AsciidoctorJ alone, but that's not yet possible.
-alone, but that's not yet possible. Additional tooling is required for
+Additional tooling is required for the HTML and HTMLHelp targets.
-the HTML and HTMLHelp targets. See the Developer's Guide for instructions
+See the https://www.wireshark.org/docs/wsdg_html_chunked/ChToolsDocumentationToolchain.html[Developer's Guide] for instructions on installing required packages for your platform.
-on installing required packages for your platform.
-
-== AsciidoctorJ (recommended) or Asciidoctor
-
-Text markup format and publishing toolchain:
-https://asciidoctor.org/
-
-AsciidoctorJ is a self-contained bundle which includes Asciidoctor and
-JRuby. It can be installed via Chocolatey on Windows, Homebrew on macOS,
-or a .zip extraction anywhere
-(https://bintray.com/asciidoctor/maven/asciidoctorj).
-
-== DocBook XML and XSL
-
-Converting from DocBook to HTML and CHM requires the DocBook DTD
-(http://www.sagehill.net/docbookxsl/ToolsSetup.html) and DocBook
-stylesheets
-(http://www.sagehill.net/docbookxsl/InstallStylesheets.html).
-These are available via installable packages on most Linux distributions,
-and Homebrew.
-
-== xsltproc
-
-http://xmlsoft.org/xslt/[xsltproc] converts DocBook XML to various
-formats based on XSL stylesheets. It either ships as part of the
-operating system or is available via an installable package on
-most Linux distributions.
-
-== HTML Help Workshop (Windows only)
-
-The HTML Help compiler is part of the
-https://www.microsoft.com/en-us/download/details.aspx?id=21138[HTML Help Workshop]
-from Microsoft. It is used to generate the documentation shipped with
-the Windows installers.
 
 = Asciidoctor Markup
 
@@ -79,7 +38,7 @@ Please use the following conventions when writing documentation:
 - Use Asciidoctor macros for buttons, keys, and menus. Note that these
   are currently experimental:
 
-** The button:[Start] button
+** The btn:[Start] button
 ** Press kbd:[Shift+Ctrl+P] to open the preferences dialog.
 ** Select menu:File[Open] from the main menu.
 

docbook/wsdg_src/WSDG_chapter_tools.adoc

@@ -455,6 +455,9 @@ Asciidoctor markup.
 Our various output formats are generated using the following tools.
 Intermediate formats are in _italics_.
 
+Man page roff:: pod2man
+Man page HTML:: pod2html
+
 Guide HTML:: Asciidoctor → _DocBook XML_ → xsltproc + DocBook XSL
 Guide PDF:: Asciidoctor
 Guide HTML Help:: Asciidoctor → _DocBook XML_ → xsltproc + DocBook XSL → HHC
@@ -470,21 +473,25 @@ JavaScript (Asciidoctor.js). Only the Asciidoctor and AsciidoctorJ
 flavors are supported for building the Wireshark documentation and
 AsciidoctorJ is recommended.
 
-The guides and release notes were originally written in DocBook (hence
+The guides and release notes were originally written in DocBook (hence the directory name).
-the directory name). They were later converted to AsciiDoc and then
+They were later converted to AsciiDoc and then migrated to Asciidoctor.
-migrated to Asciidoctor.
+We currently use Asciidoctor’s modern (>= 1.5.0) syntax.
-https://asciidoctor.org/docs/migration/[`compat-mode`] is currently
-enabled for the guides, but we are steadily migrating to Asciidoctor’s
-modern (>= 1.5.0) syntax.
 
 PDF output requires Asciidoctor PDF. It is included with AsciidoctorJ
 but _not_ with Asciidoctor.
 
-==== Xsltproc And DocBook
+==== DocBook XML and XSL
 
-The single HTML, chunked HTML, and HTML Help guides are generated using
+Converting from DocBook to HTML and CHM requires the DocBook DTD
-DocBook XSL stylesheets. They in turn require an XSLT processor. We use
+(http://www.sagehill.net/docbookxsl/ToolsSetup.html) and DocBook
-`xsltproc`.
+stylesheets
+(http://www.sagehill.net/docbookxsl/InstallStylesheets.html).
+These are available via installable packages on most Linux distributions, Chocolatey, and Homebrew.
+
+==== xsltproc
+
+http://xmlsoft.org/xslt/[xsltproc] converts DocBook XML to various formats based on XSL stylesheets.
+It either ships as part of the operating system or is available via an installable package on most Linux distributions, Chocolatey, and Homebrew.
 
 ==== HTML Help
 
@@ -507,7 +514,7 @@ since 2002).
 
 [[ChToolsDebugger]]
 
-==== Debugger
+=== Debugger
 
 Using a good debugger can save you a lot of development time.
 
@@ -516,7 +523,7 @@ otherwise the debugger will simply fail or you will only see a lot of garbage.
 
 [[ChToolsMSVCDebugger]]
 
-===== Visual Studio Integrated Debugger
+==== Visual Studio Integrated Debugger
 
 You can use the integrated debugger of Visual Studio if your toolchain includes
 it.  Open the solution in your build directory and build and debug as normal
@@ -559,7 +566,7 @@ If you require a non-optimised version, then build using a debug configuration.
 
 [[ChToolsMSDebuggingTools]]
 
-===== Debugging Tools For Windows
+==== Debugging Tools For Windows
 
 You can also use the Microsoft Debugging Tools for Windows toolkit, which is a
 standalone GUI debugger. Although it’s not that comfortable compared to