:experimental:
= Introduction

This directory contains the source files needed to build the:

- Wireshark User’s Guide
- Wireshark Developer’s Guide
- Release notes
- 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
https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[Asciidoctor syntax].
For more information see https://asciidoctor.org.

== 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 and HTMLHelp targets.
See the https://www.wireshark.org/docs/wsdg_html_chunked/ChToolsDocumentationToolchain.html[Developer's Guide] for instructions on installing required packages for your platform.

== Asciidoctor Markup

The User’s and Developer’s Guides were originally written in DocBook and
were later converted to https://asciidoc.org/[AsciiDoc]. We subsequently
switched from AsciiDoc to Asciidoctor.
We currently use Asciidoctor’s modern (>= 1.5.0) syntax.

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 btn:[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], [IMPORTANT], [CAUTION] 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.

== Custom Asciidoctor Macros

The following custom macros are available in `doc/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.

== Asciidoctor Live Preview

The Asciidoctor project provides a JavaScript version of Asciidoctor
(asciidoctor.js), which enables live previews in many web browsers and
text editors. See the
https://asciidoctor.org/docs/editing-asciidoc-with-live-preview/[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 the `experimental` attribute to your Live Preview settings.