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