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