I: new smb.conf.5 build system is coming

[Alexander Bokovoy]

Hi all!

I'm commiting a new framework for working with smb.conf(5) Docbook sources
into HEAD docs/docbook/smbdotconf/. It is not yet ready for production
(most of parameters not yet converted to new meta-information description
system) but infrastructure is there and should allow more easily maintain
smb.conf(5).

docs/docbook/smbdotconf/ not yet used for actual Samba documentation
generation but I plan switch somewhere later next week or so when
(hopefully) all information will be updated and other components of SGML
documentation will be converted to XML too (most of them already prepared
but not all).

I'm including doc/docbook/smbdotconf/README below with more detailed
description of structure and internals of new framework.

-----------------------------------------------------------------------
DocBook XML 4.2 source code for smb.conf(5) documentation for Samba 3.0

Author of the document: Alexander Bokovoy <ab at 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 decription
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.

-------------------------------------------------------------------------

-- 
/ Alexander Bokovoy
---
It's not broken, you silly boy.

	- Linus Torvalds offending people on the gcc mailing list