2016-08-22 22:10:24 +00:00
|
|
|
= Introduction =
|
|
|
|
|
2004-08-06 21:06:27 +00:00
|
|
|
This directory contains the source files needed to build the:
|
|
|
|
|
2007-02-03 04:09:22 +00:00
|
|
|
- Wireshark User's guide
|
|
|
|
- Wireshark Developer's Guide
|
|
|
|
- Release notes (NEWS)
|
|
|
|
- Lua Reference
|
2004-08-06 21:06:27 +00:00
|
|
|
|
2016-08-22 22:10:24 +00:00
|
|
|
To build everything, just run `make` (for Windows see README.cmake).
|
|
|
|
Requirements are listed below.
|
2004-08-06 21:06:27 +00:00
|
|
|
|
2016-08-22 22:10:24 +00:00
|
|
|
The guides and release notes are written in AsciiDoc (http://asciidoc.org),
|
|
|
|
but use many Asciidoctor (http://asciidoctor.org/) markup extensions which
|
|
|
|
are provided in asciidoctor-asciidoc.conf. The documentation toolchain may
|
|
|
|
switch exclusively to Asciidoctor at some point in the future.
|
2004-08-06 21:06:27 +00:00
|
|
|
|
2011-06-06 15:32:40 +00:00
|
|
|
To get HTML, PDF or other output formats, conversions are done using XSL
|
2004-08-06 21:06:27 +00:00
|
|
|
stylesheets, which provides a flexible way for these conversions.
|
|
|
|
|
2011-06-06 15:32:40 +00:00
|
|
|
By default the Makefile generates HTML in single page and multiple (chunked)
|
2009-12-20 14:49:49 +00:00
|
|
|
formats and two PDF's.
|
2007-02-03 04:09:22 +00:00
|
|
|
|
2004-08-06 21:06:27 +00:00
|
|
|
Requirements:
|
|
|
|
-------------
|
|
|
|
|
2016-08-22 22:10:24 +00:00
|
|
|
AsciiDoc
|
|
|
|
--------
|
|
|
|
Text documentation format and conversion suite:
|
|
|
|
http://asciidoc.org/
|
|
|
|
|
2004-08-06 21:06:27 +00:00
|
|
|
DocBook XML DTD
|
|
|
|
---------------
|
2013-08-08 15:58:35 +00:00
|
|
|
DocBook "official" XML DTD V4.5:
|
2004-08-06 21:06:27 +00:00
|
|
|
http://www.oasis-open.org/docbook/xml/
|
2009-12-20 14:49:49 +00:00
|
|
|
(available as a package for Linux / Cygwin)
|
2004-08-06 21:06:27 +00:00
|
|
|
|
|
|
|
DocBook XSL
|
|
|
|
-----------
|
2011-06-06 15:32:40 +00:00
|
|
|
The "official" XSL stylesheets from Norman Walsh:
|
2004-08-06 21:06:27 +00:00
|
|
|
http://docbook.sourceforge.net/
|
2009-12-20 14:49:49 +00:00
|
|
|
(available as a package for Linux / Cygwin)
|
2004-08-06 21:06:27 +00:00
|
|
|
|
|
|
|
xsltproc
|
|
|
|
--------
|
2009-12-28 22:09:35 +00:00
|
|
|
The XSL processor xsltproc. Part of libxslt:
|
|
|
|
http://xmlsoft.org/xslt/
|
|
|
|
Available as a package for Linux / Cygwin.
|
|
|
|
Supplied with Mac OS X Panther and later.
|
2007-02-03 04:09:22 +00:00
|
|
|
|
2004-08-06 21:06:27 +00:00
|
|
|
FOP processor (for PDF generation only)
|
|
|
|
---------------------------------------
|
|
|
|
FOP processor from the apache project:
|
|
|
|
http://xml.apache.org/fop/
|
2009-11-10 01:32:59 +00:00
|
|
|
|
|
|
|
FOP is a Java program, so you need to have a Java environment installed.
|
2016-03-18 00:19:18 +00:00
|
|
|
The makefiles look for fop-2.1 in the docbook directory. You can change
|
2016-06-08 13:57:00 +00:00
|
|
|
this location by setting the FOP environment variable.
|
2009-11-10 01:32:59 +00:00
|
|
|
|
|
|
|
FOP might return an OutOfMemoryException. You can limit its memory usage
|
|
|
|
by adding " -Xmx256m" to the FOP_OPTS environment variable. The Windows
|
|
|
|
makefile does this by default.
|
|
|
|
|
|
|
|
Hyphenation Patterns
|
2009-12-20 14:49:49 +00:00
|
|
|
--------------------
|
2009-11-10 01:32:59 +00:00
|
|
|
Hyphenation patterns for FOP can be found at
|
|
|
|
http://offo.sourceforge.net/hyphenation/. Different pattern files have
|
|
|
|
different licenses. The English patterns may have restrictions on
|
|
|
|
commercial use.
|
|
|
|
|
2016-08-22 22:10:24 +00:00
|
|
|
|
|
|
|
AsciiDoc Notes
|
|
|
|
--------------
|
|
|
|
|
|
|
|
AsciiDoc can use either w3m (default) or Lynx for plain text output. We use
|
|
|
|
AsciiDoc for the Developer's Guide, User's Guide, and for the release notes.
|
|
|
|
Lynx is used to render the official plaintext release announcements.
|
2014-08-18 16:31:26 +00:00
|
|
|
|
|
|
|
The AsciiDoc files have been converted from DocBook. In a lot of cases the
|
|
|
|
markup is wrong, inconsistent, or both. Use the following markup conventions
|
|
|
|
for any new or revised text:
|
|
|
|
|
|
|
|
- Window and dialog box names should be in ``curly quotes''.
|
|
|
|
|
|
|
|
- Use Asciidoctor compatibility macros for buttons, keys, and menus:
|
|
|
|
|
|
|
|
The button:[Start] button
|
|
|
|
Press kbd:[Shift+Ctrl+P] to open the preferences dialog.
|
|
|
|
Select menu:File[Open] from the main menu.
|
|
|
|
|
2016-08-05 14:11:23 +00:00
|
|
|
This ensures that UI elements are shown consistently and lets us apply styles
|
2014-08-18 16:31:26 +00:00
|
|
|
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.
|
|
|
|
|
2004-08-06 21:06:27 +00:00
|
|
|
|
2009-12-20 14:49:49 +00:00
|
|
|
Lynx
|
2007-02-03 08:01:16 +00:00
|
|
|
----
|
2016-08-05 14:11:23 +00:00
|
|
|
Text based web browser which can convert HTML to plain text.
|
2016-08-22 22:10:24 +00:00
|
|
|
(Alternatives: w3m and elinks)
|
2007-02-03 04:09:22 +00:00
|
|
|
|
2013-03-15 21:18:16 +00:00
|
|
|
dblatex
|
|
|
|
-------
|
|
|
|
DocBook to LaTeX converter. Required for AsciiDoc PDF conversion on Win32.
|
|
|
|
|
2013-03-15 17:00:21 +00:00
|
|
|
Win32 only: HTML help compiler (for .chm generation only)
|
|
|
|
---------------------------------------------------------
|
|
|
|
HTML Help Compiler (hhc.exe) from Microsoft:
|
|
|
|
http://www.microsoft.com/en-us/download/details.aspx?id=21138
|
|
|
|
|
2007-02-03 04:09:22 +00:00
|
|
|
Packages for Win32
|
|
|
|
------------------
|
2014-08-24 18:06:56 +00:00
|
|
|
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.
|
2007-02-03 04:09:22 +00:00
|
|
|
|
|
|
|
Tool/File Cygwin Package Opt./Mand. Comments
|
|
|
|
--------- -------------- ---------- --------
|
2014-08-24 18:06:56 +00:00
|
|
|
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
|
2008-04-30 07:35:25 +00:00
|
|
|
lynx: Web/lynx M
|
2014-06-16 19:14:34 +00:00
|
|
|
dblatex Text/dblatex O A number of dependencies will also be installed
|
2016-06-08 13:57:00 +00:00
|
|
|
fop: - O URL: http://xml.apache.org/fop/ - install it into docbok\fop-1.x or wireshark_lib_dir\fop-1.x
|
2011-06-06 15:32:40 +00:00
|
|
|
hhc: - O URL: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/hwMicrosoftHTMLHelpDownloads.asp
|
2008-04-30 07:35:25 +00:00
|
|
|
zip: Archive/zip O
|
2014-08-24 18:06:56 +00:00
|
|
|
getopt: Base/util-linux O Required to run "build-docbook-catalog"
|
2007-02-03 04:09:22 +00:00
|
|
|
|
|
|
|
|
2005-08-07 00:07:18 +00:00
|
|
|
Packages for Suse 9.3
|
|
|
|
---------------------
|
2007-02-03 04:09:22 +00:00
|
|
|
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
|
|
|
|
|
2005-08-07 00:07:18 +00:00
|
|
|
|
|
|
|
Packages for Gentoo
|
|
|
|
-------------------
|
2007-02-03 04:09:22 +00:00
|
|
|
Like with all packages do ...
|
2006-07-12 16:44:23 +00:00
|
|
|
Check dependencies: emerge -p <package>
|
|
|
|
Install it: emerge <package>
|
|
|
|
|
2007-02-03 04:09:22 +00:00
|
|
|
Tool/File Package Opt./Mand. Comments
|
|
|
|
--------- ------- ---------- --------
|
2011-06-06 15:32:40 +00:00
|
|
|
xsltproc: libxslt M
|
2007-02-03 04:09:22 +00:00
|
|
|
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.
|
2006-07-12 16:44:23 +00:00
|
|
|
|
|
|
|
Tip: The actual DTD version of Gentoo is 4.4, but wireshark docs still use 4.2.
|
2009-12-20 14:49:49 +00:00
|
|
|
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.
|
2006-07-12 16:44:23 +00:00
|
|
|
See into the Gentoo handbook howto unmask old versions.
|
2005-08-07 00:07:18 +00:00
|
|
|
|
2007-02-03 04:09:22 +00:00
|
|
|
|
2010-04-06 15:34:07 +00:00
|
|
|
Packages for Fedora
|
|
|
|
-------------------
|
2007-09-12 21:34:48 +00:00
|
|
|
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
|
2014-06-16 19:14:34 +00:00
|
|
|
asciidoc: ascidoc M
|
2007-09-12 21:34:48 +00:00
|
|
|
|
|
|
|
fop: fop O See above
|
|
|
|
|
2011-06-06 15:32:40 +00:00
|
|
|
Note: There are required dependencies (such as xml-common and sgml-common);
|
2009-12-20 14:49:49 +00:00
|
|
|
yum is your friend for doing package installs including required
|
|
|
|
dependencies.
|
2005-08-07 00:07:18 +00:00
|
|
|
|
2007-02-03 04:09:22 +00:00
|
|
|
|
2005-08-07 00:07:18 +00:00
|
|
|
Packages for Debian
|
|
|
|
-------------------
|
2009-12-20 14:49:49 +00:00
|
|
|
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
|
2007-02-03 04:09:22 +00:00
|
|
|
|
|
|
|
|
|
|
|
|
2016-06-08 13:57:00 +00:00
|
|
|
Makefile:
|
2007-02-03 04:09:22 +00:00
|
|
|
--------------------------
|
2011-06-06 15:32:40 +00:00
|
|
|
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
|
2004-08-06 21:06:27 +00:00
|
|
|
files required for a release in that format.
|
|
|
|
|
|
|
|
all
|
2016-08-05 14:11:23 +00:00
|
|
|
Will generate both guides in all available output formats (see below).
|
2004-10-16 11:32:07 +00:00
|
|
|
|
2006-05-30 21:34:56 +00:00
|
|
|
make wsug
|
2006-06-06 23:08:58 +00:00
|
|
|
Will generate Wireshark User's Guide in all available output formats.
|
2004-08-06 21:06:27 +00:00
|
|
|
|
2006-05-30 21:34:56 +00:00
|
|
|
make wsug_html
|
2011-06-06 15:32:40 +00:00
|
|
|
The HTML file is generated using xsltproc and the XSL stylesheets from
|
2004-08-06 21:06:27 +00:00
|
|
|
Norman Walsh. This is a conversion into a single HTML page.
|
2006-05-30 21:34:56 +00:00
|
|
|
output: wsug_html
|
2004-08-06 21:06:27 +00:00
|
|
|
|
2006-05-30 21:34:56 +00:00
|
|
|
make wsug_html_chunked
|
2011-06-06 15:32:40 +00:00
|
|
|
The HTML files are generated using xsltproc and the XSL stylesheets from
|
2004-08-06 21:06:27 +00:00
|
|
|
Norman Walsh. This is a conversion into chunked (multiple) HTML pages.
|
2006-05-30 21:34:56 +00:00
|
|
|
output: wsug_html_chunked
|
2004-08-06 21:06:27 +00:00
|
|
|
|
2006-05-30 21:34:56 +00:00
|
|
|
make wsug_pdf_us
|
|
|
|
make wsug_pdf_a4
|
2011-06-06 15:32:40 +00:00
|
|
|
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
|
2009-12-20 14:49:49 +00:00
|
|
|
(Apache's formatting object processor) is used to generate the PDF document,
|
2004-08-06 21:06:27 +00:00
|
|
|
in US letter or A4 paper format.
|
2009-12-20 14:49:49 +00:00
|
|
|
Tip: You will get lot's of INFO/WARNING/ERROR messages when generating PDF,
|
|
|
|
but the conversion works just fine.
|
2006-06-06 23:08:58 +00:00
|
|
|
output: user-guide-us.pdf user-guide-a4.pdf
|
2004-08-06 21:06:27 +00:00
|
|
|
|
2006-05-30 21:34:56 +00:00
|
|
|
make wsug_chm
|
2011-06-06 15:32:40 +00:00
|
|
|
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
|
2004-08-06 21:06:27 +00:00
|
|
|
Microsoft.
|
|
|
|
output: htmlhelp.chm
|
|
|
|
|
2011-06-06 15:32:40 +00:00
|
|
|
Using the prefix wsdg_ instead of wsug_ will build the same targets but for the
|
2006-06-06 23:08:58 +00:00
|
|
|
Wireshark Developer's Guide.
|
2004-10-16 11:32:07 +00:00
|
|
|
|
2009-12-20 14:49:49 +00:00
|
|
|
The makefile is written to be run with make on UNIX/Linux platforms.
|