Miscellaneous cleanup of manual, like removing

unneeded comments. (Note some minor changes
not related to the ticket.)

More explanation and clarifications for the zonemgr related features.

I chose to somewhat document the internal commands for now
but note that they are not exposed.
Later these will need to go in a BIND 10 developers docs too.


git-svn-id: svn://bind10.isc.org/svn/bind10/branches/trac341@2942 e5f2f494-b856-4b98-b285-d166d9295462

src/bin/xfrin/b10-xfrin.xml

@@ -103,34 +103,53 @@
     </para>
 
 <!-- TODO: formating -->
-<!-- TODO: refresh is code but not in spec -->
-<!-- schedule immediate maintenance for a zone(check soa serial ) -->
     <para>
       The configuration commands are:
     </para>
 
     <para>
-     <command>notify</command>
-TODO: what is difference from refresh_from_zonemgr ?
+      <command>notify</command> is sent by
+      <citerefentry><refentrytitle>b10-zonemgr</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+      when a DNS NOTIFY message is received to initiate a zone
+      transfer.
+<!-- TODO: document that zonemgr or xfrin checks if it needs to or not -->
+      This is an internal command and not exposed to the administrator.
+<!-- not defined in spec -->
     </para>
 
     <para>
-      <command>refresh</command>
-Same as retransfer except it checks the SOA serial first.
-TODO more detail
+      <command>refresh</command> triggers the transfer in for
+      a single zone.
+      It is the same as <command>retransfer</command> except it
+      checks the SOA serial first.
+<!-- TODO more detail -->
+      This is an internal command and not exposed to the administrator.
+<!-- not defined in spec -->
+<!-- TODO: refresh is code but not in spec, see trac ticket #328 -->
     </para>
 
     <para>
-      <command>refresh_from_zonemgr</command>
+      <command>refresh_from_zonemgr</command> is sent by
+      <citerefentry><refentrytitle>b10-zonemgr</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+      according to the SOA's REFRESH time
+      to tell <command>b10-xfrin</command> that the zone needs to do
+      a zone refresh.
+      This is an internal command and not exposed to the administrator. 
+<!-- not defined in spec -->
     </para>
 
     <para>
       <command>retransfer</command> triggers the transfer in for
       a single zone without checking the zone's serial number.
       It has the following arguments: <varname>zone_name</varname>
-      to define the zone to request and <varname>master</varname>
-      to define the IP address of the authoritative server to
-      transfer from.
+      to define the zone to request,
+      <varname>zone_class</varname> to define the class (defaults to
+      <quote>IN</quote>),
+      <varname>master</varname> to define the IP address of
+      the authoritative server to transfer from,
+      and <varname>port</varname> to define the port number on the
+      authoritative server (defaults to 53).
+<!-- TODO: note: not documenting db_file since that will be removed. -->
      </para>
 <!-- TODO: later hostname for master? -->
 
@@ -144,11 +163,6 @@ add a usage example of xfrin -->
 
 <!-- TODO:
 
-port (defaults to 53)
-db_file (defaults to zone.sqlite3) --> <!-- TODO: fix this -->
-
-<!-- TODO:
-
  later it will can be triggered by :
 1.  Notify message from auth server.
 2.  Schedule zone transfer (determined by Refresh/Expire time in SOA record)

src/bin/xfrout/b10-xfrout.xml

@@ -54,6 +54,7 @@
     <title>DESCRIPTION</title>
     <para>The <command>b10-xfrout</command> daemon provides the BIND 10
       outgoing DNS zone transfer service.
+      It also used to send outgoing NOTIFY messages.
       Normally it is started by the
       <citerefentry><refentrytitle>bind10</refentrytitle><manvolnum>8</manvolnum></citerefentry>
       boss process.
@@ -97,6 +98,7 @@
       defines the path to the SQLite3 data store file.
       The default is
       <filename>/usr/local/var/bind10-devel/zone.sqlite3</filename>.
+<!-- TODO: db_file will be removed -->
     </para>
     <para>
       <varname>transfers_out</varname>
@@ -104,6 +106,9 @@
       that can run concurrently. The default is 10.
     </para>
 
+<!-- TODO: log configurations not documented yet in here. jreed
+     has some but waiting on decisions ... -->
+
     <note><simpara>
       This prototype version uses SQLite3 as its data source backend.
       Future versions will be configurable, supporting multiple
@@ -122,13 +127,14 @@
 
     <para>
       <command>zone_new_data_ready</command> is sent from
-      <command>b10-xfrin</command> to indicate that the zone transferred
-      in successfully.
+      <citerefentry><refentrytitle>b10-xfrin</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+      to indicate that the zone transferred in successfully.
       This triggers <command>b10-xfrout</command> to send NOTIFY
       message(s).
+      This is an internal command and not exposed to the administrator.
+<!-- not defined in spec -->
     </para>
 
-
   </refsect1>
 
 <!--
@@ -182,8 +188,8 @@
   <refsect1>
     <title>HISTORY</title>
     <para>
-      The <command>b10-xfrout</command> daemon was implemented in March 2010
-      by Zhang Likun of CNNIC for the ISC BIND 10 project.
+      The <command>b10-xfrout</command> daemon was first implemented
+      in March 2010 by Zhang Likun of CNNIC for the ISC BIND 10 project.
     </para>
   </refsect1>
 </refentry><!--

src/bin/zonemgr/b10-zonemgr.xml

@@ -90,14 +90,9 @@
 
   <refsect1>
     <title>CONFIGURATION AND COMMANDS</title>
-    <para>
-      The configurable settings are:
-    </para>
 <!--
     <para>
-      <varname>transfers-out</varname>
-      defines the maximum number of outgoing zone transfers
-      that can run concurrently. The default is 10.
+      The configurable settings are:
     </para>
 -->
 
@@ -107,11 +102,14 @@
     </para>
     <para>
       <command>notify</command> (sent by
-      <command>b10-auth</command>) tells <command>b10-zonemgr</command>
+      <citerefentry><refentrytitle>b10-auth</refentrytitle><manvolnum>8</manvolnum></citerefentry>)
+      tells <command>b10-zonemgr</command>
       the zone name and class, and the IP address for the master
       (source of the NOTIFY message).
       This will set the zone's refresh time to now.
 <!-- TODO reword this -->
+      This is an internal command and not exposed to the administrator.
+<!-- not defined in spec -->
     </para>
 
     <para>
@@ -121,19 +119,23 @@
 
     <para>
       <command>zone_new_data_ready</command> is sent from
-      <command>b10-xfrin</command> to indicate that the zone transferred
-      in successfully.
+      <citerefentry><refentrytitle>b10-xfrin</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+      to indicate that the zone transferred in successfully.
+      This is an internal command and not exposed to the administrator.
+<!-- not defined in spec -->
     </para>
 
     <para>
       <command>zone_xfrin_failed</command> is sent from
-      <command>b10-xfrin</command> to indicate a failure
-      (such as transfer-in was incomplete).
+      <citerefentry><refentrytitle>b10-xfrin</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+      to indicate a failure (such as a transfer-in was incomplete).
       The refresh timer for the zone is reset.
 <!--
         """Set zone next refresh time after zone refresh fail.
            now + retry*3/4 <= next_refresh_time <= now + retry
 -->
+      This is an internal command and not exposed to the administrator.
+<!-- not defined in spec -->
     </para>
 
   </refsect1>