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

Michael
(This used to be commit 27bc3ac03f8be222814ff7b77cb3e50b3167a1ef)

1 files changed, 43 insertions, 26 deletions

diff --git a/docs-xml/manpages-3/smb.conf.5.xml b/docs-xml/manpages-3/smb.conf.5.xml
index ff94ab696e..b6d27f4ce7 100644
--- 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>.