forked from osmocom/wireshark
137 lines
4.7 KiB
Plaintext
137 lines
4.7 KiB
Plaintext
|
||
:experimental:
|
||
= Introduction
|
||
|
||
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
|
||
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. As a result we currently use
|
||
https://asciidoctor.org/docs/migration/[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 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`:
|
||
|
||
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 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
|
||
|
||
https://en.wikipedia.org/wiki/Web_help[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
|
||
|
||
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 https://doc.qt.io/qt-5/qthelp-framework.html[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.
|