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."
  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 two PDF's.
  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. Part of libxslt:
  61 http://xmlsoft.org/xslt/
  62 Available as a package for Linux / Cygwin.
  63 Supplied with Mac OS X Panther and later.
  64
  65 xmllint
  66 -------
  67 Needed to validate if the .xml files conform to the Docbook/XML DTD.
  68 Part of libxml2:
  69 http://xmlsoft.org/
  70 Available as a package for Linux / Cygwin.
  71 Supplied with Mac OS X Panther and later.
  72
  73 FOP processor (for PDF generation only)
  74 ---------------------------------------
  75 FOP processor from the apache project:
  76 http://xml.apache.org/fop/
  77
  78 FOP is a Java program, so you need to have a Java environment installed.
  79 The makefiles look for fop-1.0 in the docbook directory. You can change
  80 this location by setting the FOP environment variable or by changing
  81 config.nmake.
  82
  83 FOP might return an OutOfMemoryException. You can limit its memory usage
  84 by adding " -Xmx256m" to the FOP_OPTS environment variable. The Windows
  85 makefile does this by default.
  86
  87 Hyphenation Patterns
  88 --------------------
  89 Hyphenation patterns for FOP can be found at
  90 http://offo.sourceforge.net/hyphenation/. Different pattern files have
  91 different licenses. The English patterns may have restrictions on
  92 commercial use.
  93
  94 JIMI (for PDF generation)
  95 -------------------------
  96 Jimi is a JAVA class library for managing images.
  97 In addition to FOP, be sure to also have installed JAI and/or jimi to be able
  98 to use/convert the PNG graphics files. The FOP release note webpage tells how
  99 to do it:
 100 download jimi from:
 101 http://java.sun.com/products/jimi/
 102 then extract the archive, then copy JimiProClasses.zip to FOP's lib dir and
 103 rename it to jimi-1.0.jar.
 104
 105 Win32 only: HTML help compiler (for .chm generation only)
 106 ---------------------------------------------------------
 107 HTML Help Compiler (hhc.exe) from Microsoft:
 108 http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/hwMicrosoftHTMLHelpDownloads.asp
 109
 110 Lynx
 111 ----
 112 Text based web browser used to convert release_notes.html into plain text
 113 format.
 114 (Alternative [*nix]: elinks)
 115
 116 Packages for Win32
 117 ------------------
 118 See ..\config.nmake for Win32 settings. You may need to run
 119 "build-docbook-catalog" in order to register your catalog properly.
 120
 121 Tool/File           Cygwin Package          Opt./Mand.  Comments
 122 ---------           --------------          ----------  --------
 123 xsltproc:           Doc/libxslt             M
 124 xmllint:            Doc/libxml2             M
 125 xsl stylesheets:    Doc/docbook-xsl         M           docbook.xsl, chunk.xsl and htmlhelp.xsl
 126 docbookx.dtd:       Doc/docbook-xml42       M
 127 lynx:               Web/lynx                M
 128 fop:                -                       O           URL: http://xml.apache.org/fop/ - install it into docbook\fop-1.0 to keep defaults from config.nmake
 129 jimi:               -                       O           URL: http://java.sun.com/products/jimi/ - see above
 130 hhc:                -                       O           URL: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/hwMicrosoftHTMLHelpDownloads.asp
 131 zip:                Archive/zip             O
 132 getopt:             Utils/util-linux        O           Required to run "build-docbook-catalog"
 133
 134
 135 Packages for Suse 9.3
 136 ---------------------
 137 Tool/File           Package                 Opt./Mand.  Comments
 138 ---------           -------                 ----------  --------
 139 xsltproc:           libxslt                 M
 140 xmllint:            libxml2                 M
 141 xsl stylesheets:    docbook-xsl-stylesheets M           docbook.xsl and chunk.xsl
 142 docbookx.dtd:       docbook_4               M
 143 fop:                fop                     O
 144 jimi:               -                       O           get it from http://java.sun.com/products/jimi/ - see above
 145
 146
 147 Packages for Gentoo
 148 -------------------
 149 Like with all packages do ...
 150 Check dependencies: emerge -p <package>
 151 Install it:         emerge <package>
 152
 153 Tool/File           Package                  Opt./Mand.   Comments
 154 ---------           -------                  ----------   --------
 155 xsltproc:           libxslt                  M
 156 xmllint:            libxml2                  M
 157 xsl stylesheets:    docbook-xsl-stylesheets  M            docbook.xsl and chunk.xsl
 158                                                           Necessary docbook catalogs are built automatically by portage in /etc/xml and /etc/sgml
 159                                                             docbook.xsl and chunk.xsl using "/usr/bin/build-docbook-catalog".
 160                                                             So docbook runs out of the box on Gentoo.
 161 docbookx.dtd:       docbook-xml-dtd          M
 162 fop:                fop                      O            Has a lot of JAVA dependencies.
 163 jimi:               sun-jimi                 O            Used by fop.
 164 Quanta+             quanta or kdewebdev      O            Nice HTML/XML/SGML and Docbook editor with Syntaxhighlighting, Autocompletion, etc.
 165
 166 Tip: The actual DTD version of Gentoo is 4.4, but wireshark docs still use 4.2.
 167      To be able to generate the docs, change the version in the second line of
 168      developer-guide.xml or install an older version of the DTD.
 169      See into the Gentoo handbook howto unmask old versions.
 170
 171
 172 Packages for Fedora
 173 -------------------
 174 Tool/File           Package                 Opt./Mand.  Comments
 175 ---------           -------                 ----------  --------
 176 xsltproc:           libxslt                 M
 177 xmllint:            libxml2                 M
 178 xsl stylesheets:    docbook-style-xsl       M           docbook.xsl and chunk.xsl
 179 docbookx.dtd:       docbook-dtds            M           provides v4.1, v4.2, v4.3, v4.4 DTDs
 180
 181 fop:                fop                     O           See above
 182 jimi:               -                       O           get it from http://java.sun.com/products/jimi/ - see above
 183
 184 Note: There are required dependencies (such as xml-common and sgml-common);
 185       yum is your friend for doing package installs including required
 186       dependencies.
 187
 188
 189 Packages for Debian
 190 -------------------
 191 Tool/File           Package                 Opt./Mand.  Comments
 192 ---------           -------                 ----------  --------
 193 xsltproc:           libxslt                 M
 194 xmllint:            libxml2-utils           M
 195 xsl stylesheets:    docbook-xsl             M
 196 chunk.xsl:          docbook-xsl             M
 197 htmlhelp.xsl:       docbook-xsl             M
 198 docbookx.dtd:       docbook-xml             M
 199 fop:                fop                     O           See above
 200 jimi:               -                       O           http://java.sun.com/products/jimi/ - see above
 201
 202
 203
 204 Makefile / Makefile.nmake:
 205 --------------------------
 206 There are several ways and tools to do these conversion, following is a short
 207 description of the way the makefile targets are doing things and which output
 208 files required for a release in that format.
 209
 210 all
 211 Will generate both guide's in all available output formats (see below).
 212
 213 make wsug
 214 Will generate Wireshark User's Guide in all available output formats.
 215
 216 make wsug_html
 217 The HTML file is generated using xsltproc and the XSL stylesheets from
 218 Norman Walsh. This is a conversion into a single HTML page.
 219 output: wsug_html
 220
 221 make wsug_html_chunked
 222 The HTML files are generated using xsltproc and the XSL stylesheets from
 223 Norman Walsh. This is a conversion into chunked (multiple) HTML pages.
 224 output: wsug_html_chunked
 225
 226 make wsug_pdf_us
 227 make wsug_pdf_a4
 228 The PDF is generated using an intermediate format named XSL-FO (XSL
 229 formatting objects). xsltproc converts the XML to a FO file, and then FOP
 230 (Apache's formatting object processor) is used to generate the PDF document,
 231 in US letter or A4 paper format.
 232 Tip: You will get lot's of INFO/WARNING/ERROR messages when generating PDF,
 233 but the conversion works just fine.
 234 output: user-guide-us.pdf user-guide-a4.pdf
 235
 236 make wsug_chm
 237 On Win32 platforms, the "famous" HTML help format can be generated by using a
 238 special HTML chunked conversion and then use the htmlhelp compiler from
 239 Microsoft.
 240 output: htmlhelp.chm
 241
 242 Using the prefix wsdg_ instead of wsug_ will build the same targets but for the
 243 Wireshark Developer's Guide.
 244
 245 The makefile is written to be run with make on UNIX/Linux platforms.
 246 Win32 platforms have to use nmake -f Makefile.nmake
 247
 248
 249 Notes to authors
 250 ----------------
 251 The docbook DTD provides you with all tags required to mark up a documents
 252 structure. Please have a look at the existing XML files to see what these
 253 structural tags are, and look at the DocBook web references below.
 254 To maintain a consistent look and feel in the documents please use the
 255 following tags for the indicated purposes.
 256
 257 Tag           Purpose
 258 ---           -------
 259 <application> to mark application names, like Wireshark.
 260 <filename>    to mark an individual file or path.
 261 <command>     to mark a command, with parameters.
 262 <prompt>      to mark a prompt before user input.
 263 <userinput>   to mark an example of user input, like an actual command line.
 264 <function>    to mark a function name, ending with parenthesis.
 265 <parameter>   to mark (function) parameters.
 266 <varname>     to mark (environment) variables.
 267 <literal>     to mark some literal value.
 268
 269 These are all tags for inline text. Wrap literal text output in a CDATA block,
 270 like so:
 271
 272        <programlisting>
 273 <![CDATA[#include <epan/tap.h>
 274 ...
 275 ]]>
 276        </programlisting>
 277
 278 Make sure the CDATA clause is at column 1, because prefixed whitespace will be
 279 present in the verbatim output as well.
 280
 281
 282 Docbook web references:
 283 -----------------------
 284 Some web references to further documentation about Docbook/XML and Docbook XSL
 285 conversions:
 286
 287 DocBook: The Definitive Guide
 288 by Norman Walsh and Leonard Muellner
 289 http://www.docbook.org/tdg/en/html/docbook.html
 290
 291 DocBook XSL: The Complete Guide
 292 by Bob Stayton
 293 http://www.sagehill.net/docbookxsl/index.html
 294
 295 Documention with DocBook on Win32
 296 by Jim Crafton
 297 http://www.codeproject.com/KB/winhelp/docbook_howto.aspx
 298
 299 FO Parameter Reference
 300 by Norman Walsh
 301 http://docbook.sourceforge.net/release/xsl/current/doc/fo/
 302