manpages: update the section about registry configuration in smb.conf.5

Michael
(This used to be commit 27bc3ac03f8be222814ff7b77cb3e50b3167a1ef)

diff --git a/docs-xml/manpages-3/smb.conf.5.xml b/docs-xml/manpages-3/smb.conf.5.xml
index ff94ab696e09ce75068e1dda0a2eb06bdfa83672..b6d27f4ce7c5e77d3ae83fe5cf3fef4cb7cea93a 100644 (file)
--- a/docs-xml/manpages-3/smb.conf.5.xml
+++ b/docs-xml/manpages-3/smb.conf.5.xml
@@ -725,44 +725,61 @@ chmod 1770 /usr/local/samba/lib/usershares
        <para>
                Starting with Samba version 3.2.0, the capability to
                store Samba configuration in the registry is available.
+               The configuration is stored in the registry key
+                <emphasis><literal>HKLM\Software\Samba\smbconf</literal></emphasis>.
                There are two levels of registry configuration:
        </para>
 
        <orderedlist continuation="restarts" inheritnum="ignore" numeration="arabic">
                <listitem><para>Share definitions stored in registry are used.
                This is triggered by setting the global 
-               parameter <parameter>registry shares</parameter> to <quote>yes</quote> 
-               in <emphasis>smb.conf</emphasis>.
+               parameter <parameter>registry shares</parameter>
+               to <quote>yes</quote> in <emphasis>smb.conf</emphasis>.
                </para>
 
-               <para>Note: Shares defined in <emphasis>smb.conf</emphasis>
-               always take priority over
-               shares of the same name defined in registry.
-               </para></listitem>
-
-               <listitem><para>Global <emphasis>smb.conf</emphasis> options stored in
-               registry are used. This is triggered by the 
-               parameter <smbconfoption name="config backend">registry</smbconfoption> in
-               the [global] section of <emphasis>smb.conf</emphasis>.
-               This removes everything that has been read from config files
+               <para>The registry shares are loaded not at startup but
+               on demand at runtime by <emphasis>smbd</emphasis>.
+               Shares defined in <emphasis>smb.conf</emphasis> take
+               priority over shares of the same name defined in
+               registry.</para></listitem>
+
+               <listitem>
+               <para>Global <emphasis>smb.conf</emphasis>
+               options stored in registry are used. This can be activated
+               in two different ways:</para>
+
+               <para>Firstly, a registry only configuration is triggered
+               by setting
+               <smbconfoption name="config backend">registry</smbconfoption>
+               in the [global] section of <emphasis>smb.conf</emphasis>.
+               This resets everything that has been read from config files
                to this point and reads the content of the global configuration
                section from the registry.
-               Activation of global registry options automatically
-               activates registry shares. In this case, no share definitions
-               from smb.conf are read: This is a registry only configuration
-               with the advantage that share definitions are not read
-               in a bulk at startup time but on demand when a share is
-               accessed.
-               </para></listitem>
+               This is the recommended method of using registry based
+               configuration.</para>
+
+               <para>Secondly, a mixed configuration can be activated
+               by a special new meaning of the parameter
+               <smbconfoption name="include">registry</smbconfoption>
+               in the [global] section of <emphasis>smb.conf</emphasis>.
+               This reads the global options from registry with the same
+               priorities as for an include of a text file.
+               This may be especially useful in cases where an initial
+               configuration is needed to access the registry.</para>
+
+               <para>Activation of global registry options automatically
+               activates registry shares. So in the registry only case,
+               shares are loaded on demand only.</para>
+               </listitem>
        </orderedlist>
 
        <para>
-               Caveat: To make registry-based configurations foolproof at least to a
-               certain extent, the use 
-               of <parameter>lock directory</parameter>, 
-                <parameter>config backend</parameter>, and
-                <parameter>include</parameter> inside the registry
-               configuration has been disabled. Especially, by changing the
+               Note: To make registry-based configurations foolproof
+               at least to a certain extent, the use
+               of <parameter>lock directory</parameter> and
+                <parameter>config backend</parameter>
+               inside the registry configuration has been disabled:
+               Especially by changing the
                 <parameter>lock directory</parameter> inside the registry
                configuration, one would create a broken setup where the daemons
                do not see the configuration they loaded once it is active.
@@ -770,7 +787,7 @@ chmod 1770 /usr/local/samba/lib/usershares
 
        <para>
                The registry configuration can be accessed with
-               tools like <emphasis>regedit</emphasis> or <emphasis>net rpc
+               tools like <emphasis>regedit</emphasis> or <emphasis>net (rpc)
                registry</emphasis> in the key
                 <emphasis><literal>HKLM\Software\Samba\smbconf</literal></emphasis>.