[trac2305] various minor documentation changes

add some docbook formatting tags

minor formatting changes.

bindctl -a defaults to 127.0.0.1 not localhost

add a space between "BIND 10"

some rewording

a few punctuation changes

add a sentence to describe an example

doc/guide/bind10-guide.xml

@@ -1296,16 +1296,16 @@ TODO
         <title>bindctl command-line options</title>
         <variablelist>
           <varlistentry>
-            <term>-a &lt;address&gt;, --address=&lt;address&gt;</term>
+            <term>-a <replaceable>&lt;address&gt;</replaceable>, --address=<replaceable>&lt;address&gt;</replaceable></term>
             <listitem>
               <simpara>
-                  IP address that BIND10's <command>b10-cmdctl</command>
-                  module is listening on. By default, this is localhost.
+                  IP address that BIND 10's <command>b10-cmdctl</command>
+                  module is listening on. By default, this is 127.0.0.1.
               </simpara>
             </listitem>
           </varlistentry>
           <varlistentry>
-            <term>-c &lt;certificate file&gt;, --certificate-chain=&lt;certificate file&gt;</term>
+            <term>-c <replaceable>&lt;certificate file&gt;</replaceable>, --certificate-chain=<replaceable>&lt;certificate file&gt;</replaceable></term>
             <listitem>
               <simpara>
                   PEM-formatted server certificate file. When this option is
@@ -1317,15 +1317,16 @@ TODO
             </listitem>
           </varlistentry>
           <varlistentry>
-            <term>--csv-file-dir=&lt;csv file&gt;</term>
+            <term>--csv-file-dir=<replaceable>&lt;csv file&gt;</replaceable></term>
             <listitem>
               <simpara>
                   <command>bindctl</command> stores the username and
-                  password for logging in a file called default_user.csv;
+                  password for logging in a file called
+                  <filename>default_user.csv</filename>;
                   this option specifies the directory where this file is
-                  stored and read from. When not specified, ~/.bind10/ is
-                  used.
-                  <note>At the moment, this file contains an unencrypted password.</note>
+                  stored and read from. When not specified,
+                  <filename>~/.bind10/</filename> is used.
+                  <note>Currently, this file contains an unencrypted password.</note>
               </simpara>
             </listitem>
           </varlistentry>
@@ -1347,10 +1348,10 @@ TODO
             </listitem>
           </varlistentry>
           <varlistentry>
-            <term>-p &lt;port number&gt;, --port=&lt;port number&gt;</term>
+            <term>-p <replaceable>&lt;port number&gt;</replaceable>, --port=<replaceable>&lt;port number&gt;</replaceable></term>
             <listitem>
               <simpara>
-                  Port number that BIND10's <command>b10-cmdctl</command>
+                  Port number that BIND 10's <command>b10-cmdctl</command>
                   module is listening on. By default, this is port 8080.
               </simpara>
             </listitem>
@@ -1360,17 +1361,19 @@ TODO
 
     <section id="bindctl_general_syntax">
         <title>General syntax of bindctl commands</title>
-        The bindctl tool is an interactive command-line tool, with dynamic
-        commands depending on the modules that are running. There are a
-        number of fixed commands that have no module and that are always
+        The <command>bindctl</command> tool is an interactive
+        command-line tool, with dynamic commands depending on the
+        BIND 10 modules that are running. There are a number of
+        fixed commands that have no module and that are always
         available.
 
         The general syntax of a command is
 
-        <screen><userinput>&lt;module&gt; &lt;command&gt; [argument(s)]</userinput></screen>
+        <screen><userinput>&lt;module&gt; &lt;command&gt; <replaceable>[argument(s)]</replaceable></userinput></screen>
+
+        For example, the Boss module has a 'shutdown' command to shut down
+        BIND 10, with an optional argument 'help':
 
-        Example:
-        The Boss module has a shutdown command to shut down BIND 10, with an optional argument 'help':
         <screen><userinput>> Boss shutdown help</userinput>
 Command  shutdown 	(Shut down BIND 10)
 		help (Get help for command)
@@ -1382,7 +1385,7 @@ This command has no parameters
     <section id="bindctl_help">
         <title>Bindctl help</title>
         <command>help</command> is both a command and an option that is available to all other commands. When run as a command directly, it shows the available modules.
-        <screen><userinput>> help</userinput>
+        <screen>&gt; <userinput>help</userinput>
 usage: &lt;module name&gt; &lt;command name&gt; [param1 = value1 [, param2 = value2]]
 Type Tab character to get the hint of module/command/parameters.
 Type "help(? h)" for help on bindctl.
@@ -1390,11 +1393,11 @@ Type "&lt;module_name&gt; help" for help on the specific module.
 Type "&lt;module_name&gt; &lt;command_name&gt; help" for help on the specific command.
 
 Available module names:
-(list of modules)
+<emphasis>(list of modules)</emphasis>
         </screen>
 
-        When run as a command to a module, it shows the commands that module supports:
-        <screen><userinput>> Boss help</userinput>
+        When 'help' is used as a command to a module, it shows the supported commands for the module; for example:
+        <screen>&gt; <userinput>Boss help</userinput>
 Module  Boss 	Master process
 Available commands:
     help        Get help for module.
@@ -1404,8 +1407,8 @@ Available commands:
             List the running BIND 10 processes
         </screen>
 
-    And when added to a module command, it shows the description and parameters of that command:
-    <screen><userinput>> Auth loadzone help</userinput>
+    And when added to a module command, it shows the description and parameters of that specific command; for example:
+    <screen>&gt; <userinput>Auth loadzone help</userinput>
 Command  loadzone 	((Re)load a specified zone)
 		help (Get help for command)
 Parameters:
@@ -1417,18 +1420,19 @@ Parameters:
 
     <section id="bindctl_command_arguments">
         <title>Command arguments</title>
-        The 'loadzone' command of the Auth module, as shown in the last
+        The <command>loadzone</command> command of the Auth
+        module, as shown in the last
         example of the previous section, has two arguments, one of which is
         optional. When using positional arguments they are expected to be
         provided in the order in which 'help' gives them, in this case class
         first and origin second; i.e.
-        <screen><userinput>> Auth loadzone IN example.com.</userinput></screen>
+        <screen>&gt; <userinput>Auth loadzone IN example.com.</userinput></screen>
         But since the class is optional (defaulting to IN), leaving it out
         works as well:
-        <screen><userinput>> Auth loadzone example.com.</userinput></screen>
+        <screen>&gt;<userinput>Auth loadzone example.com.</userinput></screen>
 
         Arguments can also be provided with their names:
-        <screen><userinput>> Auth loadzone origin="example.com." class="IN"</userinput></screen>
+        <screen>&gt; <userinput>Auth loadzone origin="example.com." class="IN"</userinput></screen>
 
         When using this method, the order does not matter.
     </section>
@@ -1436,9 +1440,11 @@ Parameters:
     <section id="bindctl_module_commands">
         <title>Module commands</title>
         Each module has its own set of commands (if any), which will only be
-        available if the module is running. For instance, Auth has a
-        'loadzone' command. The commands a module provides are documented in
-        the section of that module.
+        available if the module is running. For instance, the
+        Auth module has a <command>loadzone</command> command.
+        The commands a module provides are documented in
+        this guide in the section of that module or in the module's
+        corresponding manual page.
     </section>
 
     <section>
@@ -1447,12 +1453,15 @@ Parameters:
         of BIND 10 and its modules. Module configuration is only shown if
         that module is running, but similar to commands, there are a number
         of top-level configuration items that are always available (for
-        instance tsig_keys and data_sources).
+        instance <varname>tsig_keys</varname> and
+        <varname>data_sources</varname>).
 
         Configuration changes (set, unset, add and remove) are done locally
         first, and have no immediate effect. The changes can be viewed with
-        'config diff', and either reverted (config revert), or committed
-        (config commit). In the latter case, all local changes are submitted
+        <command>config diff</command>, and either reverted
+        (<command>config revert</command>), or committed
+        (<command>config commit</command>).
+        In the latter case, all local changes are submitted
         to the configuration manager, which verifies them, and if they are
         accepted, applied and saved in persistent storage.
 
@@ -1460,7 +1469,8 @@ Parameters:
         <screen><userinput>Module/example/item</userinput></screen>
         Sub-elements of names, lists and sets (see <xref linkend=
         "bindctl_configuration_data_types"/>) are separated with the '/'
-        character, and list indices are identified with [&lt;index&gt;].
+        character, and list indices are identified with [<replaceable>&lt;index&gt;</replaceable>]; for example:
+
         <screen><userinput>Module/example/list[2]/foo</userinput></screen>
 
         <section id="bindctl_configuration_command_list">
@@ -1597,7 +1607,7 @@ Parameters:
                 <term>boolean</term>
                 <listitem>
                     <simpara>
-                        A basic boolean value; can be set directly with <command>config set</command>, to either true or false.
+                        A basic boolean value; can be set directly with <command>config set</command>, to either <command>true</command> or <command>false</command>.
                     </simpara>
                 </listitem>
             </varlistentry>
@@ -1624,37 +1634,42 @@ Parameters:
                     <simpara>
                         Maps are (pre-defined) compound collections of other
                         elements of any other type. They are not usually
-                        modified directly, but their elements are; Every
+                        modified directly, but their elements are. Every
                         top-level element for a module is a map containing
                         the configuration values for that map, which can
                         themselves be maps again. For instance, the Auth
                         module configuration is a map containing the
-                        elements 'listen_on' (list) and 'tcp_recv_timeout'
+                        elements '<varname>listen_on</varname>' (list) and '<varname>tcp_recv_timeout</varname>'
                         (integer). When changing one of its values, they can
                         be modified directly with <command>config set
                         Auth/tcp_recv_timeout 3000</command>.
                     </simpara>
                     <simpara>
-                        Some map entries are optional; If they are, and
+                        Some map entries are optional. If they are, and
                         currently have a value, the value can be unset by
-                        using either <command>config unset &lt;item name&gt;
-                        </command> or <command>config set &lt;item name&gt;
+                        using either <command>config unset
+                        <replaceable>&lt;item name&gt;</replaceable>
+                        </command> or <command>config set
+                        <replaceable>&lt;item name&gt;</replaceable>
                         null</command>.
+
                     </simpara>
                     <simpara>
-                        Maps *can* be modified as a whole, but using the
-                        full JSON representation of the entire map to set.
+                        Maps <emphasis>can</emphasis> be modified as a whole,
+                        but using the full JSON representation of
+                        the entire map to set.
+
                         Since this involves a lot of text, this is usually
                         not recommended.
                     </simpara>
                     <simpara>
                         Another example is the Logging virtual module, which
                         is, like any module, a map, but it only contains one
-                        element; a list of loggers. Normally, an
+                        element: a list of loggers. Normally, an
                         administrator would only modify that list (or its
                         elements) directly, but it is possible to set the
-                        entire map in one command:
-                        Example: <command> config set Logging { "loggers": [] } </command>
+                        entire map in one command; for example:
+                        <command> config set Logging { "loggers": [] } </command>
                     </simpara>
                 </listitem>
             </varlistentry>
@@ -1665,19 +1680,21 @@ Parameters:
                     <simpara>
                         A list is a compound list of other elements of the
                         same type; It can be modified by the <command>config
-                        add &lt;list name&gt; [value]</command> and
-                        <command>config remove &lt;list name&gt; [value]</command> or
-                        <command>config remove &lt;list name&gt;[&lt;index&gt;]</command>
+                        add <replaceable>&lt;list name&gt; [value]</replaceable></command> and
+                        <command>config remove <replaceable>&lt;list name&gt; [value]</replaceable></command> or
+                        <command>config remove <replaceable>&lt;list name&gt;</replaceable>[<replaceable>&lt;index&gt;</replaceable>]</command>
                         , to add and remove elements. For addition, if the value is omitted, an entry with default values will be added. For removal, either the index or the full value (in JSON format) needs to be specified.
                     </simpara>
                     <simpara>
-                        Lists can also be used with <command>config set
-                        </command>, but like maps, only by specifying the
+                        Lists can also be used with
+                        <command>config set</command>,
+                        but like maps, only by specifying the
                         entire list value in JSON format.
                     </simpara>
                     <simpara>
-                        List indices are identified with square brackets.
-                        Example: <command> config show Auth/listen_on[1]/port</command>
+                        List indices are identified with square brackets;
+                        for example:
+                        <command> config show Auth/listen_on[1]/port</command>
                     </simpara>
                 </listitem>
             </varlistentry>
@@ -1692,19 +1709,21 @@ Parameters:
                     </simpara>
                     <simpara>
                         Values can be added with
-                        <command>config add &lt;item name&gt; &lt;string&gt; [value]</command>
-                        Where 'string' is the name of the element. If value
+                        <command>config add <replaceable>&lt;item name&gt; &lt;string&gt; [value]</replaceable></command>
+                        where 'string' is the name of the element. If 'value'
                         is ommitted, default values will be used. Elements
-                        can be removed with <command>config remove &lt;item
-                        name&gt; &lt;string&gt;</command>
+                        can be removed with <command>config remove
+                        <replaceable>&lt;item
+                        name&gt; &lt;string&gt;</replaceable></command>
                     </simpara>
                     <simpara>
                         Elements in a named set can be addressed similarly
                         to maps.
                     </simpara>
                     <simpara>
-                        For example, the Boss/components elements is a named
-                        set; adding, showing, and then removing an element
+                        For example, the <command>Boss/components</command>
+                        elements is a named set;
+                        adding, showing, and then removing an element
                         can be done with the following three commands (note
                         the '/'-character versus the space before
                         'example_module'):
@@ -1725,8 +1744,8 @@ Parameters:
                 <listitem>
                     <simpara>
                         The 'any' type is a special type that can have any
-                        form. Apart from that it must consist of elements as
-                        decsribed in this chapter, there is no restriction
+                        form. Apart from that, it must consist of elements as
+                        described in this chapter, there is no restriction
                         on which element types are used. This type is used
                         in places where different data formats could be
                         used. Element modification commands depend on the
@@ -1743,22 +1762,26 @@ Parameters:
 
     <section>
         <title>The execute command</title>
-        The execute command executes a set of commands, either from a file
+        The <command>execute</command> command executes a set of commands,
+        either from a file
         or from a pre-defined set. Currently, the only predefined set is
-        init_authoritative_server, which adds b10-auth, b10-xfrin, and
-        b10-xfrout to the set of components to be started by BIND 10. This
+        <command>init_authoritative_server</command>, which adds
+        <command>b10-auth</command>, <command>b10-xfrin</command>, and
+        <command>b10-xfrout</command> to the set of components to be
+        started by BIND 10. This
         pre-defined set does not commit the changes, so these modules do not
-        show up for commands or configuration until the user enters 'config
-        commit' after 'execute init_authoritative_server'
+        show up for commands or configuration until the user enters
+        <command>config commit</command> after
+        <command>execute init_authoritative_server</command>. For example:
 
-        Example:
-        <screen><userinput>> execute init_authoritative_server</userinput></screen>
-        <screen><userinput>> execute file /tmp/example_commands</userinput></screen>
+        <screen>&gt; <userinput>execute init_authoritative_server</userinput></screen>
 
-        There is an optional argument 'show', which shows the exact set of
-        commands that would be executed.
+        <screen>&gt; <userinput>execute file /tmp/example_commands</userinput></screen>
 
-        <screen><userinput>> execute init_authoritative_server show</userinput>
+        The optional argument <command>show</command> displays the exact set of
+        commands that would be executed; for example:
+
+        <screen>&gt; <userinput>execute init_authoritative_server show</userinput>
 !echo adding Authoritative server component
 config add /Boss/components b10-auth
 config set /Boss/components/b10-auth/kind needed
@@ -1778,6 +1801,10 @@ config set /Boss/components/b10-zonemgr/kind dispensable
 !echo Components added. Please enter "config commit" to
 !echo finalize initial setup and run the components.
         </screen>
+
+        The optional <command>show</command> argument may also be used when
+        executing a script from a file; for example:
+
         <screen><userinput>> execute file /tmp/example_commands show</userinput></screen>
 
         <section id="bindctl_execute_directives">
@@ -1786,10 +1813,11 @@ config set /Boss/components/b10-zonemgr/kind dispensable
             command, a number of directives are supported:
             <variablelist>
               <varlistentry>
-                <term>!echo &lt;string&gt;</term>
+                <term>!echo <replaceable>&lt;string&gt;</replaceable></term>
                 <listitem>
                   <simpara>
-                      Prints the given string to bindctl's output.
+                      Prints the given string to <command>bindctl</command>'s
+                      output.
                   </simpara>
                 </listitem>
               </varlistentry>
@@ -1797,8 +1825,8 @@ config set /Boss/components/b10-zonemgr/kind dispensable
                 <term>!verbose on</term>
                 <listitem>
                   <simpara>
-                      Enables verbose mode; all commands that are to be executed
-                      are printed.
+                      Enables verbose mode; all following commands that are to
+                      be executed are also printed.
                   </simpara>
                 </listitem>
               </varlistentry>
@@ -1806,8 +1834,8 @@ config set /Boss/components/b10-zonemgr/kind dispensable
                 <term>!verbose off</term>
                 <listitem>
                   <simpara>
-                      Disables verbose mode; commands that are to be executed are
-                      no longer printed.
+                      Disables verbose mode; following commands that are to
+                      be executed are no longer printed.
                   </simpara>
                 </listitem>
               </varlistentry>
@@ -1817,7 +1845,8 @@ config set /Boss/components/b10-zonemgr/kind dispensable
         <section id="bindctl_execute_notes">
             <title>Notes on execute scripts</title>
             Within scripts, you can add or remove modules with the normal
-            configuration commands for Boss/components. However, as module
+            configuration commands for <command>Boss/components</command>.
+            However, as module
             configuration and commands do not show up until the module is
             running, it is currently not possible to add a module and set
             its configuration in one script. This will be addressed in the