You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
João Valverde 91366f56f2
WSDG: Minor logging documentation enhancements
1 month ago
asciidoctor-macros Docs+Packaging: Convert our man pages to Asciidoctor. 2 years ago
common_src Docs: Rename our guide source files 2 months ago
wsdg_src WSDG: Minor logging documentation enhancements 1 month ago
wsug_src doc: Remove stray word in statistics chapter 1 month ago
CMakeLists.txt Docbook: Reorganize our guide directories 1 month ago
README.adoc WSDG/WSUG: add missing asciidoc admonition icons 1 year ago
attributes.adoc WSUG: (PDF) add fallback font for missing up/down arrows 4 months ago
custom_layer_single_html.xsl Switch from AsciiDoc to Asciidoctor. 5 years ago
faq.adoc FAQ: Fix some markup 2 months ago
logray-quick-start.adoc Rename Logwolf to Logray 9 months ago docbook: Add file comments to wsluarm. 8 months ago
release-notes.adoc Enable rpathification and working relocation on Linux (take 3) 1 month ago
ws.css docbook: Fix our admon image widths. 2 years ago


This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

= Introduction

This directory contains the source files needed to build the:

- Wireshark Users Guide
- Wireshark Developers 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

The guides and release notes are written in[Asciidoctor syntax].
For more information see

== 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[Developer's Guide] for instructions on installing required packages for your platform.

== Asciidoctor Markup

The Users and Developers 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 Asciidoctors 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 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 `docbook/asciidoctor-macros`:

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

Links a CVE ID to

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

Links an issue number to

Links a security advisory to

== 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[Live
Preview] documentation for more information.

Note that our documentation depends on attributes defined in
_attributes.adoc_. The Users Guide and Developers 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.

= HTML Help Alternatives

Ideally we would ship documentation with Wireshark that is pleasant to
read, browsable, and searchable. Unfortunately we don't have an easy way
to do this. The closest we've been able to come is by shipping an HTML
Help (.chm) file on Windows. However, HTML Help a) is limited to Windows,
b) crusty on normal displays, and c) really crusty on HiDPI displays.

The following alternative formats are available, each with advantages
and disadvantages:

== WebHelp[WebHelp] has three main

- 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

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

== Qt Help

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