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