The first draft of an updated "Ethereal User's Guide" redesigned and updated to the current released Ethereal version 0.10.5.

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

1 files changed, 135 insertions, 0 deletions

diff --git a/docbook/README.txt b/docbook/README.txt
new file mode 100644
index 0000000000..10eb1ebe86
--- /dev/null
+++ b/docbook/README.txt
@@ -0,0 +1,135 @@
+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/