First Release of the DocBook 'source'.

(This used to be commit 6cb727c033822e3e5ff3edc532457df8258beefd)

1 files changed, 107 insertions, 0 deletions

diff --git a/docs/docbook/docbook.txt b/docs/docbook/docbook.txt
new file mode 100644
index 0000000000..a69cf0ff9d
--- /dev/null
+++ b/docs/docbook/docbook.txt
@@ -0,0 +1,107 @@
+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 product.
+
+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.
+--------------
+
+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 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. 
+
+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.
+
+I have not had the need  to make man pages from a DocBook document yet, anyone 
+want to send me some pointers ??
+
+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
+-------------
+
+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 bit messy but once installed is pretty easy. 
+
+On one of my RedHat 6.2 systems I installed the following:
+* sgml-common (as an rpm)
+* docbook  (as an rpm)
+* stylesheets  (as an rpm)
+* jade  (as an rpm)
+* 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 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>
+]>
+
+<style-sheet>
+<style-specification use="docbook">
+<style-specification-body>
+
+(define nochunks #t)			;; Dont make multiple pages
+(define rootchunk #t)			;; Do make a 'root' page
+(define %use-id-as-filename% #t)	;; Use book id as filename	
+(define %html-ext% ".html")		;; give it a proper html extension
+
+</style-specification-body>
+</style-specification>
+<external-specification id="docbook" document="dbstyle">
+</style-sheet>
+
+Note the top block that refers to where the dsssl-157 style sheets are installed, if you 
+don’t put them there make sure you edit the file. 
+
+To use this stylesheet, have it in your working directory along with your sgml files. 
+Jade does the actual conversion to html, call it like this :
+
+jade -t sgml -d html.dsl stuff.sgml
+
+To create the text version run the html through lynx :
+
+Lynx  -dump  -nolist  stuff.html  >  stuff.txt
+
+These instructions are crude by might help someone get going. Please feel free to 
+contact me if you have any questions or if you can correct any one of the many 
+mistakes I must have made above.
+
+David
+
+
+