forked from osmocom/wireshark
![Ulf Lamping](/assets/img/avatar_default.png)
As generation of output files is a bit tricky, please have a look at the Readme.txt file for instructions. Please send comments and improvements. svn path=/trunk/; revision=11433
136 lines
4.8 KiB
Text
136 lines
4.8 KiB
Text
This directory contains the source files needed to build the:
|
|
|
|
Ethereal User's guide (almost ready to release, has to be reviewed)
|
|
|
|
and the:
|
|
|
|
Ethereal Developer's Guide (long time unchanged still a very early state).
|
|
|
|
To build the User's Guide, just do 'make', but see requirements below.
|
|
The Developer's Guide is currently not generated, as it has no content.
|
|
|
|
|
|
The guides are written in Docbook/XML (formerly Docbook/SGML). This format is
|
|
now used by many other documentation projects, e.g. "the linux documentation
|
|
project" uses it too.
|
|
|
|
To get HTML, PDF or other output formats, conversions are done using XSL
|
|
stylesheets, which provides a flexible way for these conversions.
|
|
|
|
The current Makefile is running under Win32 in the cygwin environment, so it uses
|
|
GNU make and such. It should be pretty easy to use it in UNIX environments too.
|
|
Using Microsoft make (nmake) is not supported.
|
|
|
|
By default the Makefile generates HTML in single page and multiple (chunked) formats.
|
|
Optional output formats are PDF and CHM.
|
|
|
|
|
|
Requirements:
|
|
-------------
|
|
|
|
Settings in Makefile and catalog.xml
|
|
------------------------------------
|
|
You have to edit the settings in these files, to point to the DTD/XSL files, fop (and possibly hhc).
|
|
|
|
DocBook XML DTD
|
|
---------------
|
|
DocBook "official" XML DTD V4.2 from:
|
|
http://www.oasis-open.org/docbook/xml/
|
|
(or using cygwin package docbook-xml42)
|
|
|
|
DocBook XSL
|
|
-----------
|
|
The "official" XSL stylesheets from Norman Walsh:
|
|
http://docbook.sourceforge.net/
|
|
(or using cygwin package docbook-xsl)
|
|
|
|
xsltproc
|
|
--------
|
|
The XSL processor xsltproc.
|
|
(it seems to be packages libxml2 and libxslt, ... please give comments)
|
|
|
|
FOP processor (for PDF generation only)
|
|
---------------------------------------
|
|
FOP processor from the apache project:
|
|
http://xml.apache.org/fop/
|
|
FOP is a JAVA program, so you need to have a JAVA environment installed.
|
|
I have put the fop-0.20.5 dir right into the sources dir. If you have it somewhere else,
|
|
you'll have to change the setting in the Makefile.
|
|
|
|
Be sure to also have installed JAI and/or jimi to be able to use/convert the png graphics files.
|
|
The fop release note webpage tells how to do it:
|
|
download jimi from:
|
|
http://java.sun.com/products/jimi/
|
|
then extract the archive, then copy JimiProClasses.zip to FOP's lib dir and rename it to jimi-1.0.jar.
|
|
|
|
As I got OutOfMemoryException when running fop, I had to insert -Xmx256m into the last line of the fop.bat file from:
|
|
java -cp "%LOCALCLASSPATH%" org.apache.fop.apps.Fop %1 %2 %3 %4 %5 %6 %7 %8
|
|
to:
|
|
java -Xmx256m -cp "%LOCALCLASSPATH%" org.apache.fop.apps.Fop %1 %2 %3 %4 %5 %6 %7 %8
|
|
|
|
HTML help compiler (for chm file generation only)
|
|
-------------------------------------------------
|
|
hhc compiler from Microsoft:
|
|
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/hwMicrosoftHTMLHelpDownloads.asp
|
|
|
|
|
|
Makefile:
|
|
---------
|
|
There are several ways and tools to do these conversion, following is a short
|
|
description of the way the makefile targets are doing things and which output
|
|
files required for a release in that format.
|
|
|
|
all
|
|
Will generate all output formats (see below).
|
|
|
|
make eug_html
|
|
The HTML file is generated using xsltproc and the XSL stylesheets from
|
|
Norman Walsh. This is a conversion into a single HTML page.
|
|
output: eug_html
|
|
|
|
make eug_htmlchunk
|
|
The HTML files are generated using xsltproc and the XSL stylesheets from
|
|
Norman Walsh. This is a conversion into chunked (multiple) HTML pages.
|
|
output: eug_html_chunked
|
|
|
|
make eug_pdf_us
|
|
make eug_pdf_a4
|
|
The PDF is generated using an intermediate format named XSL-FO (XSL
|
|
formatting objects). xsltproc converts the XML to a FO file, and then fop
|
|
(apache's formatting object processor) is used to generate the PDF document,
|
|
in US letter or A4 paper format.
|
|
TIPP: You will get lot's of INFO/WARNING/ERROR messages when generating pdf,
|
|
but conversation works just fine.
|
|
output: user-guide.pdf
|
|
|
|
make eug_chm
|
|
On Win32 platforms, the "famous" HTML help format can be generated by using a
|
|
special HTML chunked conversion and then use the htmlhelp compiler from
|
|
Microsoft.
|
|
output: htmlhelp.chm
|
|
|
|
The makefile is written to be run with gmake on unix/linux platforms. Win32
|
|
platforms have to use the cygwin environment (Microsoft nmake is not
|
|
supported).
|
|
|
|
|
|
Docbook web references:
|
|
-----------------------
|
|
Some web references to further documentation about Docbook/XML and Docbook XSL conversions:
|
|
|
|
DocBook: The Definitive Guide
|
|
by Norman Walsh and Leonard Muellner
|
|
http://www.docbook.org/tdg/en/html/docbook.html
|
|
|
|
DocBook XSL: The Complete Guide
|
|
by Bob Stayton
|
|
http://www.sagehill.net/docbookxsl/index.html
|
|
|
|
Documention with DocBook on Win32
|
|
by Jim Crafton
|
|
http://www.codeproject.com/winhelp/docbook_howto.asp
|
|
|
|
FO Parameter Reference
|
|
by Norman Walsh
|
|
http://docbook.sourceforge.net/release/xsl/current/doc/fo/
|