docbook/README.txt

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