svn commit - mysqldoc@docsrva: r5289 - in trunk: . refman-4.1 refman-5.0 refman-5.1

[paul]

Author: paul
Date: 2007-03-09 19:00:16 +0100 (Fri, 09 Mar 2007)
New Revision: 5289

Log:
 r17472@frost:  paul | 2007-03-09 11:59:20 -0600
 Correct the descriptions for the !include/!includedir option file directives.
 Their semantics was described incorrectly. (Bug#26775)


Modified:
   trunk/refman-4.1/using-mysql-programs.xml
   trunk/refman-5.0/using-mysql-programs.xml
   trunk/refman-5.1/using-mysql-programs.xml

Property changes on: trunk
___________________________________________________________________
Name: svk:merge
   - 4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/mysqldoc/trunk:21154
7d8d2c4e-af1d-0410-ab9f-b038ce55645b:/mysqldoc-local/mysqldoc:17454
b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:14218
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:14593
   + 4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/mysqldoc/trunk:21154
7d8d2c4e-af1d-0410-ab9f-b038ce55645b:/mysqldoc-local/mysqldoc:17472
b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:14218
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:14593


Modified: trunk/refman-4.1/using-mysql-programs.xml
===================================================================
--- trunk/refman-4.1/using-mysql-programs.xml	2007-03-09 17:55:10 UTC (rev 5288)
+++ trunk/refman-4.1/using-mysql-programs.xml	2007-03-09 18:00:16 UTC (rev 5289)
Changed blocks: 5, Lines Added: 45, Lines Deleted: 19; 4515 bytes

@@ -1173,13 +1173,12 @@
 </programlisting>
 
       <para>
-        Beginning with MySQL 4.1.11 in the 4.1 series and MySQL 5.0.4 in
-        the 5.0 series, it is possible to use
+        Beginning with MySQL 4.1.11, it is possible to use
         <literal>!include</literal> directives in option files to
         include other option files and <literal>!includedir</literal> to
         search specific directories for option files. For example, to
-        include the <filename>/home/mydir/myopt.cnf</filename> file, you
-        can use the following directive:
+        include the <filename>/home/mydir/myopt.cnf</filename> file, use
+        the following directive:
       </para>
 
 <programlisting>

@@ -1188,7 +1187,7 @@
 
       <para>
         To search the <filename>/home/mydir</filename> directory and
-        read option files found there, you would use this directive:
+        read option files found there, use this directive:
       </para>
 
 <programlisting>

@@ -1196,6 +1195,11 @@
 </programlisting>
 
       <para>
+        There is no guarantee about the order in which the option files
+        in the directory will be read.
+      </para>
+
+      <para>
         <emphasis role="bold">Note</emphasis>: Currently, any files to
         be found and included using the <literal>!includedir</literal>
         directive on Unix operating systems <emphasis>must</emphasis>

@@ -1206,32 +1210,54 @@
       </para>
 
       <para>
-        Note that options read from included files are applied in the
-        context of the current option group. Suppose that you were to
-        write the following lines in <filename>my.cnf</filename>:
+        Write the contents of an included option file like any other
+        option file. That is, it should contain groups of options, each
+        preceded by a
+        <literal>[<replaceable>group</replaceable>]</literal>
line that
+        indicates the program to which the options apply.
       </para>
 
+      <para>
+        While an included file is being processed, only those options in
+        groups that the current program is looking for are used. Other
+        groups are ignored. Suppose that a <filename>my.cnf</filename>
+        file contains this line:
+      </para>
+
 <programlisting>
-[mysqld]
 !include /home/mydir/myopt.cnf
 </programlisting>
 
       <para>
-        In this case, the <filename>myopt.cnf</filename> file is
-        processed only for the server, and the
-        <literal>!include</literal> directive is ignored by any client
-        applications. However, if you were to use the following lines,
-        the directory <filename>/home/mydir/my-dump-options</filename>
-        is checked for option files by <command>mysqldump</command>
-        only, and not by the server or by any other client applications:
+        And suppose that <filename>/home/mydir/myopt.cnf</filename>
+        looks like this:
       </para>
 
 <programlisting>
-[mysqldump]
-!includedir /home/mydir/my-dump-options
+[mysqladmin]
+force
+
+[mysqld]
+key_buffer_size=16M
 </programlisting>
 
       <para>
+        If <filename>my.cnf</filename> is processed by
+        <command>mysqld</command>, only the
<literal>[mysqld]</literal>
+        group in <filename>/home/mydir/myopt.cnf</filename> is used. If
+        the file is processed by <command>mysqladmin</command>, only the
+        <literal>[mysqldamin]</literal> group is used. If the file is
+        processed by any other program, no options in
+        <filename>/home/mydir/myopt.cnf</filename> are used.
+      </para>
+
+      <para>
+        The <literal>!includedir</literal> directive is processed
+        similarly except that all option files in the named directory
+        are read.
+      </para>
+
+      <para>
         If you have a source distribution, you can find sample option
         files named
        
<filename>my-<replaceable>xxxx</replaceable>.cnf</filename> in

@@ -1255,7 +1281,7 @@
       </para>
 
       <para>
-        All MySQL programs that support option files handle the
+        Most MySQL programs that support option files handle the
         following options. They affect option-file handling, so they
         must be given on the command line and not in an option file. To
         work properly, each of these options must immediately follow the


Modified: trunk/refman-5.0/using-mysql-programs.xml
===================================================================
--- trunk/refman-5.0/using-mysql-programs.xml	2007-03-09 17:55:10 UTC (rev 5288)
+++ trunk/refman-5.0/using-mysql-programs.xml	2007-03-09 18:00:16 UTC (rev 5289)
Changed blocks: 5, Lines Added: 44, Lines Deleted: 17; 4303 bytes

@@ -1171,8 +1171,8 @@
         <literal>!include</literal> directives in option files to
         include other option files and <literal>!includedir</literal> to
         search specific directories for option files. For example, to
-        include the <filename>/home/mydir/myopt.cnf</filename> file, you
-        can use the following directive:
+        include the <filename>/home/mydir/myopt.cnf</filename> file, use
+        the following directive:
       </para>
 
 <programlisting>

@@ -1181,7 +1181,7 @@
 
       <para>
         To search the <filename>/home/mydir</filename> directory and
-        read option files found there, you would use this directive:
+        read option files found there, use this directive:
       </para>
 
 <programlisting>

@@ -1189,6 +1189,11 @@
 </programlisting>
 
       <para>
+        There is no guarantee about the order in which the option files
+        in the directory will be read.
+      </para>
+
+      <para>
         <emphasis role="bold">Note</emphasis>: Currently, any files to
         be found and included using the <literal>!includedir</literal>
         directive on Unix operating systems <emphasis>must</emphasis>

@@ -1199,32 +1204,54 @@
       </para>
 
       <para>
-        Note that options read from included files are applied in the
-        context of the current option group. Suppose that you were to
-        write the following lines in <filename>my.cnf</filename>:
+        Write the contents of an included option file like any other
+        option file. That is, it should contain groups of options, each
+        preceded by a
+        <literal>[<replaceable>group</replaceable>]</literal>
line that
+        indicates the program to which the options apply.
       </para>
 
+      <para>
+        While an included file is being processed, only those options in
+        groups that the current program is looking for are used. Other
+        groups are ignored. Suppose that a <filename>my.cnf</filename>
+        file contains this line:
+      </para>
+
 <programlisting>
-[mysqld]
 !include /home/mydir/myopt.cnf
 </programlisting>
 
       <para>
-        In this case, the <filename>myopt.cnf</filename> file is
-        processed only for the server, and the
-        <literal>!include</literal> directive is ignored by any client
-        applications. However, if you were to use the following lines,
-        the directory <filename>/home/mydir/my-dump-options</filename>
-        is checked for option files by <command>mysqldump</command>
-        only, and not by the server or by any other client applications:
+        And suppose that <filename>/home/mydir/myopt.cnf</filename>
+        looks like this:
       </para>
 
 <programlisting>
-[mysqldump]
-!includedir /home/mydir/my-dump-options
+[mysqladmin]
+force
+
+[mysqld]
+key_buffer_size=16M
 </programlisting>
 
       <para>
+        If <filename>my.cnf</filename> is processed by
+        <command>mysqld</command>, only the
<literal>[mysqld]</literal>
+        group in <filename>/home/mydir/myopt.cnf</filename> is used. If
+        the file is processed by <command>mysqladmin</command>, only the
+        <literal>[mysqldamin]</literal> group is used. If the file is
+        processed by any other program, no options in
+        <filename>/home/mydir/myopt.cnf</filename> are used.
+      </para>
+
+      <para>
+        The <literal>!includedir</literal> directive is processed
+        similarly except that all option files in the named directory
+        are read.
+      </para>
+
+      <para>
         If you have a source distribution, you can find sample option
         files named
        
<filename>my-<replaceable>xxxx</replaceable>.cnf</filename> in

@@ -1248,7 +1275,7 @@
       </para>
 
       <para>
-        All MySQL programs that support option files handle the
+        Most MySQL programs that support option files handle the
         following options. They affect option-file handling, so they
         must be given on the command line and not in an option file. To
         work properly, each of these options must immediately follow the


Modified: trunk/refman-5.1/using-mysql-programs.xml
===================================================================
--- trunk/refman-5.1/using-mysql-programs.xml	2007-03-09 17:55:10 UTC (rev 5288)
+++ trunk/refman-5.1/using-mysql-programs.xml	2007-03-09 18:00:16 UTC (rev 5289)
Changed blocks: 5, Lines Added: 48, Lines Deleted: 21; 4634 bytes

@@ -1169,12 +1169,12 @@
 </programlisting>
 
       <para>
-        Beginning with MySQL 5.0.4, it is possible to use
-        <literal>!include</literal> directives in option files to
-        include other option files and <literal>!includedir</literal> to
-        search specific directories for option files. For example, to
-        include the <filename>/home/mydir/myopt.cnf</filename> file, you
-        can use the following directive:
+        It is possible to use <literal>!include</literal> directives in
+        option files to include other option files and
+        <literal>!includedir</literal> to search specific directories
+        for option files. For example, to include the
+        <filename>/home/mydir/myopt.cnf</filename> file, use the
+        following directive:
       </para>
 
 <programlisting>

@@ -1183,7 +1183,7 @@
 
       <para>
         To search the <filename>/home/mydir</filename> directory and
-        read option files found there, you would use this directive:
+        read option files found there, use this directive:
       </para>
 
 <programlisting>

@@ -1191,6 +1191,11 @@
 </programlisting>
 
       <para>
+        There is no guarantee about the order in which the option files
+        in the directory will be read.
+      </para>
+
+      <para>
         <emphasis role="bold">Note</emphasis>: Currently, any files to
         be found and included using the <literal>!includedir</literal>
         directive on Unix operating systems <emphasis>must</emphasis>

@@ -1201,32 +1206,54 @@
       </para>
 
       <para>
-        Note that options read from included files are applied in the
-        context of the current option group. Suppose that you were to
-        write the following lines in <filename>my.cnf</filename>:
+        Write the contents of an included option file like any other
+        option file. That is, it should contain groups of options, each
+        preceded by a
+        <literal>[<replaceable>group</replaceable>]</literal>
line that
+        indicates the program to which the options apply.
       </para>
 
+      <para>
+        While an included file is being processed, only those options in
+        groups that the current program is looking for are used. Other
+        groups are ignored. Suppose that a <filename>my.cnf</filename>
+        file contains this line:
+      </para>
+
 <programlisting>
-[mysqld]
 !include /home/mydir/myopt.cnf
 </programlisting>
 
       <para>
-        In this case, the <filename>myopt.cnf</filename> file is
-        processed only for the server, and the
-        <literal>!include</literal> directive is ignored by any client
-        applications. However, if you were to use the following lines,
-        the directory <filename>/home/mydir/my-dump-options</filename>
-        is checked for option files by <command>mysqldump</command>
-        only, and not by the server or by any other client applications:
+        And suppose that <filename>/home/mydir/myopt.cnf</filename>
+        looks like this:
       </para>
 
 <programlisting>
-[mysqldump]
-!includedir /home/mydir/my-dump-options
+[mysqladmin]
+force
+
+[mysqld]
+key_buffer_size=16M
 </programlisting>
 
       <para>
+        If <filename>my.cnf</filename> is processed by
+        <command>mysqld</command>, only the
<literal>[mysqld]</literal>
+        group in <filename>/home/mydir/myopt.cnf</filename> is used. If
+        the file is processed by <command>mysqladmin</command>, only the
+        <literal>[mysqldamin]</literal> group is used. If the file is
+        processed by any other program, no options in
+        <filename>/home/mydir/myopt.cnf</filename> are used.
+      </para>
+
+      <para>
+        The <literal>!includedir</literal> directive is processed
+        similarly except that all option files in the named directory
+        are read.
+      </para>
+
+      <para>
         If you have a source distribution, you can find sample option
         files named
        
<filename>my-<replaceable>xxxx</replaceable>.cnf</filename> in

@@ -1250,7 +1277,7 @@
       </para>
 
       <para>
-        All MySQL programs that support option files handle the
+        Most MySQL programs that support option files handle the
         following options. They affect option-file handling, so they
         must be given on the command line and not in an option file. To
         work properly, each of these options must immediately follow the