- update information to the latest changes

- redesign parts of the file
- remove some redundant information
- remove tabs, tabs don't work well!

svn path=/trunk/; revision=20691

1 files changed, 107 insertions, 66 deletions

diff --git a/docbook/README.txt b/docbook/README.txt
index 23c2630123..88fa6c3008 100644
--- a/docbook/README.txt
+++ b/docbook/README.txt
@@ -2,13 +2,13 @@ $Id$
 
 This directory contains the source files needed to build the:
 
-Wireshark User's guide
+ - Wireshark User's guide
+ - Wireshark Developer's Guide
+ - Release notes (NEWS)
+ - Lua Reference
 
-and the:
 
-Wireshark Developer's Guide  (in an early state).
-
-To build both Guide's, just do 'make', but see requirements below.
+To build everything, just do 'make' - but see requirements below.
 
 
 The guides are written in Docbook/XML (formerly Docbook/SGML). This format is 
@@ -18,118 +18,159 @@ 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 and PDF.
+
+Win32 only: The optional output format CHM has to be enabled by setting 
+HHC_EXE in ..\config.nmake.
 
-By default the Makefile generates HTML in single page and multiple (chunked) formats 
-and PDF. The optional output format CHM has to be enabled in the Makefile.
+
+Settings:
+---------
+
+Unix only: Makefile and catalog.xml
+-----------------------------------------------
+You have to edit the settings in these files, to point to the DTD/XSL files 
+and fop. (Makefile.auto.am is currently experimental and will probably NOT 
+work - any progress on this would be appreciated!)
+
+Win32 only: ..\config.nmake
+---------------------------------------
+Settings moved to: ..\config.nmake.
 
 
 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:
+DocBook "official" XML DTD V4.2: 
 http://www.oasis-open.org/docbook/xml/
-(or using cygwin package docbook-xml42)
+(available as a package for Linux / cygwin)
 
 DocBook XSL
 -----------
-The "official" XSL stylesheets from Norman Walsh:
+The "official" XSL stylesheets from Norman Walsh: 
 http://docbook.sourceforge.net/
-(or using cygwin package docbook-xsl)
+(available as a package for Linux / cygwin)
 
 xsltproc
 --------
 The XSL processor xsltproc. 
-(it seems to be packages libxml2 and libxslt, ... please give comments)
+(available as a package for Linux / cygwin)
+
+xmllint
+-------
+Needed to validate if the .xml files conform to the Docbook/XML DTD. 
+(available as a package for Linux / cygwin)
 
 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.
+I have put the fop-0.20.5 dir right into the docbook sources dir. If you have 
+it somewhere else, you'll have to change the setting in the Makefile 
+(or config.nmake for Win32).
 
-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:
+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
 This should be added automatically on unixish systems.
 
-HTML help compiler (for chm file generation only)
--------------------------------------------------
-hhc compiler from Microsoft:
+JIMI (for PDF generation only)
+------------------------------
+Jimi is a JAVA class library for managing images. 
+In addition to FOP, 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.
+
+Win32 only: HTML help compiler (for .chm generation only)
+---------------------------------------------------------
+hhc compiler (hhc.exe) from Microsoft:
 http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/hwMicrosoftHTMLHelpDownloads.asp 
 
+
+
+Packages for Win32
+------------------
+See ..\config.nmake for Win32 settings.
+
+Tool/File           Cygwin Package          Opt./Mand.  Comments
+---------           --------------          ----------  --------
+xsltproc:           libxslt                 M
+xmllint:            libxml2                 M
+xsl stylesheets:    docbook-xsl             M           docbook.xsl, chunk.xsl and htmlhelp.xsl
+docbookx.dtd:       docbook_xml42           M
+fop:                -                       O           URL: http://xml.apache.org/fop/ - install it into fop-0.20.5 to keep defaults from config.nmake
+jimi:               -                       O           URL: http://java.sun.com/products/jimi/ - see above
+hhc:                -                       O           URL: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/hwMicrosoftHTMLHelpDownloads.asp 
+
+
 Packages for Suse 9.3
 ---------------------
-Tool/File	Package
----------	-------
-xsltproc:	libxslt
-xmllint:	libxml2
-fop:		fop
-docbook.xsl:	docbook-xsl-stylesheets
-chunk.xsl:	docbook-xsl-stylesheets
-htmlhelp.xsl:	docbook-xsl-stylesheets
-docbookx.dtd:	docbook_4
-jimi:		N/A - build yourself - see above
+Tool/File           Package                 Opt./Mand.  Comments
+---------           -------                 ----------  --------
+xsltproc:           libxslt                 M
+xmllint:            libxml2                 M
+xsl stylesheets:    docbook-xsl-stylesheets M           docbook.xsl and chunk.xsl
+docbookx.dtd:       docbook_4               M
+fop:                fop                     O
+jimi:               -                       O           get it from http://java.sun.com/products/jimi/ - see above
+
 
 Packages for Gentoo
 -------------------
-Like with all packages do...
+Like with all packages do ...
 Check dependencies: emerge -p <package>
 Install it:         emerge <package>
 
-Tool/File	Package                  Opt./Mand.   Comments
----------	-------                  ----------   --------
-xsltproc:	libxslt                  M            XSLT processer. A very fast processor writtin in C.
-xmllint:	libxml2                  O            Xml Validator. You probably want to install that.
-fop:		fop                      O            Only needed to generate PDFs. Has a lot of JAVA dependencies.
-docbook.xsl:	docbook-xsl-stylesheets  M            Necessary docbook catalogs are built automatically by portage in /etc/xml and /etc/sgml
-chunk.xsl:	docbook-xsl-stylesheets  M              using "/usr/bin/build-docbook-catalog".
-htmlhelp.xsl:	docbook-xsl-stylesheets  M              So docbook runs out of the box on Gentoo.
-docbookx.dtd:	docbook-xml-dtd          M
-jimi:		sun-jimi                 O            Jimi is a class library for managing images. Used by fop.
-Quanta+         quanta or kdewebdev      O            Nice HTML/XML/SGML and Docbook editor with Syntaxhighlighting, Autocompletion, etc.
+Tool/File           Package                  Opt./Mand.   Comments
+---------           -------                  ----------   --------
+xsltproc:           libxslt                  M            
+xmllint:            libxml2                  M            
+xsl stylesheets:    docbook-xsl-stylesheets  M            docbook.xsl and chunk.xsl
+                                                          Necessary docbook catalogs are built automatically by portage in /etc/xml and /etc/sgml
+                                                            docbook.xsl and chunk.xsl using "/usr/bin/build-docbook-catalog".
+                                                            So docbook runs out of the box on Gentoo.
+docbookx.dtd:       docbook-xml-dtd          M
+fop:                fop                      O            Has a lot of JAVA dependencies.
+jimi:               sun-jimi                 O            Used by fop.
+Quanta+             quanta or kdewebdev      O            Nice HTML/XML/SGML and Docbook editor with Syntaxhighlighting, Autocompletion, etc.
 
 Tip: The actual DTD version of Gentoo is 4.4, but wireshark docs still use 4.2.
      To be able to generate the docs, change the version in the second line of developer-guide.xml
      or install an older version of the DTD.
      See into the Gentoo handbook howto unmask old versions.
 
+
 Packages for Fedora Core
 ------------------------
 TODO
 
+
 Packages for Debian
 -------------------
-Tool/File	Package
----------	-------
-xsltproc:	libxslt
-xmllint:	libxml2-utils
-fop:		fop
-docbook.xsl:	docbook-xsl
-chunk.xsl:	docbook-xsl
-htmlhelp.xsl:	docbook-xsl
-docbookx.dtd:	docbook-xml
-jimi:		N/A - build yourself - see above
-
-Makefile:
----------
+Tool/File           Package
+---------           -------
+xsltproc:           libxslt
+xmllint:            libxml2-utils
+xsl stylesheets:    docbook-xsl
+chunk.xsl:          docbook-xsl
+htmlhelp.xsl:       docbook-xsl
+docbookx.dtd:       docbook-xml
+fop:                fop
+jimi:               http://java.sun.com/products/jimi/ - see above
+
+
+
+Makefile / Makefile.nmake:
+--------------------------
 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.