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 Asciidoctor syntax. For more information see https://asciidoctor.org.

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 and HTMLHelp targets. See the Developer’s Guide for instructions on installing required packages for your platform.

The User’s and Developer’s Guides were originally written in DocBook and were later converted to AsciiDoc. We subsequently switched from AsciiDoc to Asciidoctor. As a result we currently use 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 Start button

  • Press Shift+Ctrl+P to open the preferences dialog.

  • Select 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.

The following custom macros are available in docbook/asciidoctor-macros:

commaize-block

Sorts a list of items and separates them with commas with an "and" preceding the last item.

cveidlink-inline-macro

Links a CVE ID to cve.mitre.org.

manarg-block

Ensures that individual arguments don’t wrap in order to improve readability.

wsbuglink-inline-macro

Links an issue number to gitlab.org/wireshark/wireshark/-/issues.

wssalink-inline-macro

Links a security advisory to www.wireshark.org.

The Asciidoctor project provides a JavaScript version of Asciidoctor (asciidoctor.js), which enables live previews in many web browsers and text editors. See the Live Preview documentation for more information.

Note that our documentation depends on attributes defined in attributes.adoc. The User’s Guide and Developer’s Guide are split across several files, and only the top-level user-guide.adoc and developer-guide.adoc include attributes.adoc. As a result, some markup will be incomplete. You can work around this somewhat by adding some attributes such as compat-mode experimental to your Live Preview settings.

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 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:https:///path/to/user_guide.pdf#location works in Firefox & Chrome, but not in Safari, Preview, or Internet Explorer.

Qt provides an extensive 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.