4.6. Documentation Toolchain
Prev | Chapter 4. Tool Reference | Next

## 4.6. Documentation Toolchain

Wireshark’s documentation is split across two directories. The `doc` directory contains man pages, 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
  Asciidoctor
Man page HTML
  Asciidoctor
Guide HTML
  Asciidoctor → DocBook XML → xsltproc + DocBook XSL
Guide PDF
  Asciidoctor
Release notes HTML
  Asciidoctor
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). The Ruby and Java flavors can be used to build Wireshark’s documentation, but the JavaScript flavor doesn’t support all of the features that we require. CMake will download a pre-built version of Ruby and the Asciidoctor gem on Windows.

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. The man pages were originally in Perl’s POD (Plain Old Documentation) format and were later converted to Asciidoctor. We use Asciidoctor’s modern (>= 1.5.0) syntax.

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

### 4.6.2. DocBook XML and XSL

Converting from DocBook to HTML 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.

Prev | Up | Next
4.5. Microsoft compiler toolchain (Windows native) | Home | 4.7. Debugger