osmocom
/
wireshark
11
0
Fork 1
Code Issues Pull Requests Projects Releases Wiki Activity
wireshark/docbook/README.adoc

275 lines
11 KiB
Plaintext
Raw Blame History

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 User’s Guide
- Wireshark Developer’s 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
http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[Asciidoctor syntax].
For more information see http://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,
== AsciidoctorJ (recommended) or Asciidoctor
Text markup format and publishing toolchain:
http://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.
== Lynx
https://invisible-island.net/lynx/[Lynx] is a text based web browser which can
convert HTML to plain text. We may add w3m, elinks, or other alternatives
in the future.
== HTML Help Workshop (Windows only)
The HTML Help compiler is part of the
http://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 User’s and Developer’s Guides were originally written in DocBook and
were later converted to http://asciidoc.org/[AsciiDoc]. We subsequently
switched from AsciiDoc to Asciidoctor. As a result we currently use
http://asciidoctor.org/docs/migration/[compat mode], but may switch
to Asciidoctor’s 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.
= 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 http://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.
= Packages For Windows
Installing the asciidoc package will pull in almost all the other required Cygwin packages.
You may need to run "build-docbook-catalog" from a Cygwin bash prompt in order to register your catalog properly.
Tool/File Cygwin Package Opt./Mand. Comments
--------- -------------- ---------- --------
asciidoc Doc/asciidoc M cygwin python is a dependency and will also be installed (if not installed)
xsltproc: Libs/libxslt M
xsl stylesheets: Text/docbook-xsl M docbook.xsl, chunk.xsl and htmlhelp.xsl
docbookx.dtd: Text/docbook-xml42 M a later version may be required (e.g. Doc/docbook-xml45), depending on your asciidoc installation
docbookx.dtd: Text/docbook-xml45 M current asciidoc installations require this
lynx: Web/lynx M
dblatex Text/dblatex O A number of dependencies will also be installed
fop: - O URL: http://xml.apache.org/fop/ - install it into docbok\fop-1.x or wireshark_lib_dir\fop-1.x
hhc: - O URL: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/hwMicrosoftHTMLHelpDownloads.asp
zip: Archive/zip O
getopt: Base/util-linux O Required to run "build-docbook-catalog"
Packages for Suse 9.3
---------------------
Tool/File Package Opt./Mand. Comments
--------- ------- ---------- --------
xsltproc: libxslt M
xsl stylesheets: docbook-xsl-stylesheets M docbook.xsl and chunk.xsl
docbookx.dtd: docbook_4 M
fop: fop O
Packages for Gentoo
-------------------
Like with all packages do ...
Check dependencies: emerge -p <package>
Install it: emerge <package>
Tool/File Package Opt./Mand. Comments
--------- ------- ---------- --------
xsltproc: libxslt M
xsl stylesheets: docbook-xsl-stylesheets M docbook.xsl and chunk.xsl
Necessary docbook catalogs are built automatically by portage in /etc/xml and /etc/sgml
docbook.xsl and chunk.xsl using "/usr/bin/build-docbook-catalog".
So docbook runs out of the box on Gentoo.
docbookx.dtd: docbook-xml-dtd M
fop: fop O Has a lot of JAVA dependencies.
Quanta+ quanta or kdewebdev O Nice HTML/XML/SGML and Docbook editor with Syntaxhighlighting, Autocompletion, etc.
Tip: The actual DTD version of Gentoo is 4.4, but wireshark docs still use 4.2.
To be able to generate the docs, change the version in the second line of
developer-guide.xml or install an older version of the DTD.
See into the Gentoo handbook howto unmask old versions.
Packages for Fedora
-------------------
Tool/File Package Opt./Mand. Comments
--------- ------- ---------- --------
xsltproc: libxslt M
xsl stylesheets: docbook-style-xsl M docbook.xsl and chunk.xsl
docbookx.dtd: docbook-dtds M provides v4.1, v4.2, v4.3, v4.4 DTDs
asciidoc: ascidoc M
fop: fop O See above
Note: There are required dependencies (such as xml-common and sgml-common);
yum is your friend for doing package installs including required
dependencies.
Packages for Debian
-------------------
Tool/File Package Opt./Mand. Comments
--------- ------- ---------- --------
xsltproc: libxslt M
xsl stylesheets: docbook-xsl M
chunk.xsl: docbook-xsl M
htmlhelp.xsl: docbook-xsl M
docbookx.dtd: docbook-xml M
fop: fop O See above
Makefile:
--------------------------
There are several ways and tools to do these conversion, following is a short
description of the way the makefile targets are doing things and which output
files required for a release in that format.
all
Will generate both guides in all available output formats (see below).
make wsug
Will generate Wireshark User's Guide in all available output formats.
make wsug_html
The HTML file is generated using xsltproc and the XSL stylesheets from
Norman Walsh. This is a conversion into a single HTML page.
output: wsug_html
make wsug_html_chunked
The HTML files are generated using xsltproc and the XSL stylesheets from
Norman Walsh. This is a conversion into chunked (multiple) HTML pages.
output: wsug_html_chunked
make wsug_pdf_us
make wsug_pdf_a4
The PDF is generated using an intermediate format named XSL-FO (XSL
formatting objects). xsltproc converts the XML to a FO file, and then FOP
(Apache's formatting object processor) is used to generate the PDF document,
in US letter or A4 paper format.
Tip: You will get lot's of INFO/WARNING/ERROR messages when generating PDF,
but the conversion works just fine.
output: user-guide-us.pdf user-guide-a4.pdf
make wsug_chm
On Win32 platforms, the "famous" HTML help format can be generated by using a
special HTML chunked conversion and then use the htmlhelp compiler from
Microsoft.
output: htmlhelp.chm
Using the prefix wsdg_ instead of wsug_ will build the same targets but for the
Wireshark Developer's Guide.
The makefile is written to be run with make on UNIX/Linux platforms.
Reference in New Issue View Git Blame Copy Permalink