summaryrefslogtreecommitdiff
path: root/docs/docbook/smbdotconf/README
diff options
context:
space:
mode:
Diffstat (limited to 'docs/docbook/smbdotconf/README')
-rw-r--r--docs/docbook/smbdotconf/README159
1 files changed, 0 insertions, 159 deletions
diff --git a/docs/docbook/smbdotconf/README b/docs/docbook/smbdotconf/README
deleted file mode 100644
index e69d30af5f..0000000000
--- a/docs/docbook/smbdotconf/README
+++ /dev/null
@@ -1,159 +0,0 @@
-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.
-