= 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 Install it: emerge 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.