diff options
Diffstat (limited to 'docs/docbook/smbdotconf/README')
| -rw-r--r-- | docs/docbook/smbdotconf/README | 158 |
1 files changed, 158 insertions, 0 deletions
diff --git a/docs/docbook/smbdotconf/README b/docs/docbook/smbdotconf/README new file mode 100644 index 0000000000..9a037149ad --- /dev/null +++ b/docs/docbook/smbdotconf/README @@ -0,0 +1,158 @@ +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 'misc' parameters don't converted so far. + +All undocumented parameters are listed in doc-status file in of Samba's +docs/ directory. + +Any help is greatly appreciated. + |