docbook/README.txt

   1 $Id$
   2
   3 This directory contains the source files needed to build the:
   4
   5  - Wireshark User's guide
   6  - Wireshark Developer's Guide
   7  - Release notes (NEWS)
   8  - Lua Reference
   9
  10
  11 To build everything, just do 'make' (for Win32: 'nmake -f Makefile.nmake')
  12 but see the requirements below.
  13
  14
  15 The guides are written in Docbook/XML (formerly Docbook/SGML). This format is
  16 now used by many other documentation projects, e.g. "the linux documentation
  17 project" uses it too.
  18
  19 To get HTML, PDF or other output formats, conversions are done using XSL
  20 stylesheets, which provides a flexible way for these conversions.
  21
  22 By default the Makefile generates HTML in single page and multiple (chunked)
  23 formats and PDF.
  24
  25 Win32 only: The optional output format CHM has to be enabled by setting
  26 HHC_EXE in ..\config.nmake.
  27
  28
  29 Settings:
  30 ---------
  31
  32 Unix only: Makefile and catalog.xml
  33 -----------------------------------------------
  34 You have to edit the settings in these files, to point to the DTD/XSL files
  35 and fop. (Makefile.auto.am is currently experimental and will probably NOT
  36 work - any progress on this would be appreciated!)
  37
  38 Win32 only: ..\config.nmake
  39 ---------------------------------------
  40 Settings moved to: ..\config.nmake.
  41
  42
  43 Requirements:
  44 -------------
  45
  46 DocBook XML DTD
  47 ---------------
  48 DocBook "official" XML DTD V4.2:
  49 http://www.oasis-open.org/docbook/xml/
  50 (available as a package for Linux / cygwin)
  51
  52 DocBook XSL
  53 -----------
  54 The "official" XSL stylesheets from Norman Walsh:
  55 http://docbook.sourceforge.net/
  56 (available as a package for Linux / cygwin)
  57
  58 xsltproc
  59 --------
  60 The XSL processor xsltproc.
  61 (available as a package for Linux / cygwin)
  62
  63 xmllint
  64 -------
  65 Needed to validate if the .xml files conform to the Docbook/XML DTD.
  66 (available as a package for Linux / cygwin)
  67
  68 FOP processor (for PDF generation only)
  69 ---------------------------------------
  70 FOP processor from the apache project:
  71 http://xml.apache.org/fop/
  72 FOP is a JAVA program, so you need to have a JAVA environment installed.
  73 I have put the fop-0.20.5 dir right into the docbook sources dir. If you have
  74 it somewhere else, you'll have to change the setting in the Makefile
  75 (or config.nmake for Win32).
  76
  77 As I got OutOfMemoryException when running fop, I had to insert -Xmx256m into
  78 the last line of the fop.bat file from:
  79 java -cp "%LOCALCLASSPATH%" org.apache.fop.apps.Fop %1 %2 %3 %4 %5 %6 %7 %8
  80 to:
  81 java -Xmx256m -cp "%LOCALCLASSPATH%" org.apache.fop.apps.Fop %1 %2 %3 %4 %5 %6 %7 %8
  82 This should be added automatically on unixish systems.
  83
  84 JIMI (for PDF generation only)
  85 ------------------------------
  86 Jimi is a JAVA class library for managing images.
  87 In addition to FOP, be sure to also have installed JAI and/or jimi to be able
  88 to use/convert the png graphics files. The fop release note webpage tells how
  89 to do it:
  90 download jimi from:
  91 http://java.sun.com/products/jimi/
  92 then extract the archive, then copy JimiProClasses.zip to FOP's lib dir and rename it to jimi-1.0.jar.
  93
  94 Win32 only: HTML help compiler (for .chm generation only)
  95 ---------------------------------------------------------
  96 hhc compiler (hhc.exe) from Microsoft:
  97 http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/hwMicrosoftHTMLHelpDownloads.asp
  98
  99 lynx
 100 ----
 101 Text based web browser used to convert release_notes.html into plain text
 102 format.
 103
 104
 105 Packages for Win32
 106 ------------------
 107 See ..\config.nmake for Win32 settings.
 108
 109 Tool/File           Cygwin Package          Opt./Mand.  Comments
 110 ---------           --------------          ----------  --------
 111 xsltproc:           Doc/libxslt             M
 112 xmllint:            Doc/libxml2             M
 113 xsl stylesheets:    Doc/docbook-xsl         M           docbook.xsl, chunk.xsl and htmlhelp.xsl
 114 docbookx.dtd:       Doc/docbook_xml42       M
 115 lynx:               Web/lynx                M
 116 fop:                -                       O           URL: http://xml.apache.org/fop/ - install it into fop-0.20.5 to keep defaults from config.nmake
 117 jimi:               -                       O           URL: http://java.sun.com/products/jimi/ - see above
 118 hhc:                -                       O           URL: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/hwMicrosoftHTMLHelpDownloads.asp
 119 zip:                Archive/zip             O
 120
 121
 122 Packages for Suse 9.3
 123 ---------------------
 124 Tool/File           Package                 Opt./Mand.  Comments
 125 ---------           -------                 ----------  --------
 126 xsltproc:           libxslt                 M
 127 xmllint:            libxml2                 M
 128 xsl stylesheets:    docbook-xsl-stylesheets M           docbook.xsl and chunk.xsl
 129 docbookx.dtd:       docbook_4               M
 130 fop:                fop                     O
 131 jimi:               -                       O           get it from http://java.sun.com/products/jimi/ - see above
 132
 133
 134 Packages for Gentoo
 135 -------------------
 136 Like with all packages do ...
 137 Check dependencies: emerge -p <package>
 138 Install it:         emerge <package>
 139
 140 Tool/File           Package                  Opt./Mand.   Comments
 141 ---------           -------                  ----------   --------
 142 xsltproc:           libxslt                  M
 143 xmllint:            libxml2                  M
 144 xsl stylesheets:    docbook-xsl-stylesheets  M            docbook.xsl and chunk.xsl
 145                                                           Necessary docbook catalogs are built automatically by portage in /etc/xml and /etc/sgml
 146                                                             docbook.xsl and chunk.xsl using "/usr/bin/build-docbook-catalog".
 147                                                             So docbook runs out of the box on Gentoo.
 148 docbookx.dtd:       docbook-xml-dtd          M
 149 fop:                fop                      O            Has a lot of JAVA dependencies.
 150 jimi:               sun-jimi                 O            Used by fop.
 151 Quanta+             quanta or kdewebdev      O            Nice HTML/XML/SGML and Docbook editor with Syntaxhighlighting, Autocompletion, etc.
 152
 153 Tip: The actual DTD version of Gentoo is 4.4, but wireshark docs still use 4.2.
 154      To be able to generate the docs, change the version in the second line of developer-guide.xml
 155      or install an older version of the DTD.
 156      See into the Gentoo handbook howto unmask old versions.
 157
 158
 159 Packages for Fedora 7
 160 ---------------------
 161 Tool/File           Package                 Opt./Mand.  Comments
 162 ---------           -------                 ----------  --------
 163 xsltproc:           libxslt                 M
 164 xmllint:            libxml2                 M
 165 xsl stylesheets:    docbook-style-xsl       M           docbook.xsl and chunk.xsl
 166 docbookx.dtd:       docbook-dtds            M           provides v4.1, v4.2, v4.3, v4.4 DTDs
 167
 168 fop:                fop                     O           See above
 169 jimi:               -                       O           get it from http://java.sun.com/products/jimi/ - see above
 170
 171 Note: There are required dependencies (such as xml-common and sgml-common);
 172       yum is your friend for doing package installs including required  dependencies.
 173
 174
 175 Packages for Debian
 176 -------------------
 177 Tool/File           Package
 178 ---------           -------
 179 xsltproc:           libxslt
 180 xmllint:            libxml2-utils
 181 xsl stylesheets:    docbook-xsl
 182 chunk.xsl:          docbook-xsl
 183 htmlhelp.xsl:       docbook-xsl
 184 docbookx.dtd:       docbook-xml
 185 fop:                fop
 186 jimi:               http://java.sun.com/products/jimi/ - see above
 187
 188
 189
 190 Makefile / Makefile.nmake:
 191 --------------------------
 192 There are several ways and tools to do these conversion, following is a short
 193 description of the way the makefile targets are doing things and which output
 194 files required for a release in that format.
 195
 196 all
 197 Will generate both guide's in all available output formats (see below).
 198
 199 make wsug
 200 Will generate Wireshark User's Guide in all available output formats.
 201
 202 make wsug_html
 203 The HTML file is generated using xsltproc and the XSL stylesheets from
 204 Norman Walsh. This is a conversion into a single HTML page.
 205 output: wsug_html
 206
 207 make wsug_html_chunked
 208 The HTML files are generated using xsltproc and the XSL stylesheets from
 209 Norman Walsh. This is a conversion into chunked (multiple) HTML pages.
 210 output: wsug_html_chunked
 211
 212 make wsug_pdf_us
 213 make wsug_pdf_a4
 214 The PDF is generated using an intermediate format named XSL-FO (XSL
 215 formatting objects). xsltproc converts the XML to a FO file, and then fop
 216 (apache's formatting object processor) is used to generate the PDF document,
 217 in US letter or A4 paper format.
 218 TIP: You will get lot's of INFO/WARNING/ERROR messages when generating pdf,
 219 but conversation works just fine.
 220 output: user-guide-us.pdf user-guide-a4.pdf
 221
 222 make wsug_chm
 223 On Win32 platforms, the "famous" HTML help format can be generated by using a
 224 special HTML chunked conversion and then use the htmlhelp compiler from
 225 Microsoft.
 226 output: htmlhelp.chm
 227
 228 Using the prefix wsdg_ instead of wsug_ will build the same targets but for the
 229 Wireshark Developer's Guide.
 230
 231 The makefile is written to be run with gmake on UNIX/Linux platforms. Win32
 232 platforms have to use the cygwin environment (Microsoft nmake is not
 233 supported).
 234
 235
 236 Docbook web references:
 237 -----------------------
 238 Some web references to further documentation about Docbook/XML and Docbook XSL conversions:
 239
 240 DocBook: The Definitive Guide
 241 by Norman Walsh and Leonard Muellner
 242 http://www.docbook.org/tdg/en/html/docbook.html
 243
 244 DocBook XSL: The Complete Guide
 245 by Bob Stayton
 246 http://www.sagehill.net/docbookxsl/index.html
 247
 248 Documention with DocBook on Win32
 249 by Jim Crafton
 250 http://www.codeproject.com/winhelp/docbook_howto.asp
 251
 252 FO Parameter Reference
 253 by Norman Walsh
 254 http://docbook.sourceforge.net/release/xsl/current/doc/fo/
 255