: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 doc\all_guides.vcxproj`. Requirements are listed
below.

All of the documentation in this directory is written in
https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[Asciidoctor syntax].
For more information see https://asciidoctor.org.

== Requirements

See the https://www.wireshark.org/docs/wsdg_html_chunked/ChToolsDocumentationToolchain.html[Developer's Guide] for instructions on installing required packages for your platform.
Ultimately we'd like to reduce the toolchain requirements to Asciidoctor alone, but that's not yet possible.
Additional tooling is required for the HTML targets.

== Markup and Typographic Conventions

In order to keep the markup for filenames, commands, and other content consistent, please follow the guidelines in __common_src/typographic_conventions.adoc__.

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 require the `:experimental:` attribute:

** 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.

== Historical Notes

The User’s and Developer’s Guides were originally written in DocBook and were later converted to https://asciidoc.org/[AsciiDoc].
The AsciiDoc markup has been modernized over time and we migrated our documentation toolchain to Asciidoctor.