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
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
|
DocBook XML 4.2 source code for smb.conf(5) documentation for Samba 3.0
Author of the document: Alexander Bokovoy <ab@samba.org>
Welcome to new smb.conf(5) documentation build system! This directory
contains a new incarnation of Samba's smb.conf(5) Docbook XML 4.2
sources. Note that the output might be unsatisfying untill all smb.conf(5)
parameters will converted to new format (see Chapter 4 for details).
Content
-------
0. Prerequisites
1. Structure
2. XSLT stylesheets
3. Usage
4. Current status of converted parameters
Prerequisites
-------------
In order to compile smb.conf(5) documentation from Docbook XML 4.2
sources you'll need:
- a working libxml2 and libxslt installation, together with xsltproc utility
- a locally installed Docbook XSL 4.2 or higher
- a working xmlcatalog to eliminate Web access for Docbook XSL
The latter requisite is important: we do not specify local copies of
Docbook XSL stylesheets in our XSLTs because of real nightmare in their
location in most distributions. Fortunately, libxml2 provides standard
way to access locally installed external resources via so-called
'xmlcatalog' tool. It is working in RedHat, Mandrake, ALT Linux, and
some other distributions but wasn't at the moment of this writting (Late
March'03) in Debian.
Structure
---------
smb.conf(5) sources consist of a number of XML files distributed across
a number of subdirectories. Each subdirectory represents a group of
smb.conf(5) parameters dedicated to one specific task as described in
Samba's loadparm.c source file (and shown in SWAT).
Each XML file in subdirectories represents one parameter description,
together with some additional meta-information about it. Complete list
of meta-information attributes
attribute description
-------------------------------------------------------------------
name smb.conf(5) parameter name
context G for global, S for services
basic set to 1 if loadparm.c's description
wizard includes appropriate flag for
advanced this parameter (FLAG_BASIC,
developer FLAG_ADVANCED, FLAG_WIZARD, FLAG_DEVELOPER)
-------------------------------------------------------------------
Main XML file for smb.conf(5) is smb.conf.5.xml. It contains a general
stub for man page and several XML instructions to include:
- a list of global parameters (auto-generated);
- a list of service parameters (auto-generated);
- a complete list of alphabetically sorted parameters (auto-generated).
XSLT stylesheets
----------------
In order to combine and build final version of smb.conf(5) we apply a
set of XSLT stylesheets to smb.conf(5) sources. Following is the
complete description of existing stylesheets in smb.conf(5) source tree:
1. [expand-smb.conf.xsl] Main driver, produces big XML source with all
smaller components combined. The resulted tree is then feed to Docbook
XSL for final producing.
This stylesheet performs two main transformations:
- Replaces <samba:parameter> tag by <varlistentry> one;
- Generates <term> and <anchor> tags for each <samba:parameter>.
The latter step needs some explanation. We generate automatically
<anchor> and <term> tags based on meta-information about parameter. This
way all anchors have predictable names (capitalized parameter name with
all spaces supressed) and we really don't need to dublicate data.
There was only one exception to the generation rule in smb.conf.5.sgml:
"use spnego" parameter had anchor SPNEGO which is now unified to
USESPNEGO. This also fixes a bug in SWAT which was unable to find SPNEGO
achnor.
2. [generate-context.xsl] An utility stylesheet which main purpose is to
produce a list of parameters which are applicable for selected context
(global or service).
The generate-context.xsl is run twice to generate both
parameters.global.xml and parameters.service.xml which are included then
by smb.conf.5.xml. This stylesheet relies on parameters.all.xml file
which is generated by [generate-file-list.sh] shell script.
The parameters.all.xml file contains a complete list of include
instructions for XSLT processor to include all small XML files from
subdirectories.
3. [man.xsl] Our local copy of Docbook XML to man(5) transformer. It
fixes some annoying errors in official Docbook XSL stylesheets and adds
our tuned parameters. This file really belongs to upper level where it
would occur later, as we'll move to Docbook XML completely.
4. [split-original-smb.conf.xsl] This stylesheet isn't required anymore.
It was used for initial split of SGML-based smb.conf.5.sgml onto a set
of per-parameter XML files. I left it in source tree just for historical
interest. :)
Usage
-----
1. Generate [parameters.all.xml]:
sh generate-file-list.sh >parameters.all.xml
2. Generate [parameters.global.xml]:
xsltproc --xinclude \
--param smb.context "'G'" \
--output parameters.global.xml \
generate-context.xsl parameters.all.xml
3. Generate [parameters.service.xml]:
xsltproc --xinclude \
--param smb.context "'S'" \
--output parameters.service.xml \
generate-context.xsl parameters.all.xml
4. Process smb.conf.5.xml (for example, to HTML):
xsltproc --xinclude expand-smb.conf.xsl smb.conf.5.xml | \
xsltproc http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl - > smb.conf.5.html
Note that in step 4 we are not saving preprocessed smb.conf.5.xml to
disk and directly passing it to the next XSLT processor (in this case --
Docbook XML to HTML generator).
For convenience, this sequence of commands is added into source tree as
process-all.sh
Current state of converted parameters
-------------------------------------
Only 'base' parameters converted so far to serve as example of
formatting.
All undocumented parameters are listed in doc-status file in of Samba's
docs/ directory.
Any help is greatly appreciated.
|
