Switch from AsciiDoc to Asciidoctor.

Switch the markup text processor for files in the docbook directory from
AsciiDoc to Asciidoctor. Asciidoctor has several useful features (such
as direct PDF output) and is actively developed. It's written in Ruby
but that dependency can be sidestepped with AsciidoctorJ, a
self-contained bundle that only depends on the JRE.

The current toolchain targets require Python, AsciiDoc, DocBook XML,
DocBook XSL, Java, FOP, xsltproc, lynx, and the HTMLHelp compiler:

HTML: AsciiDoc → DocBook XML → xsltproc + DocBook XSL
Chunked HTML: AsciiDoc → DocBook XML → xsltproc + DocBook XSL
PDF: AsciiDoc → DocBook XML → xsltproc + DocBook XSL → FOP
HTMLHelp: AsciiDoc → DocBook XML → xsltproc + DocBook XSL → HHC

This change removes the AsciiDoc and FOP requirements and adds either
AsciidoctorJ or Asciidoctor + Ruby:

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

Ideally we could generate all of these using AsciidoctorJ, Java, and
lynx. Unfortunately we're not there yet.

The release notes depend on several macros (ws-buglink, ws-salink,
cve-idlink, sort-and-group). Add Asciidoctor (Ruby) equivalents.

Remove the BUILD_xxx_GUIDES CMake options and add various output targets
automatically. This means that you have to build the various documentation
targets explicitly.

Change-Id: I31930677a656b99b1c6839bb6c33a13db951eb9a
Reviewed-on: https://code.wireshark.org/review/25668
Petri-Dish: Gerald Combs <gerald@wireshark.org>
Tested-by: Petri Dish Buildbot
Reviewed-by: Gerald Combs <gerald@wireshark.org>

1 files changed, 274 insertions, 0 deletions

diff --git a/docbook/README.adoc b/docbook/README.adoc
new file mode 100644
index 0000000000..aa63ae0124
--- /dev/null
+++ b/docbook/README.adoc
@@ -0,0 +1,274 @@
+= Introduction
+
+This directory contains the source files needed to build the:
+
+- Wireshark User’s Guide
+- Wireshark Developer’s Guide
+- Release notes (NEWS)
+- Lua Reference
+
+To build everything, build the `all_guides` target, e.g. `ninja
+all_guides` or `msbuild all_guides.vcxproj`. Requirements are listed
+below.
+
+The guides and release notes are written in
+http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[Asciidoctor syntax].
+For more information see http://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
+alone, but that's not yet possible. Additional tooling is required for
+the HTML,
+
+== AsciidoctorJ (recommended) or Asciidoctor
+
+Text markup format and publishing toolchain:
+http://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.
+
+== Lynx
+
+https://invisible-island.net/lynx/[Lynx] is a text based web browser which can
+convert HTML to plain text. We may add w3m, elinks, or other alternatives
+in the future.
+
+== HTML Help Workshop (Windows only)
+
+The HTML Help compiler is part of the
+http://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
+
+The User’s and Developer’s Guides were originally written in DocBook and
+were later converted to http://asciidoc.org/[AsciiDoc]. We subsequently
+switched from AsciiDoc to Asciidoctor. As a result we currently use
+http://asciidoctor.org/docs/migration/[compat mode], but may switch
+to Asciidoctor’s modern markup at a later date.
+
+Please use the following conventions when writing documentation:
+
+- Window and dialog box names should be in “curly quotes”.
+
+- Use Asciidoctor macros for buttons, keys, and menus. Note that these
+  are currently experimental:
+
+-- The button:[Start] button
+-- Press kbd:[Shift+Ctrl+P] to open the preferences dialog.
+-- Select menu:File[Open] from the main menu.
+
+This ensures that UI elements are shown consistently and lets us apply styles
+to each type of element.
+
+- Command line examples should reflect the OS:
++
++++
+----
+$ echo Linux and UNIX
+----
+
+----
+C:\> echo Windows
+----
++++
+
+Admonitions ([NOTE], [TIP], and [WARNING]) can be used to highlight important
+information. Keep in mind that they interrupt the flow of text by design. Too
+many (especially in a row) are distracting and annoying.
+
+= HTML Help Alternatives
+
+Ideally we would ship documentation with Wireshark that is pleasant to
+read, browsable, and searchable. Unfortunately we don't have an easy way
+to do this. The closest we've been able to come is by shipping an HTML
+Help (.chm) file on Windows. However, HTML Help a) is limited to Windows,
+b) crusty on normal displays, and c) really crusty on HiDPI displays.
+
+The following alternative formats are available, each with advantages
+and disadvantages:
+
+== WebHelp
+
+https://en.wikipedia.org/wiki/Web_help[WebHelp] has three main
+dependencies:
+
+- DocBook XSL, including...
+- webhelpindexer.jar
+- The user's local web browser
+
+This format generates both HTML pages and JavaScript, which might not run
+reliably on end user machines.
+
+== PDF
+
+PDF output is page oriented, with static page sizes. This _usually_ isn't
+a problem with modern reader software. However it doesn't look like we
+can reliably load a PDF file and jump to specific section on some
+platforms. For example, loading +++file:///path/to/user_guide.pdf#location+++
+works in Firefox & Chrome, but not in Safari, Preview, or Internet Explorer.
+
+== Qt Help
+
+Qt provides an extensive http://doc.qt.io/qt-5/qthelp-framework.html[help system].
+However, to use it we need to generate a Qt Help Project (.qhp) file,
+which isn't currently supported by Asciidoctor or via DocBook XSL.
+
+The default help application (Qt Assistant) is ugly. We'd probably want
+to write our own help viewer app or integrate help directly via
+QHelpEngine.
+
+= Packages For Windows
+
+Installing the asciidoc package will pull in almost all the other required Cygwin packages.
+You may need to run "build-docbook-catalog" from a Cygwin bash prompt in order to register your catalog properly.
+
+Tool/File           Cygwin Package          Opt./Mand.  Comments
+---------           --------------          ----------  --------
+asciidoc            Doc/asciidoc            M           cygwin python is a dependency and will also be installed (if not installed)
+xsltproc:           Libs/libxslt            M
+xsl stylesheets:    Text/docbook-xsl        M           docbook.xsl, chunk.xsl and htmlhelp.xsl
+docbookx.dtd:       Text/docbook-xml42      M           a later version may be required (e.g. Doc/docbook-xml45), depending on your asciidoc installation
+docbookx.dtd:       Text/docbook-xml45      M           current asciidoc installations require this
+lynx:               Web/lynx                M
+dblatex             Text/dblatex            O           A number of dependencies will also be installed
+fop:                -                       O           URL: http://xml.apache.org/fop/ - install it into docbok\fop-1.x or wireshark_lib_dir\fop-1.x
+hhc:                -                       O           URL: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/hwMicrosoftHTMLHelpDownloads.asp
+zip:                Archive/zip             O
+getopt:             Base/util-linux         O           Required to run "build-docbook-catalog"
+
+
+Packages for Suse 9.3
+---------------------
+Tool/File           Package                 Opt./Mand.  Comments
+---------           -------                 ----------  --------
+xsltproc:           libxslt                 M
+xsl stylesheets:    docbook-xsl-stylesheets M           docbook.xsl and chunk.xsl
+docbookx.dtd:       docbook_4               M
+fop:                fop                     O
+
+
+Packages for Gentoo
+-------------------
+Like with all packages do ...
+Check dependencies: emerge -p <package>
+Install it:         emerge <package>
+
+Tool/File           Package                  Opt./Mand.   Comments
+---------           -------                  ----------   --------
+xsltproc:           libxslt                  M
+xsl stylesheets:    docbook-xsl-stylesheets  M            docbook.xsl and chunk.xsl
+                                                          Necessary docbook catalogs are built automatically by portage in /etc/xml and /etc/sgml
+                                                            docbook.xsl and chunk.xsl using "/usr/bin/build-docbook-catalog".
+                                                            So docbook runs out of the box on Gentoo.
+docbookx.dtd:       docbook-xml-dtd          M
+fop:                fop                      O            Has a lot of JAVA dependencies.
+Quanta+             quanta or kdewebdev      O            Nice HTML/XML/SGML and Docbook editor with Syntaxhighlighting, Autocompletion, etc.
+
+Tip: The actual DTD version of Gentoo is 4.4, but wireshark docs still use 4.2.
+     To be able to generate the docs, change the version in the second line of
+     developer-guide.xml or install an older version of the DTD.
+     See into the Gentoo handbook howto unmask old versions.
+
+
+Packages for Fedora
+-------------------
+Tool/File           Package                 Opt./Mand.  Comments
+---------           -------                 ----------  --------
+xsltproc:           libxslt                 M
+xsl stylesheets:    docbook-style-xsl       M           docbook.xsl and chunk.xsl
+docbookx.dtd:       docbook-dtds            M           provides v4.1, v4.2, v4.3, v4.4 DTDs
+asciidoc:           ascidoc                 M
+
+fop:                fop                     O           See above
+
+Note: There are required dependencies (such as xml-common and sgml-common);
+      yum is your friend for doing package installs including required
+      dependencies.
+
+
+Packages for Debian
+-------------------
+Tool/File           Package                 Opt./Mand.  Comments
+---------           -------                 ----------  --------
+xsltproc:           libxslt                 M
+xsl stylesheets:    docbook-xsl             M
+chunk.xsl:          docbook-xsl             M
+htmlhelp.xsl:       docbook-xsl             M
+docbookx.dtd:       docbook-xml             M
+fop:                fop                     O           See above
+
+
+
+Makefile:
+--------------------------
+There are several ways and tools to do these conversion, following is a short
+description of the way the makefile targets are doing things and which output
+files required for a release in that format.
+
+all
+Will generate both guides in all available output formats (see below).
+
+make wsug
+Will generate Wireshark User's Guide in all available output formats.
+
+make wsug_html
+The HTML file is generated using xsltproc and the XSL stylesheets from
+Norman Walsh. This is a conversion into a single HTML page.
+output: wsug_html
+
+make wsug_html_chunked
+The HTML files are generated using xsltproc and the XSL stylesheets from
+Norman Walsh. This is a conversion into chunked (multiple) HTML pages.
+output: wsug_html_chunked
+
+make wsug_pdf_us
+make wsug_pdf_a4
+The PDF is generated using an intermediate format named XSL-FO (XSL
+formatting objects). xsltproc converts the XML to a FO file, and then FOP
+(Apache's formatting object processor) is used to generate the PDF document,
+in US letter or A4 paper format.
+Tip: You will get lot's of INFO/WARNING/ERROR messages when generating PDF,
+but the conversion works just fine.
+output: user-guide-us.pdf user-guide-a4.pdf
+
+make wsug_chm
+On Win32 platforms, the "famous" HTML help format can be generated by using a
+special HTML chunked conversion and then use the htmlhelp compiler from
+Microsoft.
+output: htmlhelp.chm
+
+Using the prefix wsdg_ instead of wsug_ will build the same targets but for the
+Wireshark Developer's Guide.
+
+The makefile is written to be run with make on UNIX/Linux platforms.