wireshark/docbook
Huang Qiangxiong 623b347d1e Protobuf: add dissecting protobuf fields as wireshark fields preferences, etc.
Two enhancements and one fixed bug:

1. Add dissecting protobuf fields as wireshark (header) fields preferences. User
can input the full names of protobuf fields or messages in Filter toolbar for
searching.

2. Add 'protobuf_field' dissector table. Dissector based on protobuf can register
itself to 'protobuf_field' keyed with the full names of fields of BYETS or STRING
types.

3. A bug about search MESSAGE or ENUM type in context is fixed.

4. Another small enhancement is adding prefs_set_preference_effect_fields() which
can mark a preference that affects fields change (triggering FieldsChanged event).

See the linked bug for sample capture file and .proto files.

Ping-Bug: 16209
Change-Id: Ibc3c45a6d596a8bb983b0d847dd6a22801af7e04
Reviewed-on: https://code.wireshark.org/review/35111
Petri-Dish: Alexis La Goutte <alexis.lagoutte@gmail.com>
Tested-by: Petri Dish Buildbot
Reviewed-by: Peter Wu <peter@lekensteyn.nl>
Reviewed-by: Anders Broman <a.broman58@gmail.com>
2019-12-19 05:04:17 +00:00
..
asciidoctor-macros Revert "docbook: remove equivalent case." 2018-06-27 17:07:37 +00:00
common_graphics Convert admon graphics to SVG. 2014-08-24 02:56:35 +00:00
common_src docbook: put a space after PS prompts. 2019-11-27 01:35:58 +00:00
wsdg_graphics Recompress PNGs. 2016-06-30 15:41:32 +00:00
wsdg_src WSUG+WSDG: Remove description list formatting. 2019-12-14 19:51:22 +00:00
wsug_graphics WSUG: Update the Expert Information and Status Bar docs. 2019-12-17 05:10:44 +00:00
wsug_src WSUG: Update the Expert Information and Status Bar docs. 2019-12-17 05:10:44 +00:00
CMakeLists.txt WSUG: Update the Expert Information and Status Bar docs. 2019-12-17 05:10:44 +00:00
README.adoc Documentation: convert http URLS to https 2019-07-20 20:51:30 +00:00
attributes.adoc WSUG: Export, packet range+format, and other IO chapter updates. 2019-12-09 05:09:18 +00:00
custom_layer_chm.xsl CMake+docbook: Fixup our .chm titles. 2019-11-08 20:27:15 +00:00
custom_layer_single_html.xsl Switch from AsciiDoc to Asciidoctor. 2018-02-11 18:22:09 +00:00
developer-guide-docinfo.xml 3.1.0 → 3.3.0. 2019-11-20 23:33:02 +00:00
developer-guide.adoc Rename our .asciidoc files to .adoc 2019-02-15 05:17:26 +00:00
faq.adoc FAQ: Update and remove entries. 2019-12-17 05:06:53 +00:00
make-wsluarm.pl Rename our .asciidoc files to .adoc 2019-02-15 05:17:26 +00:00
release-notes.adoc Protobuf: add dissecting protobuf fields as wireshark fields preferences, etc. 2019-12-19 05:04:17 +00:00
user-guide-docinfo.xml 3.1.0 → 3.3.0. 2019-11-20 23:33:02 +00:00
user-guide.adoc Rename our .asciidoc files to .adoc 2019-02-15 05:17:26 +00:00
ws.css doc+docbook: Add .guisubmenu. 2019-08-15 17:55:08 +00:00
wsluarm.adoc Documentation: convert http URLS to https 2019-07-20 20:51:30 +00:00

README.adoc

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

= Introduction

This directory contains the source files needed to build the:

- Wireshark Users Guide
- Wireshark Developers 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.

Conversions from Asciidoctor markup to each of our supported output
formats is done via the following steps:

- HTML: Asciidoctor → DocBook XML → xsltproc + DocBook XSL
- Chunked HTML: Asciidoctor → DocBook XML → xsltproc + DocBook XSL
- PDF: Asciidoctor
- HTMLHelp: Asciidoctor → DocBook XML → xsltproc + DocBook XSL → HHC
- Text: [HTML output] → elinks

= 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 Developer's Guide for instructions
on installing required packages for your platform.

== AsciidoctorJ (recommended) or Asciidoctor

Text markup format and publishing toolchain:
https://asciidoctor.org/

AsciidoctorJ is a self-contained bundle which includes Asciidoctor and
JRuby. It can be installed via Chocolatey on Windows, Homebrew on macOS,
or a .zip extraction anywhere
(https://bintray.com/asciidoctor/maven/asciidoctorj).

== DocBook XML and XSL

Converting from DocBook to HTML and CHM requires the DocBook DTD
(http://www.sagehill.net/docbookxsl/ToolsSetup.html) and DocBook
stylesheets
(http://www.sagehill.net/docbookxsl/InstallStylesheets.html).
These are available via installable packages on most Linux distributions,
and Homebrew.

== xsltproc

http://xmlsoft.org/xslt/[xsltproc] converts DocBook XML to various
formats based on XSL stylesheets. It either ships as part of the
operating system or is available via an installable package on
most Linux distributions.

== HTML Help Workshop (Windows only)

The HTML Help compiler is part of the
https://www.microsoft.com/en-us/download/details.aspx?id=21138[HTML Help Workshop]
from Microsoft. It is used to generate the documentation shipped with
the Windows installers.

= Asciidoctor Markup

The Users and Developers 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 Asciidoctors 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 button:[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 Users Guide and Developers 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.