$Id$ 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, just do 'make' (for Win32: 'nmake -f Makefile.nmake') but see the requirements below. The guides are written in Docbook/XML (formerly Docbook/SGML). This format is now used by many other documentation projects, e.g. "the Linux Documentation Project." To get HTML, PDF or other output formats, conversions are done using XSL stylesheets, which provides a flexible way for these conversions. 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. 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: ------------- DocBook XML DTD --------------- DocBook "official" XML DTD V4.2: http://www.oasis-open.org/docbook/xml/ (available as a package for Linux / cygwin) DocBook XSL ----------- The "official" XSL stylesheets from Norman Walsh: http://docbook.sourceforge.net/ (available as a package for Linux / cygwin) xsltproc -------- The XSL processor xsltproc. (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. The makefiles look for fop-0.95 in the docbook directory. You can change this location by setting the FOP environment variable or by changing config.nmake. 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 ------------------------------ 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. JIMI (for PDF generation with fop 0.20.5 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 lynx ---- Text based web browser used to convert release_notes.html into plain text format. Packages for Win32 ------------------ See ..\config.nmake for Win32 settings. Tool/File Cygwin Package Opt./Mand. Comments --------- -------------- ---------- -------- xsltproc: Doc/libxslt M xmllint: Doc/libxml2 M xsl stylesheets: Doc/docbook-xsl M docbook.xsl, chunk.xsl and htmlhelp.xsl docbookx.dtd: Doc/docbook_xml42 M lynx: Web/lynx M fop: - O URL: http://xml.apache.org/fop/ - install it into docbook\fop-0.95 to keep defaults from config.nmake jimi: - O (fop 0.20.5 only) 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 zip: Archive/zip O Packages for Suse 9.3 --------------------- 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 (fop 0.20.5 only) get it from http://java.sun.com/products/jimi/ - see above Packages for Gentoo ------------------- Like with all packages do ... Check dependencies: emerge -p Install it: emerge 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 (fop 0.20.5 ony) 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 7 --------------------- Tool/File Package Opt./Mand. Comments --------- ------- ---------- -------- xsltproc: libxslt M xmllint: libxml2 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 fop: fop O See above jimi: - O (fop 0.20.5 ony) get it from http://java.sun.com/products/jimi/ - 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 --------- ------- xsltproc: libxslt xmllint: libxml2-utils xsl stylesheets: docbook-xsl chunk.xsl: docbook-xsl htmlhelp.xsl: docbook-xsl docbookx.dtd: docbook-xml fop: fop jimi: (fop 0.20.5 ony) 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. all Will generate both guide's 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 conversation 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 gmake on UNIX/Linux platforms. Win32 platforms have to use the cygwin environment (Microsoft nmake is not supported). Docbook web references: ----------------------- Some web references to further documentation about Docbook/XML and Docbook XSL conversions: DocBook: The Definitive Guide by Norman Walsh and Leonard Muellner http://www.docbook.org/tdg/en/html/docbook.html DocBook XSL: The Complete Guide by Bob Stayton http://www.sagehill.net/docbookxsl/index.html Documention with DocBook on Win32 by Jim Crafton http://www.codeproject.com/winhelp/docbook_howto.asp FO Parameter Reference by Norman Walsh http://docbook.sourceforge.net/release/xsl/current/doc/fo/