diff options
author | Gerald Combs <gerald@wireshark.org> | 2018-03-06 08:30:42 -0800 |
---|---|---|
committer | Gerald Combs <gerald@wireshark.org> | 2018-03-06 19:03:46 +0000 |
commit | 99240e62bfad757cd50ac0fc38ce6e75ea3debc0 (patch) | |
tree | dfeb03055055c5434a5d5ace8ad4c72ab4266f9e /docbook/wsdg_src | |
parent | f52bb2bf27cc55285398bbf6acb1884b10b8d3a4 (diff) |
Docs: Updates for xsltproc and Asciidoctor.
Change-Id: I3cfe2121beaab0fe09228ec277997d68fe824693
Reviewed-on: https://code.wireshark.org/review/26281
Reviewed-by: Gerald Combs <gerald@wireshark.org>
Diffstat (limited to 'docbook/wsdg_src')
-rw-r--r-- | docbook/wsdg_src/WSDG_chapter_quick_setup.asciidoc | 21 | ||||
-rw-r--r-- | docbook/wsdg_src/WSDG_chapter_tools.asciidoc | 55 |
2 files changed, 60 insertions, 16 deletions
diff --git a/docbook/wsdg_src/WSDG_chapter_quick_setup.asciidoc b/docbook/wsdg_src/WSDG_chapter_quick_setup.asciidoc index 75e7674b48..28bce1f5aa 100644 --- a/docbook/wsdg_src/WSDG_chapter_quick_setup.asciidoc +++ b/docbook/wsdg_src/WSDG_chapter_quick_setup.asciidoc @@ -42,7 +42,7 @@ Known traps are: [[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 @@ -125,13 +125,16 @@ upgrade Qt to newer versions. [[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. +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 @@ -281,17 +284,21 @@ Chocolatey ensures cmake.exe is on your path. [[ChSetupAsciidoctor]] -==== Install Asciidoctor +==== Install Asciidoctor, Xsltproc, And DocBook 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 diff --git a/docbook/wsdg_src/WSDG_chapter_tools.asciidoc b/docbook/wsdg_src/WSDG_chapter_tools.asciidoc index f3b0d0145c..ed7705ad03 100644 --- a/docbook/wsdg_src/WSDG_chapter_tools.asciidoc +++ b/docbook/wsdg_src/WSDG_chapter_tools.asciidoc @@ -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 -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. @@ -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. -==== 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. @@ -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. -===== 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). |