samba-mirror/docs/docbook/docbook.txt

!==
!== 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 ?
-----------------------------------------------------------

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
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.

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
----------

The current Samba CVS tree contains the SGML/DocBook source files as well 
as the following autogenerated formats

  * man pages
  * HTML
  * ASCII text (where appropriate)


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 'included 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/ 

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<6F>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

==========================================================================

This directory now contains a ./configure script and Makefile to 
support the automated building of man pages (including HTML versions).
The DocBook V4.1 DTD and ISO entity files have also been included in CVS
to make sure we are all working from the same plate.

The SGML_CATALOG_FILES environment variable should be set as follows
(this assumes you have a working local installation of jade and
Norman's Walsh's DSSSL stylesheets):

  export SGML_CATALOG_FILES=$SGML_CATALOG_FILES:./dbsgml/catalog


--jerry