diff options
Diffstat (limited to 'docs/docbook/docbook.txt')
-rw-r--r-- | docs/docbook/docbook.txt | 107 |
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 + + + |