diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/README.documentation.adoc (renamed from docbook/README.adoc) | 53 |
1 files changed, 5 insertions, 48 deletions
diff --git a/docbook/README.adoc b/doc/README.documentation.adoc index 58d08edf..850a870a 100644 --- a/docbook/README.adoc +++ b/doc/README.documentation.adoc @@ -6,7 +6,7 @@ This directory contains the source files needed to build the: - Wireshark User’s Guide - Wireshark Developer’s Guide -- Release notes (NEWS) +- Release notes - Lua Reference To build everything, build the `all_guides` target, e.g. `ninja @@ -27,9 +27,8 @@ See the https://www.wireshark.org/docs/wsdg_html_chunked/ChToolsDocumentationToo 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. +switched from AsciiDoc to Asciidoctor. +We currently use Asciidoctor’s modern (>= 1.5.0) syntax. Please use the following conventions when writing documentation: @@ -61,7 +60,7 @@ many (especially in a row) are distracting and annoying. == Custom Asciidoctor Macros -The following custom macros are available in `docbook/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. @@ -91,46 +90,4 @@ _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. +adding the `experimental` attribute to your Live Preview settings. |