From Graham Bloice:
[obnox/wireshark/wip.git] / 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 Like with all packages do...
94 Check dependencies: emerge -p <package>
95 Install it:         emerge <package>
96
97 Tool/File       Package                  Opt./Mand.   Comments
98 ---------       -------                  ----------   --------
99 xsltproc:       libxslt                  M            XSLT processer. A very fast processor writtin in C.
100 xmllint:        libxml2                  O            Xml Validator. You probably want to install that.
101 fop:            fop                      O            Only needed to generate PDFs. Has a lot of JAVA dependencies.
102 docbook.xsl:    docbook-xsl-stylesheets  M            Necessary docbook catalogs are built automatically by portage in /etc/xml and /etc/sgml
103 chunk.xsl:      docbook-xsl-stylesheets  M              using "/usr/bin/build-docbook-catalog".
104 htmlhelp.xsl:   docbook-xsl-stylesheets  M              So docbook runs out of the box on Gentoo.
105 docbookx.dtd:   docbook-xml-dtd          M
106 jimi:           sun-jimi                 O            Jimi is a class library for managing images. Used by fop.
107 Quanta+         quanta or kdewebdev      O            Nice HTML/XML/SGML and Docbook editor with Syntaxhighlighting, Autocompletion, etc.
108
109 Tip: The actual DTD version of Gentoo is 4.4, but wireshark docs still use 4.2.
110      To be able to generate the docs, change the version in the second line of developer-guide.xml
111      or install an older version of the DTD.
112      See into the Gentoo handbook howto unmask old versions.
113
114 Packages for Fedora Core
115 ------------------------
116 TODO
117
118 Packages for Debian
119 -------------------
120 Tool/File       Package
121 ---------       -------
122 xsltproc:       libxslt
123 xmllint:        libxml2-utils
124 fop:            fop
125 docbook.xsl:    docbook-xsl
126 chunk.xsl:      docbook-xsl
127 htmlhelp.xsl:   docbook-xsl
128 docbookx.dtd:   docbook-xml
129 jimi:           N/A - build yourself - see above
130
131 Makefile:
132 ---------
133 There are several ways and tools to do these conversion, following is a short 
134 description of the way the makefile targets are doing things and which output 
135 files required for a release in that format.
136
137 all
138 Will generate both guide's in all available output formats (see below).
139
140 make wsug
141 Will generate Wireshark User's Guide in all available output formats.
142
143 make wsug_html
144 The HTML file is generated using xsltproc and the XSL stylesheets from 
145 Norman Walsh. This is a conversion into a single HTML page.
146 output: wsug_html
147
148 make wsug_html_chunked
149 The HTML files are generated using xsltproc and the XSL stylesheets from 
150 Norman Walsh. This is a conversion into chunked (multiple) HTML pages.
151 output: wsug_html_chunked
152
153 make wsug_pdf_us
154 make wsug_pdf_a4
155 The PDF is generated using an intermediate format named XSL-FO (XSL 
156 formatting objects). xsltproc converts the XML to a FO file, and then fop 
157 (apache's formatting object processor) is used to generate the PDF document, 
158 in US letter or A4 paper format.
159 TIP: You will get lot's of INFO/WARNING/ERROR messages when generating pdf, 
160 but conversation works just fine.
161 output: user-guide-us.pdf user-guide-a4.pdf
162
163 make wsug_chm
164 On Win32 platforms, the "famous" HTML help format can be generated by using a 
165 special HTML chunked conversion and then use the htmlhelp compiler from 
166 Microsoft.
167 output: htmlhelp.chm
168
169 Using the prefix wsdg_ instead of wsug_ will build the same targets but for the 
170 Wireshark Developer's Guide.
171
172 The makefile is written to be run with gmake on UNIX/Linux platforms. Win32 
173 platforms have to use the cygwin environment (Microsoft nmake is not 
174 supported).
175
176
177 Docbook web references:
178 -----------------------
179 Some web references to further documentation about Docbook/XML and Docbook XSL conversions:
180
181 DocBook: The Definitive Guide
182 by Norman Walsh and Leonard Muellner
183 http://www.docbook.org/tdg/en/html/docbook.html
184
185 DocBook XSL: The Complete Guide
186 by Bob Stayton
187 http://www.sagehill.net/docbookxsl/index.html
188
189 Documention with DocBook on Win32
190 by Jim Crafton
191 http://www.codeproject.com/winhelp/docbook_howto.asp
192
193 FO Parameter Reference
194 by Norman Walsh
195 http://docbook.sourceforge.net/release/xsl/current/doc/fo/
196