4.6. Documentation Toolchain

Wireshark’s documentation is split across two directories. The doc directory contains man pages written in Perl’s POD (Plain Old Documentation) format. The docbook directory contains the User’s Guide, Developer’s Guide, and the release notes, which are written in Asciidoctor markup.

Our various output formats are generated using the following tools. Intermediate formats are in italics.

Man page roff
Man page HTML
Guide HTML
Asciidoctor → DocBook XML → xsltproc + DocBook XSL
Guide PDF
Guide HTML Help
Asciidoctor → DocBook XML → xsltproc + DocBook XSL → HHC
Release notes HTML
Release notes text
Asciidoctor → HTML → html2text.py

4.6.1. Asciidoctor

Asciidoctor comes in several flavors: a Ruby gem (Asciidoctor), a Java bundle (AsciidoctorJ), and transpiled 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 directory name). They were later converted to AsciiDoc and then migrated to Asciidoctor. We currently use Asciidoctor’s modern (>= 1.5.0) syntax.

PDF output requires Asciidoctor PDF. It is included with AsciidoctorJ but not with Asciidoctor.

4.6.2. 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, Chocolatey, and Homebrew.

4.6.3. xsltproc

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.

4.6.4. HTML Help

HTML Help is used to create the User’s and Developer’s Guide in .chm format. The User’s Guide .chm file is included with the NSIS and WiX installers and is used as Wireshark’s built-in help on Windows.

This compiler is used to generate a .chm file from a bunch of HTML files — in our case to generate the User’s and Developer’s Guide in .chm format.

The compiler is only available as the free (as in beer) "HTML Help Workshop" download. If you want to compile the guides yourself, you need to download and install this. If you don’t install it into the default directory, you may also have a look at the HHC_DIR setting in the file docbook/Makefile.

The files htmlhelp.c and htmlhelp.lib are required to be able to open .chm files from Wireshark and show the online help. Both files are part of the SDK (standalone (P)SDK or MSVC since 2002).