forked from osmocom/wireshark
e1d9a226a2
The static arrays are supposed to be arrays of const pointers to int, not arrays of non-const pointers to const int. Fixing that means some bugs (scribbling on what's *supposed* to be a const array) will be caught (see packet-ieee80211-radiotap.c for examples, the first of which inspired this change and the second of which was discovered while testing compiles with this change), and removes the need for some annoying casts. Also make some of those arrays static while we're at it. Update documentation and dissector-generator tools. Change-Id: I789da5fc60aadc15797cefecfd9a9fbe9a130ccc Reviewed-on: https://code.wireshark.org/review/37517 Petri-Dish: Guy Harris <gharris@sonic.net> Tested-by: Petri Dish Buildbot Reviewed-by: Anders Broman <a.broman58@gmail.com> |
||
|---|---|---|
| .. | ||
| asciidoctor-macros | ||
| common_graphics | ||
| common_src | ||
| wsdg_graphics | ||
| wsdg_src | ||
| wsug_graphics | ||
| wsug_src | ||
| CMakeLists.txt | ||
| README.adoc | ||
| attributes.adoc | ||
| custom_layer_chm.xsl | ||
| custom_layer_single_html.xsl | ||
| developer-guide-docinfo.xml | ||
| developer-guide.adoc | ||
| faq.adoc | ||
| make-wsluarm.pl | ||
| release-notes.adoc | ||
| user-guide-docinfo.xml | ||
| user-guide.adoc | ||
| ws.css | ||
| wsluarm.adoc | ||
README.adoc
: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], 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. == 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.