54b895df4e
1. Update documentation to point to doc\all_guides.vcxproj 2. Add fonts that asciidoctor-pdf build required to not fail. 3. Fix build errors with removal of some bracketed text Fixes #20528
98 lines
3.4 KiB
Plaintext
98 lines
3.4 KiB
Plaintext
|
||
: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.
|