1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
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
|
