docs/docbook/smbdotconf/README

   1 DocBook XML 4.2 source code for smb.conf(5) documentation for Samba 3.0
   2
   3 Author of the document: Alexander Bokovoy <ab@samba.org>
   4
   5 Welcome to new smb.conf(5) documentation build system! This directory
   6 contains a new incarnation of Samba's smb.conf(5) Docbook XML 4.2
   7 sources. Note that the output might be unsatisfying untill all smb.conf(5)
   8 parameters will converted to new format (see Chapter 4 for details).
   9
  10 Content
  11 -------
  12
  13 0. Prerequisites
  14 1. Structure
  15 2. XSLT stylesheets
  16 3. Usage
  17 4. Current status of converted parameters
  18
  19 Prerequisites
  20 -------------
  21
  22 In order to compile smb.conf(5) documentation from Docbook XML 4.2
  23 sources you'll need:
  24
  25         - a working libxml2 and libxslt installation, together with xsltproc utility
  26
  27         - a locally installed Docbook XSL 4.2 or higher
  28
  29         - a working xmlcatalog to eliminate Web access for Docbook XSL
  30
  31 The latter requisite is important: we do not specify local copies of
  32 Docbook XSL stylesheets in our XSLTs because of real nightmare in their
  33 location in most distributions. Fortunately, libxml2 provides standard
  34 way to access locally installed external resources via so-called
  35 'xmlcatalog' tool. It is working in RedHat, Mandrake, ALT Linux, and
  36 some other distributions but wasn't at the moment of this writting (Late
  37 March'03) in Debian.
  38
  39 Structure
  40 ---------
  41
  42 smb.conf(5) sources consist of a number of XML files distributed across
  43 a number of subdirectories. Each subdirectory represents a group of
  44 smb.conf(5) parameters dedicated to one specific task as described in
  45 Samba's loadparm.c source  file (and shown in SWAT).
  46
  47 Each XML file in subdirectories represents one parameter description,
  48 together with some additional meta-information about it. Complete list
  49 of meta-information attributes
  50
  51 attribute               description
  52 -------------------------------------------------------------------
  53 name                    smb.conf(5) parameter name
  54 context                 G for global, S for services
  55 basic                   set to 1 if loadparm.c's description
  56 wizard                  includes appropriate flag for
  57 advanced                this parameter (FLAG_BASIC,
  58 developer               FLAG_ADVANCED, FLAG_WIZARD, FLAG_DEVELOPER)
  59 -------------------------------------------------------------------
  60
  61 Main XML file for smb.conf(5) is smb.conf.5.xml. It contains a general
  62 stub for man page and several XML instructions to include:
  63
  64         - a list of global parameters (auto-generated);
  65
  66         - a list of service parameters (auto-generated);
  67
  68         - a complete list of alphabetically sorted parameters (auto-generated).
  69
  70 XSLT stylesheets
  71 ----------------
  72
  73 In order to combine and build final version of smb.conf(5) we apply a
  74 set of XSLT stylesheets to smb.conf(5) sources. Following is the
  75 complete description of existing stylesheets in smb.conf(5) source tree:
  76
  77 1. [expand-smb.conf.xsl] Main driver, produces big XML source with all
  78 smaller components combined. The resulted tree is then feed to Docbook
  79 XSL for final producing.
  80
  81 This stylesheet performs two main transformations:
  82
  83         - Replaces <samba:parameter> tag by <varlistentry> one;
  84
  85         - Generates <term> and <anchor> tags for each <samba:parameter>.
  86
  87 The latter step needs some explanation. We generate automatically
  88 <anchor> and <term> tags based on meta-information about parameter. This
  89 way all anchors have predictable names (capitalized parameter name with
  90 all spaces supressed) and we really don't need to dublicate data.
  91
  92 There was only one exception to the generation rule in smb.conf.5.sgml:
  93 "use spnego"  parameter had anchor SPNEGO which is now unified to
  94 USESPNEGO. This also fixes a bug in SWAT which was unable to find SPNEGO
  95 achnor.
  96
  97 2. [generate-context.xsl] An utility stylesheet which main purpose is to
  98 produce a list of parameters which are applicable for selected context
  99 (global or service).
 100
 101 The generate-context.xsl is run twice to generate both
 102 parameters.global.xml and parameters.service.xml which are included then
 103 by smb.conf.5.xml. This stylesheet relies on parameters.all.xml file
 104 which is generated by [generate-file-list.sh] shell script.
 105
 106 The parameters.all.xml file contains a complete list of include
 107 instructions for XSLT processor to include all small XML files from
 108 subdirectories.
 109
 110 3. [man.xsl] Our local copy of Docbook XML to man(5) transformer. It
 111 fixes some annoying errors in official Docbook XSL stylesheets and adds
 112 our tuned parameters. This file really belongs to upper level where it
 113 would occur later, as we'll move to Docbook XML completely.
 114
 115 4. [split-original-smb.conf.xsl] This stylesheet isn't required anymore.
 116 It was used for initial split of SGML-based smb.conf.5.sgml onto a set
 117 of per-parameter XML files. I left it in source tree just for historical
 118 interest. :)
 119
 120 Usage
 121 -----
 122
 123 1. Generate [parameters.all.xml]:
 124         sh generate-file-list.sh >parameters.all.xml
 125
 126 2. Generate [parameters.global.xml]:
 127         xsltproc --xinclude \
 128                  --param smb.context "'G'" \
 129                  --output parameters.global.xml \
 130                  generate-context.xsl parameters.all.xml
 131
 132 3. Generate [parameters.service.xml]:
 133         xsltproc --xinclude \
 134                  --param smb.context "'S'" \
 135                  --output parameters.service.xml \
 136                  generate-context.xsl parameters.all.xml
 137
 138 4. Process smb.conf.5.xml (for example, to HTML):
 139         xsltproc --xinclude expand-smb.conf.xsl smb.conf.5.xml | \
 140         xsltproc http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl - > smb.conf.5.html
 141
 142 Note that in step 4 we are not saving preprocessed smb.conf.5.xml to
 143 disk and directly passing it to the next XSLT processor (in this case --
 144 Docbook XML to HTML generator).
 145
 146 For convenience, this sequence of commands is added into source tree as
 147 process-all.sh
 148
 149 Current state of converted parameters
 150 -------------------------------------
 151
 152 Only 'base' parameters converted so far to serve as example of
 153 formatting.
 154
 155 All undocumented parameters are listed in doc-status file in of Samba's
 156 docs/ directory.
 157
 158 Any help is greatly appreciated.
 159