docbook/README.txt

   1 $Id$
   2
   3 This directory contains the source files needed to build the:
   4
   5 Wireshark User's guide
   6
   7 and the:
   8
   9 Wireshark Developer's Guide  (in an early state).
  10
  11 To build both Guide's, 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 The current Makefile is running under Win32 in the cygwin environment, so it uses
  22 GNU make and such. It should be pretty easy to use it in UNIX environments too.
  23 Using Microsoft make (nmake) is not supported.
  24
  25 By default the Makefile generates HTML in single page and multiple (chunked) formats
  26 and PDF. The optional output format CHM has to be enabled in the Makefile.
  27
  28
  29 Requirements:
  30 -------------
  31
  32 Settings in Makefile and catalog.xml
  33 ------------------------------------
  34 You have to edit the settings in these files, to point to the DTD/XSL files, fop (and possibly hhc).
  35
  36 DocBook XML DTD
  37 ---------------
  38 DocBook "official" XML DTD V4.2 from:
  39 http://www.oasis-open.org/docbook/xml/
  40 (or using cygwin package docbook-xml42)
  41
  42 DocBook XSL
  43 -----------
  44 The "official" XSL stylesheets from Norman Walsh:
  45 http://docbook.sourceforge.net/
  46 (or using cygwin package docbook-xsl)
  47
  48 xsltproc
  49 --------
  50 The XSL processor xsltproc.
  51 (it seems to be packages libxml2 and libxslt, ... please give comments)
  52
  53 FOP processor (for PDF generation only)
  54 ---------------------------------------
  55 FOP processor from the apache project:
  56 http://xml.apache.org/fop/
  57 FOP is a JAVA program, so you need to have a JAVA environment installed.
  58 I have put the fop-0.20.5 dir right into the sources dir. If you have it somewhere else,
  59 you'll have to change the setting in the Makefile.
  60
  61 Be sure to also have installed JAI and/or jimi to be able to use/convert the png graphics files.
  62 The fop release note webpage tells how to do it:
  63 download jimi from:
  64 http://java.sun.com/products/jimi/
  65 then extract the archive, then copy JimiProClasses.zip to FOP's lib dir and rename it to jimi-1.0.jar.
  66
  67 As I got OutOfMemoryException when running fop, I had to insert -Xmx256m into the last line of the fop.bat file from:
  68 java -cp "%LOCALCLASSPATH%" org.apache.fop.apps.Fop %1 %2 %3 %4 %5 %6 %7 %8
  69 to:
  70 java -Xmx256m -cp "%LOCALCLASSPATH%" org.apache.fop.apps.Fop %1 %2 %3 %4 %5 %6 %7 %8
  71 This should be added automatically on unixish systems.
  72
  73 HTML help compiler (for chm file generation only)
  74 -------------------------------------------------
  75 hhc compiler from Microsoft:
  76 http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/hwMicrosoftHTMLHelpDownloads.asp
  77
  78 Packages for Suse 9.3
  79 ---------------------
  80 Tool/File       Package
  81 ---------       -------
  82 xsltproc:       libxslt
  83 xmllint:        libxml2
  84 fop:            fop
  85 docbook.xsl:    docbook-xsl-stylesheets
  86 chunk.xsl:      docbook-xsl-stylesheets
  87 htmlhelp.xsl:   docbook-xsl-stylesheets
  88 docbookx.dtd:   docbook_4
  89 jimi:           N/A - build yourself - see above
  90
  91 Packages for Gentoo
  92 -------------------
  93 TODO
  94
  95 Packages for Fedora Core
  96 ------------------------
  97 TODO
  98
  99 Packages for Debian
 100 -------------------
 101 Tool/File       Package
 102 ---------       -------
 103 xsltproc:       libxslt
 104 xmllint:        libxml2-utils
 105 fop:            fop
 106 docbook.xsl:    docbook-xsl
 107 chunk.xsl:      docbook-xsl
 108 htmlhelp.xsl:   docbook-xsl
 109 docbookx.dtd:   docbook-xml
 110 jimi:           N/A - build yourself - see above
 111
 112 Makefile:
 113 ---------
 114 There are several ways and tools to do these conversion, following is a short
 115 description of the way the makefile targets are doing things and which output
 116 files required for a release in that format.
 117
 118 all
 119 Will generate both guide's in all available output formats (see below).
 120
 121 make wsug
 122 Will generate Wireshark User's Guide in all available output formats.
 123
 124 make wsug_html
 125 The HTML file is generated using xsltproc and the XSL stylesheets from
 126 Norman Walsh. This is a conversion into a single HTML page.
 127 output: wsug_html
 128
 129 make wsug_html_chunked
 130 The HTML files are generated using xsltproc and the XSL stylesheets from
 131 Norman Walsh. This is a conversion into chunked (multiple) HTML pages.
 132 output: wsug_html_chunked
 133
 134 make wsug_pdf_us
 135 make wsug_pdf_a4
 136 The PDF is generated using an intermediate format named XSL-FO (XSL
 137 formatting objects). xsltproc converts the XML to a FO file, and then fop
 138 (apache's formatting object processor) is used to generate the PDF document,
 139 in US letter or A4 paper format.
 140 TIP: You will get lot's of INFO/WARNING/ERROR messages when generating pdf,
 141 but conversation works just fine.
 142 output: user-guide-us.pdf user-guide-a4.pdf
 143
 144 make wsug_chm
 145 On Win32 platforms, the "famous" HTML help format can be generated by using a
 146 special HTML chunked conversion and then use the htmlhelp compiler from
 147 Microsoft.
 148 output: htmlhelp.chm
 149
 150 Using the prefix wsdg_ instead of wsug_ will build the same targets but for the
 151 Wireshark Developer's Guide.
 152
 153 The makefile is written to be run with gmake on UNIX/Linux platforms. Win32
 154 platforms have to use the cygwin environment (Microsoft nmake is not
 155 supported).
 156
 157
 158 Docbook web references:
 159 -----------------------
 160 Some web references to further documentation about Docbook/XML and Docbook XSL conversions:
 161
 162 DocBook: The Definitive Guide
 163 by Norman Walsh and Leonard Muellner
 164 http://www.docbook.org/tdg/en/html/docbook.html
 165
 166 DocBook XSL: The Complete Guide
 167 by Bob Stayton
 168 http://www.sagehill.net/docbookxsl/index.html
 169
 170 Documention with DocBook on Win32
 171 by Jim Crafton
 172 http://www.codeproject.com/winhelp/docbook_howto.asp
 173
 174 FO Parameter Reference
 175 by Norman Walsh
 176 http://docbook.sourceforge.net/release/xsl/current/doc/fo/
 177