wireshark/docbook
Gerald Combs 84ab55cf75 Docs+Packaging: Convert our man pages to Asciidoctor.
Convert doc/*.pod to Asciidoctor. This:

* Means we use the same markup for our man pages, the guides, and
  release notes.
* Lets us add versions to our man pages.
* Gives us more formatting options, e.g. AsciiDoc supports `commands`,
  nested lists and makes it easy to include version information. The
  manpage backend doesn't seem to support tables very well,
  unfortunately.

Convert our CMake configuration to produce *roff and html man pages
using Asciidoctor. Add a "manarg" block macro which makes our synopses
wrap correctly.

Similar to the release notes, guides, and FAQ, if Asciidoctor isn't
found the man pages won't be generated or installed.

Move Asciidoctor to the list of package build dependencies in various
places.

This commit includes the conversion script (pod2adoc.py), which will be
removed later.

Line count sanity check:

Man page         .pod .adoc
androiddump       260  280
asn2deb            93  105
capinfos          401  471
captype            54   55
ciscodump         241  269
dftest             42   42
dpauxmon          153  169
dumpcap           464  534
editcap           528  583
etwdump           136  156
extcap            157  181
idl2deb            91  103
idl2wrs           120  100
mergecap          206  207
mmdbresolve        75   75
randpkt           107  111
randpktdump       158  184
rawshark          558  610
reordercap         76   78
sdjournal         145  157
sshdump           272  302
text2pcap         274  312
tshark           2135 2360
udpdump           133  151
wireshark-filter  486  479
wireshark        2967 3420
2021-10-01 16:42:34 +00:00
..
asciidoctor-macros Docs+Packaging: Convert our man pages to Asciidoctor. 2021-10-01 16:42:34 +00:00
common_graphics
common_src Fix more spelling errors in the docbook folder. 2020-09-06 12:11:09 +00:00
wsdg_graphics EPUB: Replace cover pages 2021-08-03 19:42:02 +00:00
wsdg_src Docs+Packaging: Convert our man pages to Asciidoctor. 2021-10-01 16:42:34 +00:00
wsug_graphics EPUB: Replace cover pages 2021-08-03 19:42:02 +00:00
wsug_src documentation: Add absolute time to user guide 2021-09-30 16:44:22 +00:00
CMakeLists.txt Tools: Migrate compress-pngs.sh to Python. 2021-09-13 11:00:04 -07:00
README.adoc Docs+Packaging: Convert our man pages to Asciidoctor. 2021-10-01 16:42:34 +00:00
attributes.adoc Version: 3.5.0 → 3.5.1. 2021-08-27 21:40:12 +00:00
custom_layer_single_html.xsl Switch from AsciiDoc to Asciidoctor. 2018-02-11 18:22:09 +00:00
developer-guide-docinfo.xml Version: 3.3.0 → 3.5.0. 2020-10-22 19:15:42 +00:00
developer-guide.adoc EPUB: Add cover page and some document meta data 2021-08-03 19:42:02 +00:00
faq.adoc FAQ: Add items about forms and contracts. 2021-08-25 17:01:21 +00:00
make-wsluarm.pl wslua: Fix generate doc for WSLUA_ATTRIBUTE 2020-10-22 13:55:22 +00:00
release-notes.adoc COSE dissector from dtn-wireshark project 2021-09-29 08:51:13 +00:00
user-guide-docinfo.xml Version: 3.3.0 → 3.5.0. 2020-10-22 19:15:42 +00:00
user-guide.adoc EPUB: Add cover page and some document meta data 2021-08-03 19:42:02 +00:00
ws.css docbook: Fix our admon image widths. 2021-07-16 07:00:45 +00:00
wsluarm.adoc wslua: expose some libwiretap APIs in Lua. 2021-02-12 21:25:29 -08: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.

:experimental:
= 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.

== 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 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 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.

== 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 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.