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
|
!==
!== docbook.txt for Samba HEAD
!==
!== 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 ?
-----------------------------------------------------------
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)
* PDF
The Tools
---------
To generate the docs, you need to have the following packages installed:
* docbook-utils
* pdflatex
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 versions).
In order to be able to build some other (more rarely used) formats, you need:
- PostScript:
* LaTeX
* dvips
- Text
* xmlto
Another good tool is 'xmllint' that can be used to check the syntax of
XML files.
|
