README
1!==
2!== docbook.txt for Samba 3.0
3!==
4!== Author: David Bannon, D.Bannon@latrobe.edu.au November, 2000
5!== Updates: Gerald (Jerry) Carter, jerry@samba.org, Feb. 2001
6!== Updates: Jelmer Vernooij, jelmer@samba.org, Aug, 2002
7!== Updates: Jelmer Vernooij, jelmer@samba.org, Jun, 2003
8!== Updates: Jelmer Vernooij, jelmer@samba.org, May, 2004
9!== Updates: Jelmer Vernooij, jelmer@samba.org, May, 2005
10
11Quick start
12-----------
13
14Run:
15
16$ make all
17
18or to see what is possible:
19
20$ make help
21
22What are DocBook documents doing in the Samba Distribution ?
23-----------------------------------------------------------
24
25We have converted all samba docs to XML/DocBook V4.2
26in order to make them easier to maintain and produce a nicer looking
27product.
28
29This short note (strange isn't it how it always starts out as a short note
30and becomes a long one ?) will explain very briefly how and why we have
31done this.
32
33
34The format
35----------
36
37If you are new to xml, regard an xml file as 'source code'. You don't
38read it directly, but use it to create other formats (like the txt and html
39included in ../txtdocs and ../htmldocs).
40
41Docbook is a particular XML style, particularly suited to producing
42technical manuals.
43
44For more information on DocBook tags and format, see "DocBook: The
45Definitive Guide" by Walsh and Muellner, (c) O'Reilly Publishing.
46This book covers DocBook V4.2 and is available on-line
47at http://www.docbook.org/
48
49The Output
50----------
51The current Samba Subversion tree contains the XML/DocBook source files.
52
53A regularly generated version can be found at http://samba.org/samba/docs/.
54
55The Tools
56---------
57
58To generate the docs, you need to have the following packages installed:
59
60 * GNU Make
61 * GNU autoconf
62 * xsltproc
63 * inkscape
64
65For generating PDF and PostScript (thru LaTeX):
66 * dblatex (from http://dblatex.sf.net/)
67
68For generating PDF (thru FO):
69 * fop (http://xml.apache.org/fop/)
70
71For generating ASCII:
72 * html2text
73
74For generating Palm-viewable docs:
75 * plucker-build
76
77For generating texi files:
78 * docbook2x-texi
79 * makeinfo
80
81For validating:
82 * xmllint
83
84This directory now contains a ./configure script and Makefile to
85support the automated building of man pages (including HTML versions), and
86the building of the Samba-HOWTO-Collection and the
87Samba Developers Guide (HTML,TeX,PDF,PS,Text versions).
88
89The configure script detects which of the required utilities are installed
90and builds as much docs as it can using these tools.
91
92Help! Building the docs generates a lot of HTTP traffic...
93----------------------------------------------------------
94
95To be able to build the docs without an internet connection (or faster with
96a slow internet connection), you need to set up "catalogs".
97
98For the Pearson DTD, add something like:
99
100 <public publicId="-//Pearson//DTD Books//DE" uri="file:///home/jelmer/Xml_dtd_1.1/pearson.dtd"/>
101
102For the Samba DTD's, add something like:
103 <rewriteURI uriStartString="http://www.samba.org/samba/DTD" rewritePrefix="file:///home/jelmer/samba-web/DTD"/>
104
105catalog entries for the other DTD's and XSL scripts should be present on your
106system already.
107
108Windows Help files
109----------
110
111http://htmlhelp.berlios.de/howto/mshh4wine.php
112
