updated comments on using DocBook.

jerry

1 files changed, 35 insertions, 25 deletions

diff --git a/docs/docbook/docbook.txt b/docs/docbook/docbook.txt
index 37cad901093..7fbc80c25d9 100644
--- a/docs/docbook/docbook.txt
+++ b/docs/docbook/docbook.txt
@@ -1,16 +1,21 @@
+!==
+!== docbook.txt for Samba 2.2.0 release
+!==
+!== Author:	David Bannon, D.Bannon@latrobe.edu.au  November, 2000
+!== Updates:	Gerald (Jerry) Carter, jerry@samba.org, Feb. 2001
+
 What are DocBook documents doing in the Samba Distribution ?
 -----------------------------------------------------------
-By David Bannon, D.Bannon@latrobe.edu.au  November, 2000
-----------------------------------------------------------
 
-We are planning to convert some or all (?) of the samba docs to sgml
-DocBook to make them easier to maintain and produce a nicer looking
+We are planning to convert all of the samba docs to SGML/DocBook V4.1
+in order to make them easier to maintain and produce a nicer looking
 product.
 
-This short note (strange isn’t it how it always starts out as a short note
+This short note (strange isn't it how it always starts out as a short note
 and becomes a long one ?) will explain very briefly how and why we are
 doing this.
 
+
 The format
 ----------
 
@@ -18,37 +23,47 @@ If you are new to sgml, regard an sgml file as 'source code'. You don't
 read it directly, use it to create other formats (like the txt and html
 included in ../txt and ../html).
 
-Docbook is a particular sgml style, particularly suited to producing
+Docbook is a particular SGML style, particularly suited to producing
 technical manuals.  In the two documents I have produced so far I have used
 DocBook 4.1, it seems that products like RedHat Linux is still include only
 version 3.1, the differences are minor. The Linux Documentation Project is
 using a modified version of 3.1 but are really geared up to make multi
 paged documents, something we want to avoid for logistic reasons.
 
+For more information on DocBook tags and format, see "DocBook: The 
+Definitive Guide" by Walsh and Muellner, (c) O'Reilly Publishing.
+This book covers DocBook V3.1 and is available on-line
+at http://www.docbook.org/
+
 The Output
 ----------
 
-Formatted html or xml is easily produced from a DocBook document, however I
-had difficulty making a txt file directly ! It appears that the people who
-make DocBook did not imagine anyone wanting to make plain text from a
-DocBook document. At least one set of sgml tools appears to have decided
-that the easiest way is to make the html and then convert that, this works
-fine.
+The current Samba CVS tree contains the SGML/DocBook source files as well 
+as the following autogenerated formats
 
-I have not had the need to make man pages from a DocBook document yet,
-anyone want to send me some pointers ??
+  * man pages
+  * HTML
+  * ASCII text (where appropriate)
 
-To make file handling and distribution easy I have opted for a single file
-or page per document. In the Samba 2.2 distribution I made an html and a
-txt version of each sgml file and placed that in the appropriate directory
-under ~/doc.
 
 The Tools
 ---------
 
+[
+ addendum: For a good general overview of installing the tools
+ needed for generating files from SGML/DocBook source, refer
+ to the DocBook-Install mini HOWTO at
+ http://www.ibiblio.org/pub/Linux/docs/HOWTO/mini/DocBook-Install
+
+ While the above link is to a Linux HOWTO, the tools can be installed 
+ on almost any UNIX platform.
+
+ David's original notes follow below:
+]
+
 Any sgml document needs to be referred to a suitable style sheet
 (describing syntax) and other sheets that tell the translating programmes
-how to do the translations. The list of necessary 'include’ files is a
+how to do the translations. The list of necessary 'included files is a
 bit messy but once installed is pretty easy.
 
 On one of my RedHat 6.2 systems I installed the following:
@@ -59,19 +74,14 @@ On one of my RedHat 6.2 systems I installed the following:
 * Docbook 4.1 from http://docbook.org
 * DSSSL 157 from http://nwalsh.com/docbook/dsssl/ 
 
-If you would be happy using DocBook 3.1 (and why not ?) then stop after the
-four rpms. If you want to use 4.1 and the current DSSSL then you will need
-a bit of manual editing of the catalog files.
-
 There are several downloadable descriptions of the DocBook syntax at the
 web sites mentioned above. Note that a lot of the docs only talk about
 version 3.1 with 4.1 as an add-on.
 
 In either case you will need to include in the html/docbook.dsl and most
-likely a couple of 'defines’ to achieve a suitable output. I made a
+likely a couple of defines to achieve a suitable output. I made a
 local dsl file that I called html.dsl that looks like this :
 
-
 <!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
 <!ENTITY dbstyle SYSTEM "/usr/lib/sgml/dsssl-157/docbook/html/docbook.dsl" 
 CDATA DSSSL>