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