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