List:Commits« Previous MessageNext Message »
From:paul Date:January 30 2006 2:01am
Subject:svn commit - mysqldoc@docsrva: r1114 - in trunk: . refman-4.1 refman-5.0 refman-5.1
View as plain text  
Author: paul
Date: 2006-01-30 03:01:41 +0100 (Mon, 30 Jan 2006)
New Revision: 1114

Log:
 r6882@frost:  paul | 2006-01-29 19:16:30 -0600
 General revisions.


Modified:
   trunk/
   trunk/refman-4.1/replication.xml
   trunk/refman-5.0/replication.xml
   trunk/refman-5.1/replication.xml


Property changes on: trunk
___________________________________________________________________
Name: svk:merge
   - b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:6880
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:2588
   + b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:6882
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:2588

Modified: trunk/refman-4.1/replication.xml
===================================================================
--- trunk/refman-4.1/replication.xml	2006-01-30 00:03:51 UTC (rev 1113)
+++ trunk/refman-4.1/replication.xml	2006-01-30 02:01:41 UTC (rev 1114)
@@ -2235,7 +2235,8 @@
     <remark role="todo">
       This section says that it describes slave options, but there are
       master options that need to be listed as well, like
-      show-slave-auth-info.
+      show-slave-auth-info. Also, we should describe some of the
+      relevant system variables, such as sync_binlog?
     </remark>
 
     <remark role="todo">
@@ -2245,30 +2246,30 @@
     </remark>
 
     <para>
-      On both the master and the slave, you must use the
+      This section describes the options that you can use on slave
+      replication servers. You can specify these options either on the
+      command line or in an option file.
+    </para>
+
+    <para>
+      On the master and each slave, you must use the
       <literal>server-id</literal> option to establish a unique
-      replication ID for each server. You should pick a unique positive
+      replication ID. For each server, you should pick a unique positive
       integer in the range from 1 to 2<superscript>32</superscript>
-      &minus; 1 for each master and slave. Example:
-      <literal>server-id=3</literal>
+      &minus; 1, and each ID must be different from every other ID.
+      Example: <literal>server-id=3</literal>
     </para>
 
     <para>
-      The options that you can use on the master server for controlling
+      Options that you can use on the master server for controlling
       binary logging are described in <xref linkend="binary-log"/>.
     </para>
 
     <para>
-      The following table describes the options you can use on slave
-      replication servers. You can specify them on the command line or
-      in an option file.
-    </para>
-
-    <para>
       Some slave server replication options are handled in a special
-      way, in the sense that they are ignored if a
+      way, in the sense that each is ignored if a
       <filename>master.info</filename> file exists when the slave starts
-      and contains values for the options. The following options are
+      and contains a value for the option. The following options are
       handled this way:
     </para>
 
@@ -2376,13 +2377,10 @@
 
     <para>
       If the <filename>master.info</filename> file exists when the slave
-      server starts, the server ignores those options. Instead, it uses
-      the values found in the <filename>master.info</filename> file.
-    </para>
-
-    <para>
-      If you restart the slave server with different values of the
-      startup options that correspond to values in the
+      server starts, the server uses its contents and ignores any
+      options that correspond to the values listed in the file. Thus, if
+      you start the slave server with different values of the startup
+      options that correspond to values in the
       <filename>master.info</filename> file, the different values have
       no effect, because the server continues to use the
       <filename>master.info</filename> file. To use different values,
@@ -2399,7 +2397,7 @@
 
 <programlisting>
 [mysqld]
-master-host=some_host
+master-host=<replaceable>some_host</replaceable>
 </programlisting>
 
     <para>
@@ -2411,8 +2409,8 @@
       <filename>master.info</filename> file only and ignores the value
       in the option file. If you modify the <filename>my.cnf</filename>
       file to specify a different master host of
-      <literal>some_other_host</literal>, the change still has no
-      effect. You should use <literal>CHANGE MASTER TO</literal>
+      <replaceable>some_other_host</replaceable>, the change still has
+      no effect. You should use <literal>CHANGE MASTER TO</literal>
       instead.
     </para>
 
@@ -2441,15 +2439,24 @@
 report-host=db-slave.mycompany.com
 </programlisting>
 
+    <remark role="todo">
+      [pd] Is this a promise we should make?
+    </remark>
+
     <para>
       The following list describes startup options for controlling
-      replication: Many of these options can be reset while the server
+      replication. Many of these options can be reset while the server
       is running by using the <literal>CHANGE MASTER TO</literal>
       statement. Others, such as the <option>--replicate-*</option>
       options, can be set only when the slave server starts. We plan to
       fix this.
     </para>
 
+    <remark role="todo">
+      Add this: Replication-related system variables are discussed later
+      in this section.
+    </remark>
+
     <itemizedlist>
 
       <listitem>
@@ -2458,14 +2465,15 @@
         </para>
 
         <para>
-          Normally, updates received from a master server by a slave are
-          not logged to its binary log. This option tells the slave to
-          log the updates performed by its SQL thread to the slave's own
-          binary log. For this option to have any effect, the slave must
-          also be started with the <option>--log-bin</option> option to
-          enable binary logging. <option>--log-slave-updates</option> is
-          used when you want to chain replication servers. For example,
-          you might want a setup like this:
+          Normally, a slave does not log to its own binary log any
+          updates that are received from a master server. This option
+          tells the slave to log the updates performed by its SQL thread
+          to its own binary log. For this option to have any effect, the
+          slave must also be started with the <option>--log-bin</option>
+          option to enable binary logging.
+          <option>--log-slave-updates</option> is used when you want to
+          chain replication servers. For example, you might want to set
+          up replication servers using this arrangement:
         </para>
 
 <programlisting>
@@ -2473,12 +2481,13 @@
 </programlisting>
 
         <para>
-          That is, A serves as the master for the slave B, and B serves
-          as the master for the slave C. For this to work, B must be
-          both a master <emphasis>and</emphasis> a slave. You must start
-          both A and B with <option>--log-bin</option> to enable binary
+          Here, A serves as the master for the slave B, and B serves as
+          the master for the slave C. For this to work, B must be both a
+          master <emphasis>and</emphasis> a slave. You must start both A
+          and B with <option>--log-bin</option> to enable binary
           logging, and B with the <option>--log-slave-updates</option>
-          option.
+          option so that updates received from A are logged by B to its
+          binary log.
         </para>
       </listitem>
 
@@ -2488,14 +2497,15 @@
         </para>
 
         <para>
-          Make the slave print more messages to the error log about what
-          it is doing. For example, it warns you that it succeeded in
-          reconnecting after a network/connection failure, and warns you
-          about how each slave thread started. This option is enabled by
-          default as of MySQL 4.0.19 and 4.1.2; to disable it, use
-          <option>--skip-log-warnings</option>. As of MySQL 4.0.21 and
-          4.1.3, aborted connections are not logged to the error log
-          unless the value is greater than 1.
+          This option causes a server to print more messages to the
+          error log about what it is doing. With respect to replication,
+          the server generates warnings that it succeeded in
+          reconnecting after a network/connection failure, and informs
+          you as to how each slave thread started. This option is
+          enabled by default as of MySQL 4.0.19 and 4.1.2; to disable
+          it, use <option>--skip-log-warnings</option>. As of MySQL
+          4.0.21 and 4.1.3, aborted connections are not logged to the
+          error log unless the value is greater than 1.
         </para>
 
         <para>
@@ -2511,9 +2521,9 @@
         </para>
 
         <para>
-          The number of seconds the slave thread sleeps before retrying
-          to connect to the master in case the master goes down or the
-          connection is lost. The value in the
+          The number of seconds that the slave thread sleeps before
+          trying to reconnect to the master in case the master goes down
+          or the connection is lost. The value in the
           <filename>master.info</filename> file takes precedence if it
           can be read. If not set, the default is 60.
         </para>
@@ -2521,14 +2531,14 @@
 
       <listitem>
         <para>
-          <option>--master-host=<replaceable>host</replaceable></option>
+          <option>--master-host=<replaceable>host_name</replaceable></option>
         </para>
 
         <para>
-          The hostname or IP number of the master replication server. If
-          this option is not given, the slave thread does not start. The
-          value in <filename>master.info</filename> takes precedence if
-          it can be read.
+          The hostname or IP number of the master replication server.
+          The value in <filename>master.info</filename> takes precedence
+          if it can be read. If no master host is specified, the slave
+          thread does not start.
         </para>
       </listitem>
 
@@ -2551,9 +2561,9 @@
 
         <para>
           The password of the account that the slave thread uses for
-          authentication when connecting to the master. The value in the
-          <filename>master.info</filename> file takes precedence if it
-          can be read. If not set, an empty password is assumed.
+          authentication when it connects to the master. The value in
+          the <filename>master.info</filename> file takes precedence if
+          it can be read. If not set, an empty password is assumed.
         </para>
       </listitem>
 
@@ -2563,11 +2573,10 @@
         </para>
 
         <para>
-          The TCP/IP port the master is listening on. The value in the
-          <filename>master.info</filename> file takes precedence if it
-          can be read. If not set, the compiled-in setting is assumed.
-          If you have not tinkered with <command>configure</command>
-          options, this should be 3306.
+          The TCP/IP port number that the master is listening on. The
+          value in the <filename>master.info</filename> file takes
+          precedence if it can be read. If not set, the compiled-in
+          setting is assumed (normally 3306).
         </para>
       </listitem>
 
@@ -2577,8 +2586,8 @@
         </para>
 
         <para>
-          The number of times the slave tries to connect to the master
-          before giving up.
+          The number of times that the slave tries to connect to the
+          master before giving up.
         </para>
       </listitem>
 
@@ -2598,7 +2607,7 @@
           the same as the corresponding <option>--ssl</option>,
           <option>--ssl-ca</option>, <option>--ssl-capath</option>,
           <option>--ssl-cert</option>, <option>--ssl-cipher</option>,
-          <option>--ssl-key</option> options described in
+          <option>--ssl-key</option> options that are described in
           <xref linkend="ssl-options"/>. The values in the
           <filename>master.info</filename> file take precedence if they
           can be read.
@@ -2611,29 +2620,33 @@
 
       <listitem>
         <para>
-          <option>--master-user=<replaceable>username</replaceable></option>
+          <option>--master-user=<replaceable>user_name</replaceable></option>
         </para>
 
         <para>
           The username of the account that the slave thread uses for
-          authentication when connecting to the master. The account must
-          have the <literal>REPLICATION SLAVE</literal> privilege.
-          (Prior to MySQL 4.0.2, it must have the
+          authentication when it connects to the master. This account
+          must have the <literal>REPLICATION SLAVE</literal> privilege.
           <literal>FILE</literal> privilege instead.) The value in the
-          <filename>master.info</filename> file takes precedence if it
-          can be read. If the master user is not set, user
+          <filename>master.info</filename> file, if it can be read,
+          takes precedence. If the master username is not set, the name
           <literal>test</literal> is assumed.
         </para>
       </listitem>
 
       <listitem>
+        <remark role="todo">
+          [pd]This is really a system variable, not an option.
+        </remark>
+
         <para>
           <option>--max-relay-log-size=<replaceable>size</replaceable></option>
         </para>
 
         <para>
-          To rotate the relay log automatically. See
-          <xref linkend="server-system-variables"/>.
+          The size at which the server rotates relay log files
+          automatically. For more information, see
+          <xref linkend="slave-logs"/>.
         </para>
 
         <para>
@@ -2649,7 +2662,7 @@
         <para>
           Cause the slave to allow no updates except from slave threads
           or from users with the <literal>SUPER</literal> privilege.
-          This can be useful to ensure that a slave server accepts no
+          This enables you to ensure that a slave server accepts no
           updates from clients.
         </para>
 
@@ -2684,11 +2697,12 @@
         </para>
 
         <para>
-          The location and name that should be used for the relay log
-          index file. The default name is
-          <literal><replaceable>host_name</replaceable>-relay-bin.index</literal>,
-          where <replaceable>host_name</replaceable> is the name of the
-          slave server.
+          The name to use for the relay log index file. The default name
+          is
+          <filename><replaceable>host_name</replaceable>-relay-bin.index</filename>
+          in the data directory, where
+          <replaceable>host_name</replaceable> is the name of the slave
+          server.
         </para>
       </listitem>
 
@@ -2705,6 +2719,10 @@
       </listitem>
 
       <listitem>
+        <remark role="todo">
+          [pd]This is really a system variable, not an option.
+        </remark>
+
         <para>
           <option>--relay-log-purge={0|1}</option>
         </para>
@@ -3179,6 +3197,11 @@
 
     </itemizedlist>
 
+    <remark role="todo">
+      Add here: Discuss replication-related system variables.
+      sync_binlog.
+    </remark>
+
   </section>
 
   <section id="replication-rules">

Modified: trunk/refman-5.0/replication.xml
===================================================================
--- trunk/refman-5.0/replication.xml	2006-01-30 00:03:51 UTC (rev 1113)
+++ trunk/refman-5.0/replication.xml	2006-01-30 02:01:41 UTC (rev 1114)
@@ -2143,7 +2143,8 @@
     <remark role="todo">
       This section says that it describes slave options, but there are
       master options that need to be listed as well, like
-      show-slave-auth-info.
+      show-slave-auth-info. Also, we should describe some of the
+      relevant system variables, such as sync_binlog?
     </remark>
 
     <remark role="todo">
@@ -2153,30 +2154,30 @@
     </remark>
 
     <para>
-      On both the master and the slave, you must use the
+      This section describes the options that you can use on slave
+      replication servers. You can specify these options either on the
+      command line or in an option file.
+    </para>
+
+    <para>
+      On the master and each slave, you must use the
       <literal>server-id</literal> option to establish a unique
-      replication ID for each server. You should pick a unique positive
+      replication ID. For each server, you should pick a unique positive
       integer in the range from 1 to 2<superscript>32</superscript>
-      &minus; 1 for each master and slave. Example:
-      <literal>server-id=3</literal>
+      &minus; 1, and each ID must be different from every other ID.
+      Example: <literal>server-id=3</literal>
     </para>
 
     <para>
-      The options that you can use on the master server for controlling
+      Options that you can use on the master server for controlling
       binary logging are described in <xref linkend="binary-log"/>.
     </para>
 
     <para>
-      The following table describes the options you can use on MySQL
-      &current-series; slave replication servers. You can specify these
-      options either on the command line or in an option file.
-    </para>
-
-    <para>
       Some slave server replication options are handled in a special
-      way, in the sense that they are ignored if a
+      way, in the sense that each is ignored if a
       <filename>master.info</filename> file exists when the slave starts
-      and contains values for the options. The following options are
+      and contains a value for the option. The following options are
       handled this way:
     </para>
 
@@ -2251,11 +2252,11 @@
     </itemizedlist>
 
     <para>
-      The <filename>master.info</filename> file format in
+      The <filename>master.info</filename> file format in MySQL
       &current-series; includes values corresponding to the SSL options.
       In addition, the file format includes as its first line the number
-      of lines in the file. If you upgrade an older server to a newer
-      version, the new server upgrades the
+      of lines in the file. If you upgrade an older server (before MySQL
+      4.1.1) to a newer version, the new server upgrades the
       <filename>master.info</filename> file to the new format
       automatically when it starts. However, if you downgrade a newer
       server to an older version, you should remove the first line
@@ -2273,13 +2274,10 @@
 
     <para>
       If the <filename>master.info</filename> file exists when the slave
-      server starts, the server ignores those options. Instead, it uses
-      the values found in the <filename>master.info</filename> file.
-    </para>
-
-    <para>
-      If you restart the slave server with different values of the
-      startup options that correspond to values in the
+      server starts, the server uses its contents and ignores any
+      options that correspond to the values listed in the file. Thus, if
+      you start the slave server with different values of the startup
+      options that correspond to values in the
       <filename>master.info</filename> file, the different values have
       no effect, because the server continues to use the
       <filename>master.info</filename> file. To use different values,
@@ -2296,7 +2294,7 @@
 
 <programlisting>
 [mysqld]
-master-host=some_host
+master-host=<replaceable>some_host</replaceable>
 </programlisting>
 
     <para>
@@ -2308,8 +2306,8 @@
       <filename>master.info</filename> file only and ignores the value
       in the option file. If you modify the <filename>my.cnf</filename>
       file to specify a different master host of
-      <literal>some_other_host</literal>, the change still has no
-      effect. You should use <literal>CHANGE MASTER TO</literal>
+      <replaceable>some_other_host</replaceable>, the change still has
+      no effect. You should use <literal>CHANGE MASTER TO</literal>
       instead.
     </para>
 
@@ -2338,15 +2336,24 @@
 report-host=db-slave.mycompany.com
 </programlisting>
 
+    <remark role="todo">
+      [pd] Is this a promise we should make?
+    </remark>
+
     <para>
       The following list describes startup options for controlling
-      replication: Many of these options can be reset while the server
+      replication. Many of these options can be reset while the server
       is running by using the <literal>CHANGE MASTER TO</literal>
       statement. Others, such as the <option>--replicate-*</option>
       options, can be set only when the slave server starts. We plan to
       fix this.
     </para>
 
+    <remark role="todo">
+      Add this: Replication-related system variables are discussed later
+      in this section.
+    </remark>
+
     <itemizedlist>
 
       <listitem>
@@ -2355,14 +2362,15 @@
         </para>
 
         <para>
-          Normally, updates received from a master server by a slave are
-          not logged to its binary log. This option tells the slave to
-          log the updates performed by its SQL thread to the slave's own
-          binary log. For this option to have any effect, the slave must
-          also be started with the <option>--log-bin</option> option to
-          enable binary logging. <option>--log-slave-updates</option> is
-          used when you want to chain replication servers. For example,
-          you might want a setup like this:
+          Normally, a slave does not log to its own binary log any
+          updates that are received from a master server. This option
+          tells the slave to log the updates performed by its SQL thread
+          to its own binary log. For this option to have any effect, the
+          slave must also be started with the <option>--log-bin</option>
+          option to enable binary logging.
+          <option>--log-slave-updates</option> is used when you want to
+          chain replication servers. For example, you might want to set
+          up replication servers using this arrangement:
         </para>
 
 <programlisting>
@@ -2370,12 +2378,13 @@
 </programlisting>
 
         <para>
-          That is, A serves as the master for the slave B, and B serves
-          as the master for the slave C. For this to work, B must be
-          both a master <emphasis>and</emphasis> a slave. You must start
-          both A and B with <option>--log-bin</option> to enable binary
+          Here, A serves as the master for the slave B, and B serves as
+          the master for the slave C. For this to work, B must be both a
+          master <emphasis>and</emphasis> a slave. You must start both A
+          and B with <option>--log-bin</option> to enable binary
           logging, and B with the <option>--log-slave-updates</option>
-          option.
+          option so that updates received from A are logged by B to its
+          binary log.
         </para>
       </listitem>
 
@@ -2385,21 +2394,16 @@
         </para>
 
         <para>
-          Make the slave print more messages to the error log about what
-          it is doing. For example, it warns you that it succeeded in
+          This option causes a server to print more messages to the
+          error log about what it is doing. With respect to replication,
+          the server generates warnings that it succeeded in
           reconnecting after a network/connection failure, and informs
           you as to how each slave thread started. This option is
           enabled by default; to disable it, use
           <option>--skip-log-warnings</option>. Aborted connections are
           not logged to the error log unless the value is greater than
-          <literal>1</literal>.
+          1.
         </para>
-
-        <para>
-          Note that the effects of this option are not limited to
-          replication. It produces warnings across a spectrum of server
-          activities.
-        </para>
       </listitem>
 
       <listitem>
@@ -2408,9 +2412,9 @@
         </para>
 
         <para>
-          The number of seconds the slave thread sleeps before retrying
-          to connect to the master in case the master goes down or the
-          connection is lost. The value in the
+          The number of seconds that the slave thread sleeps before
+          trying to reconnect to the master in case the master goes down
+          or the connection is lost. The value in the
           <filename>master.info</filename> file takes precedence if it
           can be read. If not set, the default is 60.
         </para>
@@ -2418,14 +2422,14 @@
 
       <listitem>
         <para>
-          <option>--master-host=<replaceable>host</replaceable></option>
+          <option>--master-host=<replaceable>host_name</replaceable></option>
         </para>
 
         <para>
-          The hostname or IP number of the master replication server. If
-          this option is not given, the slave thread does not start. The
-          value in <filename>master.info</filename> takes precedence if
-          it can be read.
+          The hostname or IP number of the master replication server.
+          The value in <filename>master.info</filename> takes precedence
+          if it can be read. If no master host is specified, the slave
+          thread does not start.
         </para>
       </listitem>
 
@@ -2448,9 +2452,9 @@
 
         <para>
           The password of the account that the slave thread uses for
-          authentication when connecting to the master. The value in the
-          <filename>master.info</filename> file takes precedence if it
-          can be read. If not set, an empty password is assumed.
+          authentication when it connects to the master. The value in
+          the <filename>master.info</filename> file takes precedence if
+          it can be read. If not set, an empty password is assumed.
         </para>
       </listitem>
 
@@ -2460,11 +2464,10 @@
         </para>
 
         <para>
-          The TCP/IP port the master is listening on. The value in the
-          <filename>master.info</filename> file takes precedence if it
-          can be read. If not set, the compiled-in setting is assumed.
-          If you have not tinkered with <command>configure</command>
-          options, this should be 3306.
+          The TCP/IP port number that the master is listening on. The
+          value in the <filename>master.info</filename> file takes
+          precedence if it can be read. If not set, the compiled-in
+          setting is assumed (normally 3306).
         </para>
       </listitem>
 
@@ -2474,8 +2477,8 @@
         </para>
 
         <para>
-          The number of times the slave tries to connect to the master
-          before giving up.
+          The number of times that the slave tries to connect to the
+          master before giving up.
         </para>
       </listitem>
 
@@ -2495,7 +2498,7 @@
           the same as the corresponding <option>--ssl</option>,
           <option>--ssl-ca</option>, <option>--ssl-capath</option>,
           <option>--ssl-cert</option>, <option>--ssl-cipher</option>,
-          <option>--ssl-key</option> options described in
+          <option>--ssl-key</option> options that are described in
           <xref linkend="ssl-options"/>. The values in the
           <filename>master.info</filename> file take precedence if they
           can be read.
@@ -2504,27 +2507,32 @@
 
       <listitem>
         <para>
-          <option>--master-user=<replaceable>username</replaceable></option>
+          <option>--master-user=<replaceable>user_name</replaceable></option>
         </para>
 
         <para>
           The username of the account that the slave thread uses for
-          authentication when connecting to the master. This account
+          authentication when it connects to the master. This account
           must have the <literal>REPLICATION SLAVE</literal> privilege.
           The value in the <filename>master.info</filename> file, if it
-          can be read, takes precedence. If the master user is not set,
-          user <literal>test</literal> is assumed.
+          can be read, takes precedence. If the master username is not
+          set, the name <literal>test</literal> is assumed.
         </para>
       </listitem>
 
       <listitem>
+        <remark role="todo">
+          [pd]This is really a system variable, not an option.
+        </remark>
+
         <para>
           <option>--max-relay-log-size=<replaceable>size</replaceable></option>
         </para>
 
         <para>
-          To rotate the relay log automatically. See
-          <xref linkend="server-system-variables"/>.
+          The size at which the server rotates relay log files
+          automatically. For more information, see
+          <xref linkend="slave-logs"/>.
         </para>
       </listitem>
 
@@ -2536,7 +2544,7 @@
         <para>
           Cause the slave to allow no updates except from slave threads
           or from users having the <literal>SUPER</literal> privilege.
-          This can be useful to ensure that a slave server accepts no
+          This enables you to ensure that a slave server accepts no
           updates from clients. As of MySQL 5.0.16, this option does not
           apply to <literal>TEMPORARY</literal> tables.
         </para>
@@ -2568,11 +2576,12 @@
         </para>
 
         <para>
-          The location and name that should be used for the relay log
-          index file. The default name is
-          <literal><replaceable>host_name</replaceable>-relay-bin.index</literal>,
-          where <replaceable>host_name</replaceable> is the name of the
-          slave server.
+          The name to use for the relay log index file. The default name
+          is
+          <filename><replaceable>host_name</replaceable>-relay-bin.index</filename>
+          in the data directory, where
+          <replaceable>host_name</replaceable> is the name of the slave
+          server.
         </para>
       </listitem>
 
@@ -2589,6 +2598,10 @@
       </listitem>
 
       <listitem>
+        <remark role="todo">
+          [pd]This is really a system variable, not an option.
+        </remark>
+
         <para>
           <option>--relay-log-purge={0|1}</option>
         </para>
@@ -3049,6 +3062,11 @@
 
     </itemizedlist>
 
+    <remark role="todo">
+      Add here: Discuss replication-related system variables.
+      sync_binlog.
+    </remark>
+
   </section>
 
   <section id="replication-rules">

Modified: trunk/refman-5.1/replication.xml
===================================================================
--- trunk/refman-5.1/replication.xml	2006-01-30 00:03:51 UTC (rev 1113)
+++ trunk/refman-5.1/replication.xml	2006-01-30 02:01:41 UTC (rev 1114)
@@ -2283,7 +2283,8 @@
     <remark role="todo">
       This section says that it describes slave options, but there are
       master options that need to be listed as well, like
-      show-slave-auth-info.
+      show-slave-auth-info. Also, we should describe some of the
+      relevant system variables, such as sync_binlog?
     </remark>
 
     <remark role="todo">
@@ -2293,30 +2294,30 @@
     </remark>
 
     <para>
-      On both the master and the slave, you must use the
+      This section describes the options that you can use on
+      slave replication servers. You can specify these
+      options either on the command line or in an option file.
+    </para>
+
+    <para>
+      On the master and each slave, you must use the
       <literal>server-id</literal> option to establish a unique
-      replication ID for each server. You should pick a unique positive
+      replication ID. For each server, you should pick a unique positive
       integer in the range from 1 to 2<superscript>32</superscript>
-      &minus; 1 for each master and slave. Example:
-      <literal>server-id=3</literal>
+      &minus; 1, and each ID must be different from every other ID.
+      Example: <literal>server-id=3</literal>
     </para>
 
     <para>
-      The options that you can use on the master server for controlling
+      Options that you can use on the master server for controlling
       binary logging are described in <xref linkend="binary-log"/>.
     </para>
 
     <para>
-      The following table describes the options you can use on MySQL
-      &current-series; slave replication servers. You can specify these
-      options either on the command line or in an option file.
-    </para>
-
-    <para>
       Some slave server replication options are handled in a special
-      way, in the sense that they are ignored if a
+      way, in the sense that each is ignored if a
       <filename>master.info</filename> file exists when the slave starts
-      and contains values for the options. The following options are
+      and contains a value for the option. The following options are
       handled this way:
     </para>
 
@@ -2391,11 +2392,11 @@
     </itemizedlist>
 
     <para>
-      The <filename>master.info</filename> file format in
+      The <filename>master.info</filename> file format in MySQL
       &current-series; includes values corresponding to the SSL options.
       In addition, the file format includes as its first line the number
-      of lines in the file. If you upgrade an older server to a newer
-      version, the new server upgrades the
+      of lines in the file. If you upgrade an older server (before MySQL
+      4.1.1) to a newer version, the new server upgrades the
       <filename>master.info</filename> file to the new format
       automatically when it starts. However, if you downgrade a newer
       server to an older version, you should remove the first line
@@ -2413,13 +2414,10 @@
 
     <para>
       If the <filename>master.info</filename> file exists when the slave
-      server starts, the server ignores those options. Instead, it uses
-      the values found in the <filename>master.info</filename> file.
-    </para>
-
-    <para>
-      If you restart the slave server with different values of the
-      startup options that correspond to values in the
+      server starts, the server uses its contents and ignores any
+      options that correspond to the values listed in the file. Thus, if
+      you start the slave server with different values of the startup
+      options that correspond to values in the
       <filename>master.info</filename> file, the different values have
       no effect, because the server continues to use the
       <filename>master.info</filename> file. To use different values,
@@ -2436,7 +2434,7 @@
 
 <programlisting>
 [mysqld]
-master-host=some_host
+master-host=<replaceable>some_host</replaceable>
 </programlisting>
 
     <para>
@@ -2448,8 +2446,8 @@
       <filename>master.info</filename> file only and ignores the value
       in the option file. If you modify the <filename>my.cnf</filename>
       file to specify a different master host of
-      <literal>some_other_host</literal>, the change still has no
-      effect. You should use <literal>CHANGE MASTER TO</literal>
+      <replaceable>some_other_host</replaceable>, the change still has
+      no effect. You should use <literal>CHANGE MASTER TO</literal>
       instead.
     </para>
 
@@ -2478,15 +2476,24 @@
 report-host=db-slave.mycompany.com
 </programlisting>
 
+    <remark role="todo">
+      [pd] Is this a promise we should make?
+    </remark>
+
     <para>
       The following list describes startup options for controlling
-      replication: Many of these options can be reset while the server
+      replication. Many of these options can be reset while the server
       is running by using the <literal>CHANGE MASTER TO</literal>
       statement. Others, such as the <option>--replicate-*</option>
       options, can be set only when the slave server starts. We plan to
       fix this.
     </para>
 
+    <remark role="todo">
+      Add this: Replication-related system variables are discussed later
+      in this section.
+    </remark>
+
     <itemizedlist>
 
       <listitem>
@@ -2495,14 +2502,15 @@
         </para>
 
         <para>
-          Normally, updates received from a master server by a slave are
-          not logged to its binary log. This option tells the slave to
-          log the updates performed by its SQL thread to the slave's own
-          binary log. For this option to have any effect, the slave must
-          also be started with the <option>--log-bin</option> option to
-          enable binary logging. <option>--log-slave-updates</option> is
-          used when you want to chain replication servers. For example,
-          you might want a setup like this:
+          Normally, a slave does not log to its own binary log any
+          updates that are received from a master server. This option
+          tells the slave to log the updates performed by its SQL thread
+          to its own binary log. For this option to have any effect, the
+          slave must also be started with the <option>--log-bin</option>
+          option to enable binary logging.
+          <option>--log-slave-updates</option> is used when you want to
+          chain replication servers. For example, you might want to set
+          up replication servers using this arrangement:
         </para>
 
 <programlisting>
@@ -2510,12 +2518,13 @@
 </programlisting>
 
         <para>
-          That is, A serves as the master for the slave B, and B serves
-          as the master for the slave C. For this to work, B must be
-          both a master <emphasis>and</emphasis> a slave. You must start
-          both A and B with <option>--log-bin</option> to enable binary
+          Here, A serves as the master for the slave B, and B serves as
+          the master for the slave C. For this to work, B must be both a
+          master <emphasis>and</emphasis> a slave. You must start both A
+          and B with <option>--log-bin</option> to enable binary
           logging, and B with the <option>--log-slave-updates</option>
-          option.
+          option so that updates received from A are logged by B to its
+          binary log.
         </para>
       </listitem>
 
@@ -2525,21 +2534,16 @@
         </para>
 
         <para>
-          Make the slave print more messages to the error log about what
-          it is doing. For example, it warns you that it succeeded in
+          This option causes a server to print more messages to the
+          error log about what it is doing. With respect to replication,
+          the server generates warnings that it succeeded in
           reconnecting after a network/connection failure, and informs
           you as to how each slave thread started. This option is
           enabled by default; to disable it, use
           <option>--skip-log-warnings</option>. Aborted connections are
           not logged to the error log unless the value is greater than
-          <literal>1</literal>.
+          1.
         </para>
-
-        <para>
-          Note that the effects of this option are not limited to
-          replication. It produces warnings across a spectrum of server
-          activities.
-        </para>
       </listitem>
 
       <listitem>
@@ -2548,9 +2552,9 @@
         </para>
 
         <para>
-          The number of seconds the slave thread sleeps before retrying
-          to connect to the master in case the master goes down or the
-          connection is lost. The value in the
+          The number of seconds that the slave thread sleeps before
+          trying to reconnect to the master in case the master goes down
+          or the connection is lost. The value in the
           <filename>master.info</filename> file takes precedence if it
           can be read. If not set, the default is 60.
         </para>
@@ -2558,14 +2562,14 @@
 
       <listitem>
         <para>
-          <option>--master-host=<replaceable>host</replaceable></option>
+          <option>--master-host=<replaceable>host_name</replaceable></option>
         </para>
 
         <para>
-          The hostname or IP number of the master replication server. If
-          this option is not given, the slave thread does not start. The
-          value in <filename>master.info</filename> takes precedence if
-          it can be read.
+          The hostname or IP number of the master replication server.
+          The value in <filename>master.info</filename> takes precedence
+          if it can be read. If no master host is specified, the slave
+          thread does not start.
         </para>
       </listitem>
 
@@ -2588,9 +2592,9 @@
 
         <para>
           The password of the account that the slave thread uses for
-          authentication when connecting to the master. The value in the
-          <filename>master.info</filename> file takes precedence if it
-          can be read. If not set, an empty password is assumed.
+          authentication when it connects to the master. The value in
+          the <filename>master.info</filename> file takes precedence if
+          it can be read. If not set, an empty password is assumed.
         </para>
       </listitem>
 
@@ -2600,11 +2604,10 @@
         </para>
 
         <para>
-          The TCP/IP port the master is listening on. The value in the
-          <filename>master.info</filename> file takes precedence if it
-          can be read. If not set, the compiled-in setting is assumed.
-          If you have not tinkered with <command>configure</command>
-          options, this should be 3306.
+          The TCP/IP port number that the master is listening on. The
+          value in the <filename>master.info</filename> file takes
+          precedence if it can be read. If not set, the compiled-in
+          setting is assumed (normally 3306).
         </para>
       </listitem>
 
@@ -2614,8 +2617,8 @@
         </para>
 
         <para>
-          The number of times the slave tries to connect to the master
-          before giving up.
+          The number of times that the slave tries to connect to the
+          master before giving up.
         </para>
       </listitem>
 
@@ -2635,7 +2638,7 @@
           the same as the corresponding <option>--ssl</option>,
           <option>--ssl-ca</option>, <option>--ssl-capath</option>,
           <option>--ssl-cert</option>, <option>--ssl-cipher</option>,
-          <option>--ssl-key</option> options described in
+          <option>--ssl-key</option> options that are described in
           <xref linkend="ssl-options"/>. The values in the
           <filename>master.info</filename> file take precedence if they
           can be read.
@@ -2644,27 +2647,32 @@
 
       <listitem>
         <para>
-          <option>--master-user=<replaceable>username</replaceable></option>
+          <option>--master-user=<replaceable>user_name</replaceable></option>
         </para>
 
         <para>
           The username of the account that the slave thread uses for
-          authentication when connecting to the master. This account
+          authentication when it connects to the master. This account
           must have the <literal>REPLICATION SLAVE</literal> privilege.
           The value in the <filename>master.info</filename> file, if it
-          can be read, takes precedence. If the master user is not set,
-          user <literal>test</literal> is assumed.
+          can be read, takes precedence. If the master username is not
+          set, the name <literal>test</literal> is assumed.
         </para>
       </listitem>
 
       <listitem>
+        <remark role="todo">
+          [pd]This is really a system variable, not an option.
+        </remark>
+
         <para>
           <option>--max-relay-log-size=<replaceable>size</replaceable></option>
         </para>
 
         <para>
-          To rotate the relay log automatically. See
-          <xref linkend="server-system-variables"/>.
+          The size at which the server rotates relay log files
+          automatically. For more information, see
+          <xref linkend="slave-logs"/>.
         </para>
       </listitem>
 
@@ -2676,7 +2684,7 @@
         <para>
           Cause the slave to allow no updates except from slave threads
           or from users having the <literal>SUPER</literal> privilege.
-          This can be useful to ensure that a slave server accepts no
+          This enables you to ensure that a slave server accepts no
           updates from clients. This option does not apply to
           <literal>TEMPORARY</literal> tables.
         </para>
@@ -2708,11 +2716,12 @@
         </para>
 
         <para>
-          The location and name that should be used for the relay log
-          index file. The default name is
-          <literal><replaceable>host_name</replaceable>-relay-bin.index</literal>,
-          where <replaceable>host_name</replaceable> is the name of the
-          slave server.
+          The name to use for the relay log index file. The default name
+          is
+          <filename><replaceable>host_name</replaceable>-relay-bin.index</filename>
+          in the data directory, where
+          <replaceable>host_name</replaceable> is the name of the slave
+          server.
         </para>
       </listitem>
 
@@ -2729,6 +2738,10 @@
       </listitem>
 
       <listitem>
+        <remark role="todo">
+          [pd]This is really a system variable, not an option.
+        </remark>
+
         <para>
           <option>--relay-log-purge={0|1}</option>
         </para>
@@ -3189,6 +3202,11 @@
 
     </itemizedlist>
 
+    <remark role="todo">
+      Add here: Discuss replication-related system variables.
+      sync_binlog.
+    </remark>
+
   </section>
 
   <section id="replication-rules">

Thread
svn commit - mysqldoc@docsrva: r1114 - in trunk: . refman-4.1 refman-5.0 refman-5.1paul30 Jan