List:Commits« Previous MessageNext Message »
From:paul Date:January 28 2006 8:19pm
Subject:svn commit - mysqldoc@docsrva: r1083 - in trunk: . refman-4.1 refman-5.0 refman-5.1
View as plain text  
Author: paul
Date: 2006-01-28 21:19:38 +0100 (Sat, 28 Jan 2006)
New Revision: 1083

Log:
 r6816@frost:  paul | 2006-01-28 14:14:05 -0600
 General revisions.


Modified:
   trunk/
   trunk/refman-4.1/introduction.xml
   trunk/refman-4.1/sql-syntax.xml
   trunk/refman-5.0/introduction.xml
   trunk/refman-5.0/sql-syntax.xml
   trunk/refman-5.1/introduction.xml
   trunk/refman-5.1/sql-syntax.xml


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

Modified: trunk/refman-4.1/introduction.xml
===================================================================
--- trunk/refman-4.1/introduction.xml	2006-01-28 19:13:56 UTC (rev 1082)
+++ trunk/refman-4.1/introduction.xml	2006-01-28 20:19:38 UTC (rev 1083)
@@ -1940,10 +1940,12 @@
 
         <listitem>
           <para>
-            Privileges for a table are not automatically revoked when
-            you delete a table. You must explicitly issue a
-            <literal>REVOKE</literal> statement to revoke privileges for
-            a table. See <xref linkend="grant"/>.
+            There are several differences between the MySQL and standard
+            SQL privilege systems. For example, in MySQL, privileges for
+            a table are not automatically revoked when you delete a
+            table. You must explicitly issue a <literal>REVOKE</literal>
+            statement to revoke privileges for a table. For more
+            information, see <xref linkend="grant"/>.
           </para>
         </listitem>
 

Modified: trunk/refman-4.1/sql-syntax.xml
===================================================================
--- trunk/refman-4.1/sql-syntax.xml	2006-01-28 19:13:56 UTC (rev 1082)
+++ trunk/refman-4.1/sql-syntax.xml	2006-01-28 20:19:38 UTC (rev 1083)
@@ -10177,6 +10177,24 @@
 
       <title>&title-account-management-sql;</title>
 
+      <para>
+        MySQL account information is stored in the tables of the
+        <literal>mysql</literal> database. This database and the access
+        control system are discussed extensively in
+        <xref linkend="database-administration"/>, which you should
+        consult for additional details.
+      </para>
+
+      <para>
+        <emphasis role="bold">Important</emphasis>: Some releases of
+        MySQL introduce changes to the structure of the grant tables to
+        add new privileges or features. Whenever you update to a new
+        version of MySQL, you should update your grant tables to make
+        sure that they have the current structure so that you can take
+        advantage of any new capabilities. See
+        <xref linkend="mysql-fix-privilege-tables"/>.
+      </para>
+
       <section id="drop-user">
 
         <title>&title-drop-user;</title>
@@ -10236,7 +10254,7 @@
         <remark role="help-description-begin"/>
 
         <para>
-          The <literal>DROP USER</literal> statement deletes one or more
+          The <literal>DROP USER</literal> statement removes one or more
           MySQL accounts. To use it, you must have the global
           <literal>CREATE USER</literal> privilege or the
           <literal>DELETE</literal> privilege for the
@@ -10426,15 +10444,25 @@
         </para>
 
         <para>
+          <emphasis role="bold">Important</emphasis>: Some releases of
+          MySQL introduce changes to the structure of the grant tables
+          to add new privileges or features. Whenever you update to a
+          new version of MySQL, you should update your grant tables to
+          make sure that they have the current structure so that you can
+          take advantage of any new capabilities. See
+          <xref linkend="mysql-fix-privilege-tables"/>.
+        </para>
+
+        <para>
           If the grant tables hold privilege rows that contain
           mixed-case database or table names and the
           <literal>lower_case_table_names</literal> system variable is
-          set, <literal>REVOKE</literal> cannot be used to revoke the
-          privileges. It will be necessary to manipulate the grant
-          tables directly. (<literal>GRANT</literal> will not create
-          such rows when <literal>lower_case_table_names</literal> is
-          set, but such rows might have been created prior to setting
-          the variable.)
+          set to a non-zero value, <literal>REVOKE</literal> cannot be
+          used to revoke these privileges. It will be necessary to
+          manipulate the grant tables directly.
+          (<literal>GRANT</literal> will not create such rows when
+          <literal>lower_case_table_names</literal> is set, but such
+          rows might have been created prior to setting the variable.)
         </para>
 
         <para>
@@ -10545,8 +10573,8 @@
 
         <para>
           For the <literal>GRANT</literal> and <literal>REVOKE</literal>
-          statements, <literal>priv_type</literal> can be specified as
-          any of the following:
+          statements, <replaceable>priv_type</replaceable> can be
+          specified as any of the following:
         </para>
 
         <remark>
@@ -10698,7 +10726,7 @@
 
         <para>
           Use <literal>SHOW GRANTS</literal> to determine what
-          privileges the account has. See <xref linkend="show-grants"/>.
+          privileges an account has. See <xref linkend="show-grants"/>.
         </para>
 
         <para>
@@ -10729,8 +10757,8 @@
         </para>
 
         <para>
-          The only <literal>priv_type</literal> values you can specify
-          for a table are <literal>SELECT</literal>,
+          The <replaceable>priv_type</replaceable> values that you can
+          specify for a table are <literal>SELECT</literal>,
           <literal>INSERT</literal>, <literal>UPDATE</literal>,
           <literal>DELETE</literal>, <literal>CREATE</literal>,
           <literal>DROP</literal>, <literal>GRANT OPTION</literal>,
@@ -10738,23 +10766,14 @@
         </para>
 
         <para>
-          The only <literal>priv_type</literal> values you can specify
-          for a column (that is, when you use a
-          <literal>column_list</literal> clause) are
+          The <replaceable>priv_type</replaceable> values that you can
+          specify for a column (that is, when you use a
+          <replaceable>column_list</replaceable> clause) are
           <literal>SELECT</literal>, <literal>INSERT</literal>, and
           <literal>UPDATE</literal>.
         </para>
 
         <para>
-          The only <literal>priv_type</literal> values you can specify
-          at the routine level are <literal>ALTER ROUTINE</literal>,
-          <literal>EXECUTE</literal>, and <literal>GRANT
-          OPTION</literal>. <literal>CREATE ROUTINE</literal> is not a
-          routine-level privilege because you must have this privilege
-          to create a routine in the first place.
-        </para>
-
-        <para>
           For the global, database, and table levels, <literal>GRANT
           ALL</literal> assigns only the privileges that exist at the
           level you are granting. For example, if you use <literal>GRANT
@@ -10763,6 +10782,10 @@
           privileges such as <literal>FILE</literal> are granted.
         </para>
 
+        <remark role="todo">
+          [pd] Isn't next para false at the table and column levels?
+        </remark>
+
         <para>
           MySQL allows you to grant privileges even on databases and
           tables that do not exist. In such cases, the privileges to be
@@ -10838,7 +10861,7 @@
         </para>
 
 <programlisting>
-mysql&gt; <userinput>GRANT ALL ON test.* TO ''@'localhost' ...</userinput>
+GRANT ALL ON test.* TO ''@'localhost' ...
 </programlisting>
 
         <para>
@@ -10858,7 +10881,8 @@
           <literal>localhost</literal> in the
           <literal>mysql.user</literal> table (created during MySQL
           installation) is used when named users try to log in to the
-          MySQL server from the local machine.
+          MySQL server from the local machine. For details, see
+          <xref linkend="connection-access"/>.
         </para>
 
         <para>
@@ -10867,7 +10891,7 @@
         </para>
 
 <programlisting>
-mysql&gt; <userinput>SELECT Host, User FROM mysql.user WHERE User='';</userinput>
+SELECT Host, User FROM mysql.user WHERE User='';
 </programlisting>
 
         <para>
@@ -10876,8 +10900,8 @@
         </para>
 
 <programlisting>
-mysql&gt; <userinput>DELETE FROM mysql.user WHERE Host='localhost' AND User='';</userinput>
-mysql&gt; <userinput>FLUSH PRIVILEGES;</userinput>
+DELETE FROM mysql.user WHERE Host='localhost' AND User='';
+FLUSH PRIVILEGES;
 </programlisting>
 
         <para>
@@ -10890,15 +10914,14 @@
           results in unpredictable behavior which may even make it
           impossible for users to log in to the MySQL server</emphasis>.
           You should never attempt to alter the grant tables in any way
-          except by means of the
-          <literal>mysql_fix_privilege_tables</literal> script as
-          supplied by MySQL AB for use in upgrading the MySQL server.
+          except by means of the procedure prescribed by MySQL AB that
+          is described in <xref linkend="mysql-fix-privilege-tables"/>.
         </para>
 
         <para>
           The privileges for a table or column are formed additively as
           the logical <literal>OR</literal> of the privileges at each of
-          the four privilege levels. For example, if the
+          the privilege levels. For example, if the
           <literal>mysql.user</literal> table specifies that a user has
           a global <literal>SELECT</literal> privilege, the privilege
           cannot be denied by an entry at the database, table, or column
@@ -10934,6 +10957,17 @@
           USER</literal> or <literal>DELETE</literal>.
         </para>
 
+        <para>
+          <emphasis role="bold">Warning</emphasis>: If you create a new
+          user but do not specify an <literal>IDENTIFIED BY</literal>
+          clause, the user has no password. This is very insecure. As of
+          MySQL 5.0.2, you can enable the
+          <literal>NO_AUTO_CREATE_USER</literal> SQL mode to keep
+          <literal>GRANT</literal> from creating a new user if it would
+          otherwise do so, unless <literal>IDENTIFIED BY</literal> is
+          given to provide the new user a non-empty password.
+        </para>
+
         <indexterm>
           <primary>passwords</primary>
           <secondary>setting</secondary>
@@ -11000,12 +11034,6 @@
         </para>
 
         <para>
-          If a user has no privileges for a table, the table name is not
-          displayed when the user requests a list of tables (for
-          example, with a <literal>SHOW TABLES</literal> statement).
-        </para>
-
-        <para>
           The <literal>SHOW DATABASES</literal> privilege enables the
           account to see database names by issuing the <literal>SHOW
           DATABASE</literal> statement. Accounts that do not have this
@@ -11016,6 +11044,12 @@
         </para>
 
         <para>
+          If a user has no privileges for a table, the table name is not
+          displayed when the user requests a list of tables (for
+          example, with a <literal>SHOW TABLES</literal> statement).
+        </para>
+
+        <para>
           The <literal>WITH GRANT OPTION</literal> clause gives the user
           the ability to give to other users any privileges the user has
           at the specified privilege level. You should be careful to
@@ -11035,12 +11069,12 @@
           Be aware that when you grant a user the <literal>GRANT
           OPTION</literal> privilege at a particular privilege level,
           any privileges the user possesses (or may be given in the
-          future) at that level can also be granted by that user.
-          Suppose that you grant a user the <literal>INSERT</literal>
-          privilege on a database. If you then grant the
-          <literal>SELECT</literal> privilege on the database and
-          specify <literal>WITH GRANT OPTION</literal>, that user can
-          give to other users not only the <literal>SELECT</literal>
+          future) at that level can also be granted by that user to
+          other users. Suppose that you grant a user the
+          <literal>INSERT</literal> privilege on a database. If you then
+          grant the <literal>SELECT</literal> privilege on the database
+          and specify <literal>WITH GRANT OPTION</literal>, that user
+          can give to other users not only the <literal>SELECT</literal>
           privilege, but also <literal>INSERT</literal>. If you then
           grant the <literal>UPDATE</literal> privilege to the user on
           the database, the user can grant <literal>INSERT</literal>,
@@ -11048,9 +11082,10 @@
         </para>
 
         <para>
-          You should not grant <literal>ALTER</literal> privileges to a
-          normal user. If you do that, the user can try to subvert the
-          privilege system by renaming tables!
+          For a non-administrative user, you should not grant the
+          <literal>ALTER</literal> privilege globally or for the
+          <literal>mysql</literal> database. If you do that, the user
+          can try to subvert the privilege system by renaming tables!
         </para>
 
         <para>
@@ -11121,8 +11156,8 @@
             </para>
 
 <programlisting>
-mysql&gt; <userinput>GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost'</userinput>
-    -&gt; <userinput>IDENTIFIED BY 'goodsecret' REQUIRE SSL;</userinput>
+GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost'
+  IDENTIFIED BY 'goodsecret' REQUIRE SSL;
 </programlisting>
           </listitem>
 
@@ -11136,8 +11171,8 @@
             </para>
 
 <programlisting>
-mysql&gt; <userinput>GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost'</userinput>
-    -&gt; <userinput>IDENTIFIED BY 'goodsecret' REQUIRE X509;</userinput>
+GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost'
+  IDENTIFIED BY 'goodsecret' REQUIRE X509;
 </programlisting>
           </listitem>
 
@@ -11160,15 +11195,16 @@
             </remark>
 
 <programlisting>
-mysql&gt; <userinput>GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost'</userinput>
-    -&gt; <userinput>IDENTIFIED BY 'goodsecret'</userinput>
-    -&gt; <userinput>REQUIRE ISSUER '/C=FI/ST=Some-State/L=Helsinki/</userinput>
-       O=MySQL Finland AB/CN=Tonu Samuel/Email=tonu@stripped';
+GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost'
+  IDENTIFIED BY 'goodsecret'
+  REQUIRE ISSUER '/C=FI/ST=Some-State/L=Helsinki/
+    O=MySQL Finland AB/CN=Tonu Samuel/Email=tonu@stripped';
 </programlisting>
 
             <para>
-              Note that the <literal>ISSUER</literal> value should be
-              entered as a single string.
+              Note that the
+              <literal>'<replaceable>issuer</replaceable>'</literal>
+              value should be entered as a single string.
             </para>
           </listitem>
 
@@ -11184,16 +11220,17 @@
             </para>
 
 <programlisting>
-mysql&gt; <userinput>GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost'</userinput>
-    -&gt; <userinput>IDENTIFIED BY 'goodsecret'</userinput>
-    -&gt; <userinput>REQUIRE SUBJECT '/C=EE/ST=Some-State/L=Tallinn/</userinput>
-       O=MySQL demo client certificate/
-       CN=Tonu Samuel/Email=tonu@stripped';
+GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost'
+  IDENTIFIED BY 'goodsecret'
+  REQUIRE SUBJECT '/C=EE/ST=Some-State/L=Tallinn/
+    O=MySQL demo client certificate/
+    CN=Tonu Samuel/Email=tonu@stripped';
 </programlisting>
 
             <para>
-              Note that the <literal>SUBJECT</literal> value should be
-              entered as a single string.
+              Note that the
+              <literal>'<replaceable>subject</replaceable>'</literal>
+              value should be entered as a single string.
             </para>
           </listitem>
 
@@ -11209,9 +11246,9 @@
             </para>
 
 <programlisting>
-mysql&gt; <userinput>GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost'</userinput>
-    -&gt; <userinput>IDENTIFIED BY 'goodsecret'</userinput>
-    -&gt; <userinput>REQUIRE CIPHER 'EDH-RSA-DES-CBC3-SHA';</userinput>
+GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost'
+  IDENTIFIED BY 'goodsecret'
+  REQUIRE CIPHER 'EDH-RSA-DES-CBC3-SHA';
 </programlisting>
           </listitem>
 
@@ -11224,23 +11261,17 @@
         </para>
 
 <programlisting>
-mysql&gt; <userinput>GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost'</userinput>
-    -&gt; <userinput>IDENTIFIED BY 'goodsecret'</userinput>
-    -&gt; <userinput>REQUIRE SUBJECT '/C=EE/ST=Some-State/L=Tallinn/</userinput>
-       O=MySQL demo client certificate/
-       CN=Tonu Samuel/Email=tonu@stripped'
-    -&gt; <userinput>AND ISSUER '/C=FI/ST=Some-State/L=Helsinki/</userinput>
-       O=MySQL Finland AB/CN=Tonu Samuel/Email=tonu@stripped'
-    -&gt; <userinput>AND CIPHER 'EDH-RSA-DES-CBC3-SHA';</userinput>
+GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost'
+  IDENTIFIED BY 'goodsecret'
+  REQUIRE SUBJECT '/C=EE/ST=Some-State/L=Tallinn/
+    O=MySQL demo client certificate/
+    CN=Tonu Samuel/Email=tonu@stripped'
+  AND ISSUER '/C=FI/ST=Some-State/L=Helsinki/
+    O=MySQL Finland AB/CN=Tonu Samuel/Email=tonu@stripped'
+  AND CIPHER 'EDH-RSA-DES-CBC3-SHA';
 </programlisting>
 
         <para>
-          Note that the <literal>SUBJECT</literal> and
-          <literal>ISSUER</literal> values each should be entered as a
-          single string.
-        </para>
-
-        <para>
           Starting from MySQL 4.0.4, the <literal>AND</literal> keyword
           is optional between <literal>REQUIRE</literal> options.
         </para>

Modified: trunk/refman-5.0/introduction.xml
===================================================================
--- trunk/refman-5.0/introduction.xml	2006-01-28 19:13:56 UTC (rev 1082)
+++ trunk/refman-5.0/introduction.xml	2006-01-28 20:19:38 UTC (rev 1083)
@@ -1549,10 +1549,12 @@
 
         <listitem>
           <para>
-            Privileges for a table are not automatically revoked when
-            you delete a table. You must explicitly issue a
-            <literal>REVOKE</literal> statement to revoke privileges for
-            a table. See <xref linkend="grant"/>.
+            There are several differences between the MySQL and standard
+            SQL privilege systems. For example, in MySQL, privileges for
+            a table are not automatically revoked when you delete a
+            table. You must explicitly issue a <literal>REVOKE</literal>
+            statement to revoke privileges for a table. For more
+            information, see <xref linkend="grant"/>.
           </para>
         </listitem>
 

Modified: trunk/refman-5.0/sql-syntax.xml
===================================================================
--- trunk/refman-5.0/sql-syntax.xml	2006-01-28 19:13:56 UTC (rev 1082)
+++ trunk/refman-5.0/sql-syntax.xml	2006-01-28 20:19:38 UTC (rev 1083)
@@ -11168,6 +11168,24 @@
 
       <title>&title-account-management-sql;</title>
 
+      <para>
+        MySQL account information is stored in the tables of the
+        <literal>mysql</literal> database. This database and the access
+        control system are discussed extensively in
+        <xref linkend="database-administration"/>, which you should
+        consult for additional details.
+      </para>
+
+      <para>
+        <emphasis role="bold">Important</emphasis>: Some releases of
+        MySQL introduce changes to the structure of the grant tables to
+        add new privileges or features. Whenever you update to a new
+        version of MySQL, you should update your grant tables to make
+        sure that they have the current structure so that you can take
+        advantage of any new capabilities. See
+        <xref linkend="mysql-fix-privilege-tables"/>.
+      </para>
+
       <section id="create-user">
 
         <title>&title-create-user;</title>
@@ -11222,8 +11240,9 @@
           statement. In particular, to specify the password in plain
           text, omit the <literal>PASSWORD</literal> keyword. To specify
           the password as the hashed value as returned by the
-          <literal>PASSWORD()</literal> function, include the keyword
-          <literal>PASSWORD</literal>. See <xref linkend="grant"/>.
+          <literal>PASSWORD()</literal> function, include the
+          <literal>PASSWORD</literal> keyword. See
+          <xref linkend="grant"/>.
         </para>
 
         <remark role="help-description-end"/>
@@ -11289,7 +11308,7 @@
         <remark role="help-description-begin"/>
 
         <para>
-          The <literal>DROP USER</literal> statement deletes one or more
+          The <literal>DROP USER</literal> statement removes one or more
           MySQL accounts. To use it, you must have the global
           <literal>CREATE USER</literal> privilege or the
           <literal>DELETE</literal> privilege for the
@@ -11486,15 +11505,25 @@
         </para>
 
         <para>
+          <emphasis role="bold">Important</emphasis>: Some releases of
+          MySQL introduce changes to the structure of the grant tables
+          to add new privileges or features. Whenever you update to a
+          new version of MySQL, you should update your grant tables to
+          make sure that they have the current structure so that you can
+          take advantage of any new capabilities. See
+          <xref linkend="mysql-fix-privilege-tables"/>.
+        </para>
+
+        <para>
           If the grant tables hold privilege rows that contain
           mixed-case database or table names and the
           <literal>lower_case_table_names</literal> system variable is
-          set, <literal>REVOKE</literal> cannot be used to revoke the
-          privileges. It will be necessary to manipulate the grant
-          tables directly. (<literal>GRANT</literal> will not create
-          such rows when <literal>lower_case_table_names</literal> is
-          set, but such rows might have been created prior to setting
-          the variable.)
+          set to a non-zero value, <literal>REVOKE</literal> cannot be
+          used to revoke these privileges. It will be necessary to
+          manipulate the grant tables directly.
+          (<literal>GRANT</literal> will not create such rows when
+          <literal>lower_case_table_names</literal> is set, but such
+          rows might have been created prior to setting the variable.)
         </para>
 
         <para>
@@ -11574,11 +11603,12 @@
               The <literal>CREATE ROUTINE</literal>, <literal>ALTER
               ROUTINE</literal>, <literal>EXECUTE</literal>, and
               <literal>GRANT</literal> privileges apply to stored
-              routines. They can be granted at the global and database
-              levels. Also, except for <literal>CREATE
-              ROUTINE</literal>, these privileges can be granted at the
-              routine level for individual routines and are stored in
-              the <literal>mysql.procs_priv</literal> table.
+              routines (functions and procedures). They can be granted
+              at the global and database levels. Also, except for
+              <literal>CREATE ROUTINE</literal>, these privileges can be
+              granted at the routine level for individual routines and
+              are stored in the <literal>mysql.procs_priv</literal>
+              table.
             </para>
           </listitem>
 
@@ -11589,10 +11619,7 @@
           MySQL 5.0.6. It should be specified as
           <literal>TABLE</literal>, <literal>FUNCTION</literal>, or
           <literal>PROCEDURE</literal> when the following object is a
-          table, a stored function, or a stored procedure. To use this
-          clause when upgrading from a version of MySQL older than
-          5.0.6, you must upgrade your grant tables. See
-          <xref linkend="mysql-fix-privilege-tables"/>.
+          table, a stored function, or a stored procedure.
         </para>
 
         <remark role="help-description-end"/>
@@ -11623,8 +11650,8 @@
 
         <para>
           For the <literal>GRANT</literal> and <literal>REVOKE</literal>
-          statements, <literal>priv_type</literal> can be specified as
-          any of the following:
+          statements, <replaceable>priv_type</replaceable> can be
+          specified as any of the following:
         </para>
 
         <informaltable>
@@ -11646,7 +11673,7 @@
               </row>
               <row>
                 <entry><literal>ALTER ROUTINE</literal></entry>
-                <entry>Alter or drop stored routines</entry>
+                <entry>Enables stored routines to be altered or dropped</entry>
               </row>
               <row>
                 <entry><literal>CREATE</literal></entry>
@@ -11654,7 +11681,7 @@
               </row>
               <row>
                 <entry><literal>CREATE ROUTINE</literal></entry>
-                <entry>Create stored routines</entry>
+                <entry>Enables creation of stored routines</entry>
               </row>
               <row>
                 <entry><literal>CREATE TEMPORARY TABLES</literal></entry>
@@ -11769,10 +11796,7 @@
           <literal>SHOW VIEW</literal> were added in MySQL 5.0.1.
           <literal>CREATE USER</literal>, <literal>CREATE
           ROUTINE</literal>, and <literal>ALTER ROUTINE</literal> were
-          added in MySQL 5.0.3. To use these privileges when upgrading
-          from an earlier version of MySQL that does not have them, you
-          must first upgrade the grant tables, as described in
-          <xref linkend="mysql-fix-privilege-tables"/>.
+          added in MySQL 5.0.3.
         </para>
 
         <para>
@@ -11787,7 +11811,7 @@
 
         <para>
           Use <literal>SHOW GRANTS</literal> to determine what
-          privileges the account has. See <xref linkend="show-grants"/>.
+          privileges an account has. See <xref linkend="show-grants"/>.
         </para>
 
         <para>
@@ -11818,8 +11842,8 @@
         </para>
 
         <para>
-          The only <literal>priv_type</literal> values you can specify
-          for a table are <literal>SELECT</literal>,
+          The <replaceable>priv_type</replaceable> values that you can
+          specify for a table are <literal>SELECT</literal>,
           <literal>INSERT</literal>, <literal>UPDATE</literal>,
           <literal>DELETE</literal>, <literal>CREATE</literal>,
           <literal>DROP</literal>, <literal>GRANT OPTION</literal>,
@@ -11827,32 +11851,37 @@
         </para>
 
         <para>
-          The only <literal>priv_type</literal> values you can specify
-          for a column (that is, when you use a
-          <literal>column_list</literal> clause) are
+          The <replaceable>priv_type</replaceable> values that you can
+          specify for a column (that is, when you use a
+          <replaceable>column_list</replaceable> clause) are
           <literal>SELECT</literal>, <literal>INSERT</literal>, and
           <literal>UPDATE</literal>.
         </para>
 
         <para>
-          The only <literal>priv_type</literal> values you can specify
-          at the routine level are <literal>ALTER ROUTINE</literal>,
-          <literal>EXECUTE</literal>, and <literal>GRANT
-          OPTION</literal>. <literal>CREATE ROUTINE</literal> is not a
-          routine-level privilege because you must have this privilege
-          to create a routine in the first place.
+          The <replaceable>priv_type</replaceable> values that you can
+          specify at the routine level are <literal>ALTER
+          ROUTINE</literal>, <literal>EXECUTE</literal>, and
+          <literal>GRANT OPTION</literal>. <literal>CREATE
+          ROUTINE</literal> is not a routine-level privilege because you
+          must have this privilege to create a routine in the first
+          place.
         </para>
 
         <para>
           For the global, database, table, and routine levels,
           <literal>GRANT ALL</literal> assigns only the privileges that
-          exist at the level you are granting. For example, if you use
+          exist at the level you are granting. For example,
           <literal>GRANT ALL ON
-          <replaceable>db_name</replaceable>.*</literal>, that is a
-          database-level statement, so none of the global-only
-          privileges such as <literal>FILE</literal> are granted.
+          <replaceable>db_name</replaceable>.*</literal> is a
+          database-level statement, so it does not grant any global-only
+          privileges such as <literal>FILE</literal>.
         </para>
 
+        <remark role="todo">
+          [pd] Isn't next para false at the table and column levels?
+        </remark>
+
         <para>
           MySQL allows you to grant privileges even on database objects
           that do not exist. In such cases, the privileges to be granted
@@ -11930,7 +11959,7 @@
         </para>
 
 <programlisting>
-mysql&gt; <userinput>GRANT ALL ON test.* TO ''@'localhost' ...</userinput>
+GRANT ALL ON test.* TO ''@'localhost' ...
 </programlisting>
 
         <para>
@@ -11950,7 +11979,8 @@
           <literal>localhost</literal> in the
           <literal>mysql.user</literal> table (created during MySQL
           installation) is used when named users try to log in to the
-          MySQL server from the local machine.
+          MySQL server from the local machine. For details, see
+          <xref linkend="connection-access"/>.
         </para>
 
         <para>
@@ -11959,7 +11989,7 @@
         </para>
 
 <programlisting>
-mysql&gt; <userinput>SELECT Host, User FROM mysql.user WHERE User='';</userinput>
+SELECT Host, User FROM mysql.user WHERE User='';
 </programlisting>
 
         <para>
@@ -11968,8 +11998,8 @@
         </para>
 
 <programlisting>
-mysql&gt; <userinput>DELETE FROM mysql.user WHERE Host='localhost' AND User='';</userinput>
-mysql&gt; <userinput>FLUSH PRIVILEGES;</userinput>
+DELETE FROM mysql.user WHERE Host='localhost' AND User='';
+FLUSH PRIVILEGES;
 </programlisting>
 
         <para>
@@ -11982,15 +12012,15 @@
           attempting to do so results in unpredictable behavior which
           may even make it impossible for users to log in to the MySQL
           server</emphasis>. You should never attempt to alter the grant
-          tables in any way except by means of the
-          <literal>mysql_fix_privilege_tables</literal> script as
-          supplied by MySQL AB for use in upgrading the MySQL server.
+          tables in any way except by means of the procedure prescribed
+          by MySQL AB that is described in
+          <xref linkend="mysql-fix-privilege-tables"/>.
         </para>
 
         <para>
           The privileges for a table or column are formed additively as
           the logical <literal>OR</literal> of the privileges at each of
-          the four privilege levels. For example, if the
+          the privilege levels. For example, if the
           <literal>mysql.user</literal> table specifies that a user has
           a global <literal>SELECT</literal> privilege, the privilege
           cannot be denied by an entry at the database, table, or column
@@ -12026,6 +12056,17 @@
           USER</literal> or <literal>DELETE</literal>.
         </para>
 
+        <para>
+          <emphasis role="bold">Warning</emphasis>: If you create a new
+          user but do not specify an <literal>IDENTIFIED BY</literal>
+          clause, the user has no password. This is very insecure. As of
+          MySQL 5.0.2, you can enable the
+          <literal>NO_AUTO_CREATE_USER</literal> SQL mode to keep
+          <literal>GRANT</literal> from creating a new user if it would
+          otherwise do so, unless <literal>IDENTIFIED BY</literal> is
+          given to provide the new user a non-empty password.
+        </para>
+
         <indexterm>
           <primary>passwords</primary>
           <secondary>setting</secondary>
@@ -12040,17 +12081,6 @@
         </para>
 
         <para>
-          <emphasis role="bold">Warning</emphasis>: If you create a new
-          user but do not specify an <literal>IDENTIFIED BY</literal>
-          clause, the user has no password. This is very insecure. As of
-          MySQL 5.0.2, you can enable the
-          <literal>NO_AUTO_CREATE_USER</literal> SQL mode to keep
-          <literal>GRANT</literal> from creating a new user if it would
-          otherwise do so, unless <literal>IDENTIFIED BY</literal> is
-          given to provide the new user a non-empty password.
-        </para>
-
-        <para>
           Passwords can also be set with the <literal>SET
           PASSWORD</literal> statement. See
           <xref linkend="set-password"/>.
@@ -12097,12 +12127,6 @@
         </para>
 
         <para>
-          If a user has no privileges for a table, the table name is not
-          displayed when the user requests a list of tables (for
-          example, with a <literal>SHOW TABLES</literal> statement).
-        </para>
-
-        <para>
           The <literal>SHOW DATABASES</literal> privilege enables the
           account to see database names by issuing the <literal>SHOW
           DATABASE</literal> statement. Accounts that do not have this
@@ -12113,6 +12137,12 @@
         </para>
 
         <para>
+          If a user has no privileges for a table, the table name is not
+          displayed when the user requests a list of tables (for
+          example, with a <literal>SHOW TABLES</literal> statement).
+        </para>
+
+        <para>
           The <literal>WITH GRANT OPTION</literal> clause gives the user
           the ability to give to other users any privileges the user has
           at the specified privilege level. You should be careful to
@@ -12132,12 +12162,12 @@
           Be aware that when you grant a user the <literal>GRANT
           OPTION</literal> privilege at a particular privilege level,
           any privileges the user possesses (or may be given in the
-          future) at that level can also be granted by that user.
-          Suppose that you grant a user the <literal>INSERT</literal>
-          privilege on a database. If you then grant the
-          <literal>SELECT</literal> privilege on the database and
-          specify <literal>WITH GRANT OPTION</literal>, that user can
-          give to other users not only the <literal>SELECT</literal>
+          future) at that level can also be granted by that user to
+          other users. Suppose that you grant a user the
+          <literal>INSERT</literal> privilege on a database. If you then
+          grant the <literal>SELECT</literal> privilege on the database
+          and specify <literal>WITH GRANT OPTION</literal>, that user
+          can give to other users not only the <literal>SELECT</literal>
           privilege, but also <literal>INSERT</literal>. If you then
           grant the <literal>UPDATE</literal> privilege to the user on
           the database, the user can grant <literal>INSERT</literal>,
@@ -12145,9 +12175,10 @@
         </para>
 
         <para>
-          You should not grant <literal>ALTER</literal> privileges to a
-          normal user. If you do that, the user can try to subvert the
-          privilege system by renaming tables!
+          For a non-administrative user, you should not grant the
+          <literal>ALTER</literal> privilege globally or for the
+          <literal>mysql</literal> database. If you do that, the user
+          can try to subvert the privilege system by renaming tables!
         </para>
 
         <para>
@@ -12229,8 +12260,8 @@
             </para>
 
 <programlisting>
-mysql&gt; <userinput>GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost'</userinput>
-    -&gt; <userinput>IDENTIFIED BY 'goodsecret' REQUIRE SSL;</userinput>
+GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost'
+  IDENTIFIED BY 'goodsecret' REQUIRE SSL;
 </programlisting>
           </listitem>
 
@@ -12244,8 +12275,8 @@
             </para>
 
 <programlisting>
-mysql&gt; <userinput>GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost'</userinput>
-    -&gt; <userinput>IDENTIFIED BY 'goodsecret' REQUIRE X509;</userinput>
+GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost'
+  IDENTIFIED BY 'goodsecret' REQUIRE X509;
 </programlisting>
           </listitem>
 
@@ -12256,11 +12287,10 @@
               restriction on connection attempts that the client must
               present a valid X509 certificate issued by CA
               <literal>'<replaceable>issuer</replaceable>'</literal>. If
-              the client presents the client presents a certificate that
-              is valid but has a different issuer, the server rejects
-              the connection. Use of X509 certificates always implies
-              encryption, so the <literal>SSL</literal> option is
-              unnecessary in this case.
+              the client presents a certificate that is valid but has a
+              different issuer, the server rejects the connection. Use
+              of X509 certificates always implies encryption, so the
+              <literal>SSL</literal> option is unnecessary in this case.
             </para>
 
             <remark role="todo">
@@ -12269,15 +12299,16 @@
             </remark>
 
 <programlisting>
-mysql&gt; <userinput>GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost'</userinput>
-    -&gt; <userinput>IDENTIFIED BY 'goodsecret'</userinput>
-    -&gt; <userinput>REQUIRE ISSUER '/C=FI/ST=Some-State/L=Helsinki/</userinput>
-       O=MySQL Finland AB/CN=Tonu Samuel/Email=tonu@stripped';
+GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost'
+  IDENTIFIED BY 'goodsecret'
+  REQUIRE ISSUER '/C=FI/ST=Some-State/L=Helsinki/
+    O=MySQL Finland AB/CN=Tonu Samuel/Email=tonu@stripped';
 </programlisting>
 
             <para>
-              Note that the <literal>ISSUER</literal> value should be
-              entered as a single string.
+              Note that the
+              <literal>'<replaceable>issuer</replaceable>'</literal>
+              value should be entered as a single string.
             </para>
           </listitem>
 
@@ -12293,16 +12324,17 @@
             </para>
 
 <programlisting>
-mysql&gt; <userinput>GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost'</userinput>
-    -&gt; <userinput>IDENTIFIED BY 'goodsecret'</userinput>
-    -&gt; <userinput>REQUIRE SUBJECT '/C=EE/ST=Some-State/L=Tallinn/</userinput>
-       O=MySQL demo client certificate/
-       CN=Tonu Samuel/Email=tonu@stripped';
+GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost'
+  IDENTIFIED BY 'goodsecret'
+  REQUIRE SUBJECT '/C=EE/ST=Some-State/L=Tallinn/
+    O=MySQL demo client certificate/
+    CN=Tonu Samuel/Email=tonu@stripped';
 </programlisting>
 
             <para>
-              Note that the <literal>SUBJECT</literal> value should be
-              entered as a single string.
+              Note that the
+              <literal>'<replaceable>subject</replaceable>'</literal>
+              value should be entered as a single string.
             </para>
           </listitem>
 
@@ -12318,9 +12350,9 @@
             </para>
 
 <programlisting>
-mysql&gt; <userinput>GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost'</userinput>
-    -&gt; <userinput>IDENTIFIED BY 'goodsecret'</userinput>
-    -&gt; <userinput>REQUIRE CIPHER 'EDH-RSA-DES-CBC3-SHA';</userinput>
+GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost'
+  IDENTIFIED BY 'goodsecret'
+  REQUIRE CIPHER 'EDH-RSA-DES-CBC3-SHA';
 </programlisting>
           </listitem>
 
@@ -12333,23 +12365,17 @@
         </para>
 
 <programlisting>
-mysql&gt; <userinput>GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost'</userinput>
-    -&gt; <userinput>IDENTIFIED BY 'goodsecret'</userinput>
-    -&gt; <userinput>REQUIRE SUBJECT '/C=EE/ST=Some-State/L=Tallinn/</userinput>
-       O=MySQL demo client certificate/
-       CN=Tonu Samuel/Email=tonu@stripped'
-    -&gt; <userinput>AND ISSUER '/C=FI/ST=Some-State/L=Helsinki/</userinput>
-       O=MySQL Finland AB/CN=Tonu Samuel/Email=tonu@stripped'
-    -&gt; <userinput>AND CIPHER 'EDH-RSA-DES-CBC3-SHA';</userinput>
+GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost'
+  IDENTIFIED BY 'goodsecret'
+  REQUIRE SUBJECT '/C=EE/ST=Some-State/L=Tallinn/
+    O=MySQL demo client certificate/
+    CN=Tonu Samuel/Email=tonu@stripped'
+  AND ISSUER '/C=FI/ST=Some-State/L=Helsinki/
+    O=MySQL Finland AB/CN=Tonu Samuel/Email=tonu@stripped'
+  AND CIPHER 'EDH-RSA-DES-CBC3-SHA';
 </programlisting>
 
         <para>
-          Note that the <literal>SUBJECT</literal> and
-          <literal>ISSUER</literal> values each should be entered as a
-          single string.
-        </para>
-
-        <para>
           The <literal>AND</literal> keyword is optional between
           <literal>REQUIRE</literal> options.
         </para>

Modified: trunk/refman-5.1/introduction.xml
===================================================================
--- trunk/refman-5.1/introduction.xml	2006-01-28 19:13:56 UTC (rev 1082)
+++ trunk/refman-5.1/introduction.xml	2006-01-28 20:19:38 UTC (rev 1083)
@@ -1308,10 +1308,12 @@
 
         <listitem>
           <para>
-            Privileges for a table are not automatically revoked when
-            you delete a table. You must explicitly issue a
-            <literal>REVOKE</literal> statement to revoke privileges for
-            a table. See <xref linkend="grant"/>.
+            There are several differences between the MySQL and standard
+            SQL privilege systems. For example, in MySQL, privileges for
+            a table are not automatically revoked when you delete a
+            table. You must explicitly issue a <literal>REVOKE</literal>
+            statement to revoke privileges for a table. For more
+            information, see <xref linkend="grant"/>.
           </para>
         </listitem>
 

Modified: trunk/refman-5.1/sql-syntax.xml
===================================================================
--- trunk/refman-5.1/sql-syntax.xml	2006-01-28 19:13:56 UTC (rev 1082)
+++ trunk/refman-5.1/sql-syntax.xml	2006-01-28 20:19:38 UTC (rev 1083)
@@ -11707,6 +11707,24 @@
 
       <title>&title-account-management-sql;</title>
 
+      <para>
+        MySQL account information is stored in the tables of the
+        <literal>mysql</literal> database. This database and the access
+        control system are discussed extensively in
+        <xref linkend="database-administration"/>, which you should
+        consult for additional details.
+      </para>
+
+      <para>
+        <emphasis role="bold">Important</emphasis>: Some releases of
+        MySQL introduce changes to the structure of the grant tables to
+        add new privileges or features. Whenever you update to a new
+        version of MySQL, you should update your grant tables to make
+        sure that they have the current structure so that you can take
+        advantage of any new capabilities. See
+        <xref linkend="mysql-fix-privilege-tables"/>.
+      </para>
+
       <section id="create-user">
 
         <title>&title-create-user;</title>
@@ -11736,8 +11754,8 @@
         <remark role="help-description-begin"/>
 
         <para>
-          The <literal>CREATE USER</literal> creates new MySQL accounts.
-          To use it, you must have the global <literal>CREATE
+          The <literal>CREATE USER</literal> statement creates new MySQL
+          accounts. To use it, you must have the global <literal>CREATE
           USER</literal> privilege or the <literal>INSERT</literal>
           privilege for the <literal>mysql</literal> database. For each
           account, <literal>CREATE USER</literal> creates a new row in
@@ -11760,8 +11778,9 @@
           statement. In particular, to specify the password in plain
           text, omit the <literal>PASSWORD</literal> keyword. To specify
           the password as the hashed value as returned by the
-          <literal>PASSWORD()</literal> function, include the keyword
-          <literal>PASSWORD</literal>. See <xref linkend="grant"/>.
+          <literal>PASSWORD()</literal> function, include the
+          <literal>PASSWORD</literal> keyword. See
+          <xref linkend="grant"/>.
         </para>
 
         <remark role="help-description-end"/>
@@ -11827,9 +11846,10 @@
         <remark role="help-description-begin"/>
 
         <para>
-          The <literal>DROP USER</literal> statement deletes one or more
-          MySQL accounts. To use it, you must have the global
-          <literal>CREATE USER</literal> privilege or the
+          The <literal>DROP USER</literal> statement removes one or more
+          MySQL accounts. It removes privilege rows for the account from
+          all grant tables. To use this statement, you must have the
+          global <literal>CREATE USER</literal> privilege or the
           <literal>DELETE</literal> privilege for the
           <literal>mysql</literal> database. Each account is named using
           the same format as for the <literal>GRANT</literal> statement;
@@ -11849,11 +11869,6 @@
 DROP USER <replaceable>user</replaceable>;
 </programlisting>
 
-        <para>
-          The statement removes privilege rows for the account from all
-          grant tables.
-        </para>
-
         <remark role="help-description-end"/>
 
         <para>
@@ -11976,15 +11991,25 @@
         </para>
 
         <para>
+          <emphasis role="bold">Important</emphasis>: Some releases of
+          MySQL introduce changes to the structure of the grant tables
+          to add new privileges or features. Whenever you update to a
+          new version of MySQL, you should update your grant tables to
+          make sure that they have the current structure so that you can
+          take advantage of any new capabilities. See
+          <xref linkend="mysql-fix-privilege-tables"/>.
+        </para>
+
+        <para>
           If the grant tables hold privilege rows that contain
           mixed-case database or table names and the
           <literal>lower_case_table_names</literal> system variable is
-          set, <literal>REVOKE</literal> cannot be used to revoke the
-          privileges. It will be necessary to manipulate the grant
-          tables directly. (<literal>GRANT</literal> will not create
-          such rows when <literal>lower_case_table_names</literal> is
-          set, but such rows might have been created prior to setting
-          the variable.)
+          set to a non-zero value, <literal>REVOKE</literal> cannot be
+          used to revoke these privileges. It will be necessary to
+          manipulate the grant tables directly.
+          (<literal>GRANT</literal> will not create such rows when
+          <literal>lower_case_table_names</literal> is set, but such
+          rows might have been created prior to setting the variable.)
         </para>
 
         <para>
@@ -12064,11 +12089,12 @@
               The <literal>CREATE ROUTINE</literal>, <literal>ALTER
               ROUTINE</literal>, <literal>EXECUTE</literal>, and
               <literal>GRANT</literal> privileges apply to stored
-              routines. They can be granted at the global and database
-              levels. Also, except for <literal>CREATE
-              ROUTINE</literal>, these privileges can be granted at the
-              routine level for individual routines and are stored in
-              the <literal>mysql.procs_priv</literal> table.
+              routines (functions and procedures). They can be granted
+              at the global and database levels. Also, except for
+              <literal>CREATE ROUTINE</literal>, these privileges can be
+              granted at the routine level for individual routines and
+              are stored in the <literal>mysql.procs_priv</literal>
+              table.
             </para>
           </listitem>
 
@@ -12079,9 +12105,7 @@
           specified as <literal>TABLE</literal>,
           <literal>FUNCTION</literal>, or <literal>PROCEDURE</literal>
           when the following object is a table, a stored function, or a
-          stored procedure. To use this clause when upgrading from older
-          versions of MySQL, you must upgrade your grant tables. See
-          <xref linkend="mysql-fix-privilege-tables"/>.
+          stored procedure.
         </para>
 
         <remark role="help-description-end"/>
@@ -12112,8 +12136,8 @@
 
         <para>
           For the <literal>GRANT</literal> and <literal>REVOKE</literal>
-          statements, <literal>priv_type</literal> can be specified as
-          any of the following:
+          statements, <replaceable>priv_type</replaceable> can be
+          specified as any of the following:
         </para>
 
         <informaltable>
@@ -12135,7 +12159,7 @@
               </row>
               <row>
                 <entry><literal>ALTER ROUTINE</literal></entry>
-                <entry>Alter or drop stored routines</entry>
+                <entry>Enables stored routines to be altered or dropped</entry>
               </row>
               <row>
                 <entry><literal>CREATE</literal></entry>
@@ -12143,7 +12167,7 @@
               </row>
               <row>
                 <entry><literal>CREATE ROUTINE</literal></entry>
-                <entry>Create stored routines</entry>
+                <entry>Enables creation of stored routines</entry>
               </row>
               <row>
                 <entry><literal>CREATE TEMPORARY TABLES</literal></entry>
@@ -12253,16 +12277,6 @@
         </informaltable>
 
         <para>
-          To use the <literal>EXECUTE</literal>, <literal>CREATE
-          VIEW</literal>, <literal>SHOW VIEW</literal>, <literal>CREATE
-          USER</literal>, <literal>CREATE ROUTINE</literal>, and
-          <literal>ALTER ROUTINE</literal> privileges when upgrading
-          from an earlier version of MySQL that does not have them, you
-          must first upgrade your grant tables, as described in
-          <xref linkend="mysql-fix-privilege-tables"/>.
-        </para>
-
-        <para>
           The <literal>REFERENCES</literal> privilege currently is
           unused.
         </para>
@@ -12274,7 +12288,7 @@
 
         <para>
           Use <literal>SHOW GRANTS</literal> to determine what
-          privileges the account has. See <xref linkend="show-grants"/>.
+          privileges an account has. See <xref linkend="show-grants"/>.
         </para>
 
         <para>
@@ -12305,8 +12319,8 @@
         </para>
 
         <para>
-          The only <literal>priv_type</literal> values you can specify
-          for a table are <literal>SELECT</literal>,
+          The <replaceable>priv_type</replaceable> values that you can
+          specify for a table are <literal>SELECT</literal>,
           <literal>INSERT</literal>, <literal>UPDATE</literal>,
           <literal>DELETE</literal>, <literal>CREATE</literal>,
           <literal>DROP</literal>, <literal>GRANT OPTION</literal>,
@@ -12314,32 +12328,37 @@
         </para>
 
         <para>
-          The only <literal>priv_type</literal> values you can specify
-          for a column (that is, when you use a
-          <literal>column_list</literal> clause) are
+          The <replaceable>priv_type</replaceable> values that you can
+          specify for a column (that is, when you use a
+          <replaceable>column_list</replaceable> clause) are
           <literal>SELECT</literal>, <literal>INSERT</literal>, and
           <literal>UPDATE</literal>.
         </para>
 
         <para>
-          The only <literal>priv_type</literal> values you can specify
-          at the routine level are <literal>ALTER ROUTINE</literal>,
-          <literal>EXECUTE</literal>, and <literal>GRANT
-          OPTION</literal>. <literal>CREATE ROUTINE</literal> is not a
-          routine-level privilege because you must have this privilege
-          to create a routine in the first place.
+          The <replaceable>priv_type</replaceable> values that you can
+          specify at the routine level are <literal>ALTER
+          ROUTINE</literal>, <literal>EXECUTE</literal>, and
+          <literal>GRANT OPTION</literal>. <literal>CREATE
+          ROUTINE</literal> is not a routine-level privilege because you
+          must have this privilege to create a routine in the first
+          place.
         </para>
 
         <para>
           For the global, database, table, and routine levels,
           <literal>GRANT ALL</literal> assigns only the privileges that
-          exist at the level you are granting. For example, if you use
+          exist at the level you are granting. For example,
           <literal>GRANT ALL ON
-          <replaceable>db_name</replaceable>.*</literal>, that is a
-          database-level statement, so none of the global-only
-          privileges such as <literal>FILE</literal> are granted.
+          <replaceable>db_name</replaceable>.*</literal> is a
+          database-level statement, so it does not grant any global-only
+          privileges such as <literal>FILE</literal>.
         </para>
 
+        <remark role="todo">
+          [pd] Isn't next para false at the table and column levels?
+        </remark>
+
         <para>
           MySQL allows you to grant privileges even on database objects
           that do not exist. In such cases, the privileges to be granted
@@ -12417,7 +12436,7 @@
         </para>
 
 <programlisting>
-mysql&gt; <userinput>GRANT ALL ON test.* TO ''@'localhost' ...</userinput>
+GRANT ALL ON test.* TO ''@'localhost' ...
 </programlisting>
 
         <para>
@@ -12437,7 +12456,8 @@
           <literal>localhost</literal> in the
           <literal>mysql.user</literal> table (created during MySQL
           installation) is used when named users try to log in to the
-          MySQL server from the local machine.
+          MySQL server from the local machine. For details, see
+          <xref linkend="connection-access"/>.
         </para>
 
         <para>
@@ -12446,7 +12466,7 @@
         </para>
 
 <programlisting>
-mysql&gt; <userinput>SELECT Host, User FROM mysql.user WHERE User='';</userinput>
+SELECT Host, User FROM mysql.user WHERE User='';
 </programlisting>
 
         <para>
@@ -12455,8 +12475,8 @@
         </para>
 
 <programlisting>
-mysql&gt; <userinput>DELETE FROM mysql.user WHERE Host='localhost' AND User='';</userinput>
-mysql&gt; <userinput>FLUSH PRIVILEGES;</userinput>
+DELETE FROM mysql.user WHERE Host='localhost' AND User='';
+FLUSH PRIVILEGES;
 </programlisting>
 
         <para>
@@ -12469,15 +12489,15 @@
           attempting to do so results in unpredictable behavior which
           may even make it impossible for users to log in to the MySQL
           server</emphasis>. You should never attempt to alter the grant
-          tables in any way except by means of the
-          <literal>mysql_fix_privilege_tables</literal> script as
-          supplied by MySQL AB for use in upgrading the MySQL server.
+          tables in any way except by means of the procedure prescribed
+          by MySQL AB that is described in
+          <xref linkend="mysql-fix-privilege-tables"/>.
         </para>
 
         <para>
           The privileges for a table or column are formed additively as
           the logical <literal>OR</literal> of the privileges at each of
-          the four privilege levels. For example, if the
+          the privilege levels. For example, if the
           <literal>mysql.user</literal> table specifies that a user has
           a global <literal>SELECT</literal> privilege, the privilege
           cannot be denied by an entry at the database, table, or column
@@ -12513,6 +12533,17 @@
           USER</literal> or <literal>DELETE</literal>.
         </para>
 
+        <para>
+          <emphasis role="bold">Warning</emphasis>: If you create a new
+          user but do not specify an <literal>IDENTIFIED BY</literal>
+          clause, the user has no password. This is very insecure.
+          However, you can enable the
+          <literal>NO_AUTO_CREATE_USER</literal> SQL mode to keep
+          <literal>GRANT</literal> from creating a new user if it would
+          otherwise do so, unless <literal>IDENTIFIED BY</literal> is
+          given to provide the new user a non-empty password.
+        </para>
+
         <indexterm>
           <primary>passwords</primary>
           <secondary>setting</secondary>
@@ -12527,17 +12558,6 @@
         </para>
 
         <para>
-          <emphasis role="bold">Warning</emphasis>: If you create a new
-          user but do not specify an <literal>IDENTIFIED BY</literal>
-          clause, the user has no password. This is very insecure.
-          However, you can enable the
-          <literal>NO_AUTO_CREATE_USER</literal> SQL mode to keep
-          <literal>GRANT</literal> from creating a new user if it would
-          otherwise do so, unless <literal>IDENTIFIED BY</literal> is
-          given to provide the new user a non-empty password.
-        </para>
-
-        <para>
           Passwords can also be set with the <literal>SET
           PASSWORD</literal> statement. See
           <xref linkend="set-password"/>.
@@ -12584,12 +12604,6 @@
         </para>
 
         <para>
-          If a user has no privileges for a table, the table name is not
-          displayed when the user requests a list of tables (for
-          example, with a <literal>SHOW TABLES</literal> statement).
-        </para>
-
-        <para>
           The <literal>SHOW DATABASES</literal> privilege enables the
           account to see database names by issuing the <literal>SHOW
           DATABASE</literal> statement. Accounts that do not have this
@@ -12600,6 +12614,12 @@
         </para>
 
         <para>
+          If a user has no privileges for a table, the table name is not
+          displayed when the user requests a list of tables (for
+          example, with a <literal>SHOW TABLES</literal> statement).
+        </para>
+
+        <para>
           The <literal>WITH GRANT OPTION</literal> clause gives the user
           the ability to give to other users any privileges the user has
           at the specified privilege level. You should be careful to
@@ -12619,12 +12639,12 @@
           Be aware that when you grant a user the <literal>GRANT
           OPTION</literal> privilege at a particular privilege level,
           any privileges the user possesses (or may be given in the
-          future) at that level can also be granted by that user.
-          Suppose that you grant a user the <literal>INSERT</literal>
-          privilege on a database. If you then grant the
-          <literal>SELECT</literal> privilege on the database and
-          specify <literal>WITH GRANT OPTION</literal>, that user can
-          give to other users not only the <literal>SELECT</literal>
+          future) at that level can also be granted by that user to
+          other users. Suppose that you grant a user the
+          <literal>INSERT</literal> privilege on a database. If you then
+          grant the <literal>SELECT</literal> privilege on the database
+          and specify <literal>WITH GRANT OPTION</literal>, that user
+          can give to other users not only the <literal>SELECT</literal>
           privilege, but also <literal>INSERT</literal>. If you then
           grant the <literal>UPDATE</literal> privilege to the user on
           the database, the user can grant <literal>INSERT</literal>,
@@ -12632,9 +12652,10 @@
         </para>
 
         <para>
-          You should not grant <literal>ALTER</literal> privileges to a
-          normal user. If you do that, the user can try to subvert the
-          privilege system by renaming tables!
+          For a non-administrative user, you should not grant the
+          <literal>ALTER</literal> privilege globally or for the
+          <literal>mysql</literal> database. If you do that, the user
+          can try to subvert the privilege system by renaming tables!
         </para>
 
         <para>
@@ -12716,8 +12737,8 @@
             </para>
 
 <programlisting>
-mysql&gt; <userinput>GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost'</userinput>
-    -&gt; <userinput>IDENTIFIED BY 'goodsecret' REQUIRE SSL;</userinput>
+GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost'
+  IDENTIFIED BY 'goodsecret' REQUIRE SSL;
 </programlisting>
           </listitem>
 
@@ -12731,8 +12752,8 @@
             </para>
 
 <programlisting>
-mysql&gt; <userinput>GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost'</userinput>
-    -&gt; <userinput>IDENTIFIED BY 'goodsecret' REQUIRE X509;</userinput>
+GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost'
+  IDENTIFIED BY 'goodsecret' REQUIRE X509;
 </programlisting>
           </listitem>
 
@@ -12743,11 +12764,10 @@
               restriction on connection attempts that the client must
               present a valid X509 certificate issued by CA
               <literal>'<replaceable>issuer</replaceable>'</literal>. If
-              the client presents the client presents a certificate that
-              is valid but has a different issuer, the server rejects
-              the connection. Use of X509 certificates always implies
-              encryption, so the <literal>SSL</literal> option is
-              unnecessary in this case.
+              the client presents a certificate that is valid but has a
+              different issuer, the server rejects the connection. Use
+              of X509 certificates always implies encryption, so the
+              <literal>SSL</literal> option is unnecessary in this case.
             </para>
 
             <remark role="todo">
@@ -12756,15 +12776,16 @@
             </remark>
 
 <programlisting>
-mysql&gt; <userinput>GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost'</userinput>
-    -&gt; <userinput>IDENTIFIED BY 'goodsecret'</userinput>
-    -&gt; <userinput>REQUIRE ISSUER '/C=FI/ST=Some-State/L=Helsinki/</userinput>
-       O=MySQL Finland AB/CN=Tonu Samuel/Email=tonu@stripped';
+GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost'
+  IDENTIFIED BY 'goodsecret'
+  REQUIRE ISSUER '/C=FI/ST=Some-State/L=Helsinki/
+    O=MySQL Finland AB/CN=Tonu Samuel/Email=tonu@stripped';
 </programlisting>
 
             <para>
-              Note that the <literal>ISSUER</literal> value should be
-              entered as a single string.
+              Note that the
+              <literal>'<replaceable>issuer</replaceable>'</literal>
+              value should be entered as a single string.
             </para>
           </listitem>
 
@@ -12780,16 +12801,17 @@
             </para>
 
 <programlisting>
-mysql&gt; <userinput>GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost'</userinput>
-    -&gt; <userinput>IDENTIFIED BY 'goodsecret'</userinput>
-    -&gt; <userinput>REQUIRE SUBJECT '/C=EE/ST=Some-State/L=Tallinn/</userinput>
-       O=MySQL demo client certificate/
-       CN=Tonu Samuel/Email=tonu@stripped';
+GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost'
+  IDENTIFIED BY 'goodsecret'
+  REQUIRE SUBJECT '/C=EE/ST=Some-State/L=Tallinn/
+    O=MySQL demo client certificate/
+    CN=Tonu Samuel/Email=tonu@stripped';
 </programlisting>
 
             <para>
-              Note that the <literal>SUBJECT</literal> value should be
-              entered as a single string.
+              Note that the
+              <literal>'<replaceable>subject</replaceable>'</literal>
+              value should be entered as a single string.
             </para>
           </listitem>
 
@@ -12805,9 +12827,9 @@
             </para>
 
 <programlisting>
-mysql&gt; <userinput>GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost'</userinput>
-    -&gt; <userinput>IDENTIFIED BY 'goodsecret'</userinput>
-    -&gt; <userinput>REQUIRE CIPHER 'EDH-RSA-DES-CBC3-SHA';</userinput>
+GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost'
+  IDENTIFIED BY 'goodsecret'
+  REQUIRE CIPHER 'EDH-RSA-DES-CBC3-SHA';
 </programlisting>
           </listitem>
 
@@ -12820,23 +12842,17 @@
         </para>
 
 <programlisting>
-mysql&gt; <userinput>GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost'</userinput>
-    -&gt; <userinput>IDENTIFIED BY 'goodsecret'</userinput>
-    -&gt; <userinput>REQUIRE SUBJECT '/C=EE/ST=Some-State/L=Tallinn/</userinput>
-       O=MySQL demo client certificate/
-       CN=Tonu Samuel/Email=tonu@stripped'
-    -&gt; <userinput>AND ISSUER '/C=FI/ST=Some-State/L=Helsinki/</userinput>
-       O=MySQL Finland AB/CN=Tonu Samuel/Email=tonu@stripped'
-    -&gt; <userinput>AND CIPHER 'EDH-RSA-DES-CBC3-SHA';</userinput>
+GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost'
+  IDENTIFIED BY 'goodsecret'
+  REQUIRE SUBJECT '/C=EE/ST=Some-State/L=Tallinn/
+    O=MySQL demo client certificate/
+    CN=Tonu Samuel/Email=tonu@stripped'
+  AND ISSUER '/C=FI/ST=Some-State/L=Helsinki/
+    O=MySQL Finland AB/CN=Tonu Samuel/Email=tonu@stripped'
+  AND CIPHER 'EDH-RSA-DES-CBC3-SHA';
 </programlisting>
 
         <para>
-          Note that the <literal>SUBJECT</literal> and
-          <literal>ISSUER</literal> values each should be entered as a
-          single string.
-        </para>
-
-        <para>
           The <literal>AND</literal> keyword is optional between
           <literal>REQUIRE</literal> options.
         </para>

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