diff options
Diffstat (limited to 'docbook/README.adoc')
| -rw-r--r-- | docbook/README.adoc | 136 |
1 files changed, 136 insertions, 0 deletions
diff --git a/docbook/README.adoc b/docbook/README.adoc new file mode 100644 index 00000000..58d08edf --- /dev/null +++ b/docbook/README.adoc @@ -0,0 +1,136 @@ + +: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. |