diff options
Diffstat (limited to 'docs/docbook/docbook.txt')
| -rw-r--r-- | docs/docbook/docbook.txt | 136 |
1 files changed, 136 insertions, 0 deletions
diff --git a/docs/docbook/docbook.txt b/docs/docbook/docbook.txt new file mode 100644 index 00000000000..388cd5cf9b7 --- /dev/null +++ b/docs/docbook/docbook.txt @@ -0,0 +1,136 @@ +!== +!== 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’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 |