Docs: Updates for xsltproc and Asciidoctor.
Change-Id: I3cfe2121beaab0fe09228ec277997d68fe824693 Reviewed-on: https://code.wireshark.org/review/26281 Reviewed-by: Gerald Combs <gerald@wireshark.org>
This commit is contained in:
parent
f52bb2bf27
commit
99240e62bf
|
@ -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
|
||||
|
||||
|
|
|
@ -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.
|
||||
|
||||
=== 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
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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 and
|
||||
to show the User’s Guide as the Wireshark "Online Help".
|
||||
|
||||
Both features are currently optional, and might be removed in future versions.
|
||||
|
||||
===== HTML Help Compiler (hhc.exe)
|
||||
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).
|
||||
|
|
Loading…
Reference in New Issue