This directory contains the source files needed to build the:
-Wireshark User's guide
+ - Wireshark User's guide
+ - Wireshark Developer's Guide
+ - Release notes (NEWS)
+ - Lua Reference
-and the:
-Wireshark Developer's Guide (in an early state).
-
-To build both Guide's, just do 'make', but see requirements below.
+To build everything, just do 'make' - but see requirements below.
The guides are written in Docbook/XML (formerly Docbook/SGML). This format is
To get HTML, PDF or other output formats, conversions are done using XSL
stylesheets, which provides a flexible way for these conversions.
-The current Makefile is running under Win32 in the cygwin environment, so it uses
-GNU make and such. It should be pretty easy to use it in UNIX environments too.
-Using Microsoft make (nmake) is not supported.
+By default the Makefile generates HTML in single page and multiple (chunked)
+formats and PDF.
+
+Win32 only: The optional output format CHM has to be enabled by setting
+HHC_EXE in ..\config.nmake.
-By default the Makefile generates HTML in single page and multiple (chunked) formats
-and PDF. The optional output format CHM has to be enabled in the Makefile.
+
+Settings:
+---------
+
+Unix only: Makefile and catalog.xml
+-----------------------------------------------
+You have to edit the settings in these files, to point to the DTD/XSL files
+and fop. (Makefile.auto.am is currently experimental and will probably NOT
+work - any progress on this would be appreciated!)
+
+Win32 only: ..\config.nmake
+---------------------------------------
+Settings moved to: ..\config.nmake.
Requirements:
-------------
-Settings in Makefile and catalog.xml
-------------------------------------
-You have to edit the settings in these files, to point to the DTD/XSL files, fop (and possibly hhc).
-
DocBook XML DTD
---------------
-DocBook "official" XML DTD V4.2 from:
+DocBook "official" XML DTD V4.2:
http://www.oasis-open.org/docbook/xml/
-(or using cygwin package docbook-xml42)
+(available as a package for Linux / cygwin)
DocBook XSL
-----------
-The "official" XSL stylesheets from Norman Walsh:
+The "official" XSL stylesheets from Norman Walsh:
http://docbook.sourceforge.net/
-(or using cygwin package docbook-xsl)
+(available as a package for Linux / cygwin)
xsltproc
--------
The XSL processor xsltproc.
-(it seems to be packages libxml2 and libxslt, ... please give comments)
+(available as a package for Linux / cygwin)
+
+xmllint
+-------
+Needed to validate if the .xml files conform to the Docbook/XML DTD.
+(available as a package for Linux / cygwin)
FOP processor (for PDF generation only)
---------------------------------------
FOP processor from the apache project:
http://xml.apache.org/fop/
FOP is a JAVA program, so you need to have a JAVA environment installed.
-I have put the fop-0.20.5 dir right into the sources dir. If you have it somewhere else,
-you'll have to change the setting in the Makefile.
+I have put the fop-0.20.5 dir right into the docbook sources dir. If you have
+it somewhere else, you'll have to change the setting in the Makefile
+(or config.nmake for Win32).
-Be sure to also have installed JAI and/or jimi to be able to use/convert the png graphics files.
-The fop release note webpage tells how to do it:
-download jimi from:
-http://java.sun.com/products/jimi/
-then extract the archive, then copy JimiProClasses.zip to FOP's lib dir and rename it to jimi-1.0.jar.
-
-As I got OutOfMemoryException when running fop, I had to insert -Xmx256m into the last line of the fop.bat file from:
+As I got OutOfMemoryException when running fop, I had to insert -Xmx256m into
+the last line of the fop.bat file from:
java -cp "%LOCALCLASSPATH%" org.apache.fop.apps.Fop %1 %2 %3 %4 %5 %6 %7 %8
to:
java -Xmx256m -cp "%LOCALCLASSPATH%" org.apache.fop.apps.Fop %1 %2 %3 %4 %5 %6 %7 %8
This should be added automatically on unixish systems.
-HTML help compiler (for chm file generation only)
--------------------------------------------------
-hhc compiler from Microsoft:
+JIMI (for PDF generation only)
+------------------------------
+Jimi is a JAVA class library for managing images.
+In addition to FOP, be sure to also have installed JAI and/or jimi to be able
+to use/convert the png graphics files. The fop release note webpage tells how
+to do it:
+download jimi from:
+http://java.sun.com/products/jimi/
+then extract the archive, then copy JimiProClasses.zip to FOP's lib dir and rename it to jimi-1.0.jar.
+
+Win32 only: HTML help compiler (for .chm generation only)
+---------------------------------------------------------
+hhc compiler (hhc.exe) from Microsoft:
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/hwMicrosoftHTMLHelpDownloads.asp
+
+
+Packages for Win32
+------------------
+See ..\config.nmake for Win32 settings.
+
+Tool/File Cygwin Package Opt./Mand. Comments
+--------- -------------- ---------- --------
+xsltproc: libxslt M
+xmllint: libxml2 M
+xsl stylesheets: docbook-xsl M docbook.xsl, chunk.xsl and htmlhelp.xsl
+docbookx.dtd: docbook_xml42 M
+fop: - O URL: http://xml.apache.org/fop/ - install it into fop-0.20.5 to keep defaults from config.nmake
+jimi: - O URL: http://java.sun.com/products/jimi/ - see above
+hhc: - O URL: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/hwMicrosoftHTMLHelpDownloads.asp
+
+
Packages for Suse 9.3
---------------------
-Tool/File Package
---------- -------
-xsltproc: libxslt
-xmllint: libxml2
-fop: fop
-docbook.xsl: docbook-xsl-stylesheets
-chunk.xsl: docbook-xsl-stylesheets
-htmlhelp.xsl: docbook-xsl-stylesheets
-docbookx.dtd: docbook_4
-jimi: N/A - build yourself - see above
+Tool/File Package Opt./Mand. Comments
+--------- ------- ---------- --------
+xsltproc: libxslt M
+xmllint: libxml2 M
+xsl stylesheets: docbook-xsl-stylesheets M docbook.xsl and chunk.xsl
+docbookx.dtd: docbook_4 M
+fop: fop O
+jimi: - O get it from http://java.sun.com/products/jimi/ - see above
+
Packages for Gentoo
-------------------
-Like with all packages do...
+Like with all packages do ...
Check dependencies: emerge -p <package>
Install it: emerge <package>
-Tool/File Package Opt./Mand. Comments
---------- ------- ---------- --------
-xsltproc: libxslt M XSLT processer. A very fast processor writtin in C.
-xmllint: libxml2 O Xml Validator. You probably want to install that.
-fop: fop O Only needed to generate PDFs. Has a lot of JAVA dependencies.
-docbook.xsl: docbook-xsl-stylesheets M Necessary docbook catalogs are built automatically by portage in /etc/xml and /etc/sgml
-chunk.xsl: docbook-xsl-stylesheets M using "/usr/bin/build-docbook-catalog".
-htmlhelp.xsl: docbook-xsl-stylesheets M So docbook runs out of the box on Gentoo.
-docbookx.dtd: docbook-xml-dtd M
-jimi: sun-jimi O Jimi is a class library for managing images. Used by fop.
-Quanta+ quanta or kdewebdev O Nice HTML/XML/SGML and Docbook editor with Syntaxhighlighting, Autocompletion, etc.
+Tool/File Package Opt./Mand. Comments
+--------- ------- ---------- --------
+xsltproc: libxslt M
+xmllint: libxml2 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.
+jimi: sun-jimi O Used by fop.
+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 Core
------------------------
TODO
+
Packages for Debian
-------------------
-Tool/File Package
---------- -------
-xsltproc: libxslt
-xmllint: libxml2-utils
-fop: fop
-docbook.xsl: docbook-xsl
-chunk.xsl: docbook-xsl
-htmlhelp.xsl: docbook-xsl
-docbookx.dtd: docbook-xml
-jimi: N/A - build yourself - see above
-
-Makefile:
----------
+Tool/File Package
+--------- -------
+xsltproc: libxslt
+xmllint: libxml2-utils
+xsl stylesheets: docbook-xsl
+chunk.xsl: docbook-xsl
+htmlhelp.xsl: docbook-xsl
+docbookx.dtd: docbook-xml
+fop: fop
+jimi: http://java.sun.com/products/jimi/ - see above
+
+
+
+Makefile / Makefile.nmake:
+--------------------------
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.
git.samba.org / metze / wireshark / wip.git / commitdiff