Add new framework for smb.conf(5). Please read README before trying to compile.

I will commit more meta-information updates during week-end.
(This used to be commit 8d684dffab6a90b3d612a1aa2b2c457a2bc2e6ac)

1 files changed, 159 insertions, 0 deletions

diff --git a/docs/docbook/smbdotconf/README b/docs/docbook/smbdotconf/README
new file mode 100644
index 0000000000..f50a944e7b
--- /dev/null
+++ b/docs/docbook/smbdotconf/README
@@ -0,0 +1,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 'ads server' parameter 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.
+