diff options
Diffstat (limited to 'docs/docbook/docbook.txt')
| -rw-r--r-- | docs/docbook/docbook.txt | 91 |
1 files changed, 83 insertions, 8 deletions
diff --git a/docs/docbook/docbook.txt b/docs/docbook/docbook.txt index 019b073b51..388cd5cf9b 100644 --- a/docs/docbook/docbook.txt +++ b/docs/docbook/docbook.txt @@ -1,9 +1,8 @@ !== -!== docbook.txt for Samba HEAD +!== 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 -!== Updates: Jelmer Vernooij, jelmer@samba.org, Aug, 2002 What are DocBook documents doing in the Samba Distribution ? ----------------------------------------------------------- @@ -45,17 +44,93 @@ as the following autogenerated formats * man pages * HTML * ASCII text (where appropriate) - * PDF The Tools --------- -To generate the docs, you need to have the following packages installed: +[ + 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 -* docbook-utils -* htmldoc + 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’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), and -the building of the Samba-HOWTO-Collection (HTML,PDF,PS,Text versions). +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 |