Docs: Updates for xsltproc and Asciidoctor.
authorGerald Combs <gerald@wireshark.org>
Tue, 6 Mar 2018 16:30:42 +0000 (08:30 -0800)
committerGerald Combs <gerald@wireshark.org>
Tue, 6 Mar 2018 19:03:46 +0000 (19:03 +0000)
Change-Id: I3cfe2121beaab0fe09228ec277997d68fe824693
Reviewed-on: https://code.wireshark.org/review/26281
Reviewed-by: Gerald Combs <gerald@wireshark.org>
docbook/wsdg_src/WSDG_chapter_quick_setup.asciidoc
docbook/wsdg_src/WSDG_chapter_tools.asciidoc

index 75e7674b48919ccecabfa82fb4e2b4b2b8d33a9b..28bce1f5aaf39bc94dd8e57aac26ad19a1042543 100644 (file)
@@ -42,7 +42,7 @@ Known traps are:
 
 [[ChSetupChocolatey]]
 
 
 [[ChSetupChocolatey]]
 
-==== Optional: Install Chocolatey
+==== Recommended: Install Chocolatey
 
 https://chocolatey.org/[Chocolatey] is a native package manager for Windows.
 There are https://chocolatey.org/packages[packages] for most of the software
 
 https://chocolatey.org/[Chocolatey] is a native package manager for Windows.
 There are https://chocolatey.org/packages[packages] for most of the software
@@ -125,13 +125,16 @@ upgrade Qt to newer versions.
 
 [[ChSetupCygwin]]
 
 
 [[ChSetupCygwin]]
 
-==== Install Cygwin
+==== Optional: Install Cygwin
 
 On 32-bit Windows, http://www.cygwin.com/setup-x86.exe[download the
 32-bit Cygwin installer] and start it. On 64-bit Windows,
 http://www.cygwin.com/setup-x86_64.exe[download the 64-bit Cygwin
 installer] and start it.
 
 
 On 32-bit Windows, http://www.cygwin.com/setup-x86.exe[download the
 32-bit Cygwin installer] and start it. On 64-bit Windows,
 http://www.cygwin.com/setup-x86_64.exe[download the 64-bit Cygwin
 installer] and start it.
 
+Over time the Wireshark development toolchain has been migrating away from Cygwin
+toward native tools and we hope to eliminate it as a requirement someday.
+
 At the "Select Packages" page, you'll need to select
 some additional packages which are not installed by default.
 Navigate to the required Category/Package row and, if the package
 At the "Select Packages" page, you'll need to select
 some additional packages which are not installed by default.
 Navigate to the required Category/Package row and, if the package
@@ -281,17 +284,21 @@ Chocolatey ensures cmake.exe is on your path.
 
 [[ChSetupAsciidoctor]]
 
 
 [[ChSetupAsciidoctor]]
 
-==== Install Asciidoctor
+==== Install Asciidoctor, Xsltproc, And DocBook
 
 http://asciidoctor.org/[Asciidoctor] can be run directly as a Ruby
 
 http://asciidoctor.org/[Asciidoctor] can be run directly as a Ruby
-script or via a Java wrapper (AsciidoctorJ). The easiest way to install
-it on Windows is via Chocolatey:
+script or via a Java wrapper (AsciidoctorJ). It is used in conjuntion
+with Xsltproc and DocBook to generate the documenation you're reading
+and the User’s Guide.
+
+The easiest way to install them on Windows is via Chocolatey:
 
 ----
 
 ----
-PS$>choco install asciidoctorj
+PS$>choco install asciidoctorj xsltproc docbook-bundle
 ----
 
 ----
 
-Chocolatey ensures that asciidoctorj.exe is on your path.
+Chocolatey ensures that asciidoctorj.exe and xsltproc.exe is on your
+path and that xsltproc uses the DocBook catalog.
 
 ==== Install and Prepare Sources
 
 
 ==== Install and Prepare Sources
 
index f3b0d0145c3869ceae114b88c4fd558bb0e813f5..ed7705ad030c6d326ee833b75a2dd9ebe7057b8c 100644 (file)
@@ -591,7 +591,7 @@ is used (this produces the smallest package).
 
 The Windows Platform SDK (PSDK) or Windows SDK is a free
 (as in beer) download and contains platform specific headers and
 
 The Windows Platform SDK (PSDK) or Windows SDK is a free
 (as in beer) download and contains platform specific headers and
-libraries (e.g. _windows.h_, _WSock32.lib_, etc.). As new Windows
+libraries (e.g. `windows.h`, `WSock32.lib`, etc.). As new Windows
 features evolve in time, updated SDK’s become available that
 include new and updated APIs.
 
 features evolve in time, updated SDK’s become available that
 include new and updated APIs.
 
@@ -605,14 +605,53 @@ Older versions of the SDK should also work. However, the
 command to set the environment settings will be different, try
 search for SetEnv.* in the SDK directory.
 
 command to set the environment settings will be different, try
 search for SetEnv.* in the SDK directory.
 
-==== HTML Help
+=== Documentation Toolchain
+
+Wireshark’s documentation is split across two directories. The `doc`
+directory contains man pages written in Perl’s POD (Plain Old
+Documentation) format. The `docbook` directory contains the User’s
+Guide, Developer’s Guide, and the release notes, which are written in
+Asciidoctor markup.
+
+Our various output formats are generated using the following tools.
+Intermediate formats are in _italics_.
+
+Guide HTML:: Asciidoctor → _DocBook XML_ → xsltproc + DocBook XSL
+Guide PDF:: Asciidoctor
+Guide HTML Help:: Asciidoctor → _DocBook XML_ → xsltproc + DocBook XSL → HHC
+
+Release notes HTML:: Asciidoctor
+Release notes text:: Asciidoctor → _HTML_ → html2text.py
+
+==== Asciidoctor
 
 
-HTML Help is used to create the User’s and Developer’s Guide in .chm format and
-to show the User’s Guide as the Wireshark "Online Help".
+Asciidoctor[https://asciidoctor.org/] comes in several flavors: a Ruby
+gem (Asciidoctor), a Java bundle (AsciidoctorJ), and transpiled
+JavaScript (Asciidoctor.js). Only the Asciidoctor and AsciidoctorJ
+flavors are supported for building the Wireshark documentation and
+AsciidoctorJ is recommended.
 
 
-Both features are currently optional, and might be removed in future versions.
+The guides and release notes were originally written in DocBook (hence
+the directory name). They were later converted to AsciiDoc and then
+migrated to Asciidoctor.
+`compat-mode`[https://asciidoctor.org/docs/migration/] is currently
+enabled for the guides, but we are steadily migrating to Asciidoctor’s
+modern (>= 1.5.0) syntax.
 
 
-===== HTML Help Compiler (hhc.exe)
+PDF output requires Asciidoctor PDF. It is included with AsciidoctorJ
+but _not_ with Asciidoctor.
+
+==== Xsltproc And DocBook
+
+The single HTML, chunked HTML, and HTML Help guides are generated using
+DocBook XSL stylesheets. They in turn require an XSLT processor. We use
+`xsltproc`.
+
+==== HTML Help
+
+HTML Help is used to create the User’s and Developer’s Guide in .chm format.
+The User’s Guide .chm file is included with the NSIS and WiX installers and
+is used as Wireshark's built-in help on Windows.
 
 This compiler is used to generate a .chm file from a bunch of HTML files -- in
 our case to generate the User’s and Developer’s Guide in .chm format.
 
 This compiler is used to generate a .chm file from a bunch of HTML files -- in
 our case to generate the User’s and Developer’s Guide in .chm format.
@@ -622,9 +661,7 @@ download. If you want to compile the guides yourself, you need to download and
 install this. If you don't install it into the default directory, you may also
 have a look at the HHC_DIR setting in the file docbook/Makefile.
 
 install this. If you don't install it into the default directory, you may also
 have a look at the HHC_DIR setting in the file docbook/Makefile.
 
-===== HTML Help Build Files (htmlhelp.c / htmlhelp.lib)
-
-The files _htmlhelp.c_ and _htmlhelp.lib_ are required to
+The files `htmlhelp.c` and `htmlhelp.lib` are required to
 be able to open .chm files from Wireshark and show the
 online help. Both files are part of the SDK (standalone (P)SDK or MSVC
 since 2002).
 be able to open .chm files from Wireshark and show the
 online help. Both files are part of the SDK (standalone (P)SDK or MSVC
 since 2002).