DocBook XML 4.2 source code for smb.conf(5) documentation for Samba 3.0 Author of the document: Alexander Bokovoy 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 tag by one; - Generates and tags for each . The latter step needs some explanation. We generate automatically and 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.