List:Commits« Previous MessageNext Message »
From:paul Date:January 4 2006 6:54am
Subject:svn commit - mysqldoc@docsrva: r667 - in trunk: . refman-4.1 refman-5.0 refman-5.1 refman-common
View as plain text  
Author: paul
Date: 2006-01-04 07:54:26 +0100 (Wed, 04 Jan 2006)
New Revision: 667

Log:
 r5822@frost:  paul | 2006-01-04 00:54:10 -0600
 Add some markup.


Modified:
   trunk/
   trunk/refman-4.1/connector-j.xml
   trunk/refman-5.0/connector-j.xml
   trunk/refman-5.1/connector-j.xml
   trunk/refman-common/titles.en.ent


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

Modified: trunk/refman-4.1/connector-j.xml
===================================================================
--- trunk/refman-4.1/connector-j.xml	2006-01-04 06:25:17 UTC (rev 666)
+++ trunk/refman-4.1/connector-j.xml	2006-01-04 06:54:26 UTC (rev 667)
@@ -11,7 +11,7 @@
 ]>
 <section id="java-connector">
 
-  <title>MySQL Connector/J</title>
+  <title>&title-java-connector;</title>
 
   <para>
     MySQL provides connectivity for client applications developed in the
@@ -20,28 +20,26 @@
   </para>
 
   <para>
-    MySQL Connector/J is a JDBC-3.0 "Type 4" driver, which means that is
-    is pure Java, implements version 3.0 of the JDBC specification, and
-    communicates directly with the MySQL server using the MySQL
-    protocol.
+    MySQL Connector/J is a JDBC-3.0 <quote>Type 4</quote> driver, which
+    means that is is pure Java, implements version 3.0 of the JDBC
+    specification, and communicates directly with the MySQL server using
+    the MySQL protocol.
   </para>
 
   <para>
     This document is arranged for a beginning JDBC developer. If you are
     already experienced with using JDBC, you might consider starting
-    with the section "<link linkend="cj-installing">Installing
-    Connector/J</link>".
+    with the section <xref linkend="cj-installing"/>.
   </para>
 
   <para>
     While JDBC is useful by itself, we would hope that if you are not
     familiar with JDBC that after reading the first few sections of this
-    manual, that you would avoid using "naked" JDBC for all but the most
-    trivial problems and consider using one of the popular persistence
-    frameworks such as
+    manual, that you would avoid using <quote>naked</quote> JDBC for all
+    but the most trivial problems and consider using one of the popular
+    persistence frameworks such as
     <ulink url="http://www.hibernate.org/">Hibernate</ulink>,
-    <ulink
-  url="http://www.springframework.org/">Spring's JDBC
+    <ulink url="http://www.springframework.org/">Spring's JDBC
     templates</ulink> or
     <ulink url="http://www.ibatis.com/common/sqlmaps.html">Ibatis SQL
     Maps</ulink> to do the majority of repetitive work and heavier
@@ -61,17 +59,16 @@
       <para>
         <ulink
       url="http://java.sun.com/docs/books/tutorial/jdbc/basics/index.html">JDBC
-        Basics </ulink>- A tutorial from Sun covering beginner topics in
-        JDBC
+        Basics </ulink> &mdash; A tutorial from Sun covering beginner
+        topics in JDBC
       </para>
     </listitem>
 
     <listitem>
       <para>
-        <ulink
-      url="http://java.sun.com/developer/onlineTraining/Database/JDBCShortCourse/index.html">JDBC
-        Short Course</ulink> - A more in-depth tutorial from Sun and
-        JGuru
+        <ulink url="http://java.sun.com/developer/onlineTraining/Database/JDBCShortCourse/index.html">JDBC
+        Short Course</ulink> &mdash; A more in-depth tutorial from Sun
+        and JGuru
       </para>
     </listitem>
 
@@ -79,7 +76,7 @@
 
   <section id="cj-basic-jdbc">
 
-    <title>Basic JDBC concepts</title>
+    <title>&title-cj-basic-jdbc;</title>
 
     <para>
       This section provides some general JDBC background.
@@ -87,26 +84,30 @@
 
     <section id="cj-connect-with-drivermanager">
 
-      <title>Connecting to MySQL using the DriverManager Interface</title>
+      <title>&title-cj-connect-with-drivermanager;</title>
 
       <para>
         When you are using JDBC outside of an application server, the
-        DriverManager class manages the establishment of Connections.
+        <literal>DriverManager</literal> class manages the establishment
+        of Connections.
       </para>
 
       <para>
-        The DriverManager needs to be told which JDBC drivers it should
-        try to make Connections with. The easiest way to do this is to
-        use Class.forName() on the class that implements the
-        java.sql.Driver interface. With MySQL Connector/J, the name of
-        this class is com.mysql.jdbc.Driver. With this method, you could
-        use an external configuration file to supply the driver class
-        name and driver parameters to use when connecting to a database.
+        The <literal>DriverManager</literal> needs to be told which JDBC
+        drivers it should try to make Connections with. The easiest way
+        to do this is to use <literal>Class.forName()</literal> on the
+        class that implements the <literal>java.sql.Driver</literal>
+        interface. With MySQL Connector/J, the name of this class is
+        <literal>com.mysql.jdbc.Driver</literal>. With this method, you
+        could use an external configuration file to supply the driver
+        class name and driver parameters to use when connecting to a
+        database.
       </para>
 
       <para>
         The following section of Java code shows how you might register
-        MySQL Connector/J from the main() method of your application:
+        MySQL Connector/J from the <literal>main()</literal> method of
+        your application:
       </para>
 
 <programlisting>import java.sql.Connection;
@@ -129,21 +130,24 @@
 }</programlisting>
 
       <para>
-        After the driver has been registered with the DriverManager, you
-        can obtain a Connection instance that is connected to a
-        particular database by calling DriverManager.getConnection():
+        After the driver has been registered with the
+        <literal>DriverManager</literal>, you can obtain a
+        <literal>Connection</literal> instance that is connected to a
+        particular database by calling
+        <literal>DriverManager.getConnection()</literal>:
       </para>
 
       <example>
 
-        <title>Obtaining a Connection From the DriverManager</title>
+        <title>Obtaining a Connection From the <literal>DriverManager</literal></title>
 
         <para>
-          This example shows how you can obtain a Connection instance
-          from the DriverManager. There are a few different signatures
-          for the getConnection() method. You should see the API
-          documentation that comes with your JDK for more specific
-          information on how to use them.
+          This example shows how you can obtain a
+          <literal>Connection</literal> instance from the
+          <literal>DriverManager</literal>. There are a few different
+          signatures for the <literal>getConnection()</literal> method.
+          You should see the API documentation that comes with your JDK
+          for more specific information on how to use them.
         </para>
 
 <programlisting>
@@ -166,9 +170,10 @@
 </programlisting>
 
         <para>
-          Once a Connection is established, it can be used to create
-          Statements and PreparedStatements, as well as retrieve
-          metadata about the database. This is explained in the
+          Once a <literal>Connection</literal> is established, it can be
+          used to create <literal>Statement</literal> and
+          <literal>PreparedStatement</literal> objects, as well as
+          retrieve metadata about the database. This is explained in the
           following sections.
         </para>
 
@@ -178,7 +183,7 @@
 
 <!--
         <section id="cj-connect-with-datasource">
-          <title>Connecting to MySQL using the DataSource Interface</title>
+          <title>&title-cj-connect-with-datasource;;</title>
 
           <para />
         </section>
@@ -197,47 +202,56 @@
       <title>Using Statements to Execute SQL</title>
 
       <para>
-        Statements allow you to execute basic SQL queries and retrieve
-        the results through the ResultSet class which is described
-        later.
+        <literal>Statement</literal> objects allow you to execute basic
+        SQL queries and retrieve the results through the
+        <literal>ResultSet</literal> class which is described later.
       </para>
 
       <para>
-        To create a Statement instance, you call the createStatement()
-        method on the Connection object you have retrieved via one of
-        the DriverManager.getConnection() or DataSource.getConnection()
-        methods described earlier.
+        To create a <literal>Statement</literal> instance, you call the
+        <literal>createStatement()</literal> method on the
+        <literal>Connection</literal> object you have retrieved via one
+        of the <literal>DriverManager.getConnection()</literal> or
+        <literal>DataSource.getConnection()</literal> methods described
+        earlier.
       </para>
 
       <para>
-        Once you have a Statement instance, you can execute a SELECT
-        query by calling the executeQuery(String) method with the SQL
-        you want to use.
+        Once you have a <literal>Statement</literal> instance, you can
+        execute a <literal>SELECT</literal> query by calling the
+        <literal>executeQuery(String)</literal> method with the SQL you
+        want to use.
       </para>
 
       <para>
-        To update data in the database use the executeUpdate(String SQL)
-        method. This method returns the number of rows affected by the
-        update statement.
+        To update data in the database use the
+        <literal>executeUpdate(String SQL)</literal> method. This method
+        returns the number of rows affected by the update statement.
       </para>
 
       <para>
         If you don't know ahead of time whether the SQL statement will
-        be a SELECT or an UPDATE/INSERT, then you can use the
-        execute(String SQL) method. This method will return true if the
-        SQL query was a SELECT, or false if an UPDATE/INSERT/DELETE
-        query. If the query was a SELECT query, you can retrieve the
-        results by calling the getResultSet() method. If the query was
-        an UPDATE/INSERT/DELETE query, you can retrieve the affected
-        rows count by calling getUpdateCount() on the Statement
-        instance.
+        be a <literal>SELECT</literal> or an
+        <literal>UPDATE</literal>/<literal>INSERT</literal>, then you
+        can use the <literal>execute(String SQL)</literal> method. This
+        method will return true if the SQL query was a
+        <literal>SELECT</literal>, or false if it was an
+        <literal>UPDATE</literal>, <literal>INSERT</literal>, or
+        <literal>DELETE</literal> statement. If the statement was a
+        <literal>SELECT</literal> query, you can retrieve the results by
+        calling the <literal>getResultSet()</literal> method. If the
+        statement was an <literal>UPDATE</literal>,
+        <literal>INSERT</literal>, or <literal>DELETE</literal>
+        statement, you can retrieve the affected rows count by calling
+        <literal>getUpdateCount()</literal> on the
+        <literal>Statement</literal> instance.
       </para>
 
       <example>
 
         <title>Using java.sql.Statement to Execute a SELECT Query</title>
 
-<programlisting>// assume conn is an already created JDBC connection
+<programlisting>// assume that conn is an already created JDBC connection
 Statement stmt = null;
 ResultSet rs = null;
 
@@ -302,8 +316,7 @@
 
       <para>
         MySQL's stored procedure syntax is documented in the
-        "<ulink
-      url="http://www.mysql.com/doc/en/Stored_Procedures.html">Stored
+        "<ulink url="http://www.mysql.com/doc/en/stored-procedures.html">Stored
         Procedures and Functions</ulink>" section of the MySQL Reference
         Manual.
       </para>
@@ -887,7 +900,7 @@
 
   <section id="cj-installing">
 
-    <title>Installing Connector/J</title>
+    <title>&title-cj-installing;</title>
 
     <para>
       Use the following instructions to install Connector/J
@@ -895,13 +908,13 @@
 
     <section id="cj-system-requirements">
 
-      <title>Required Software Versions</title>
+      <title>&title-cj-system-requirements;</title>
 
       <para></para>
 
       <section id="cj-supported-java-versions">
 
-        <title>Java Versions Supported</title>
+        <title>&title-cj-supported-java-versions;</title>
 
         <para>
           MySQL Connector/J supports Java-2 JVMs, including JDK-1.2.x,
@@ -963,23 +976,23 @@
         <para>
           MySQL Connector/J is distributed as a .zip or .tar.gz archive
           containing the sources, the class files a class-file only
-          "binary" .jar archive named
+          <quote>binary</quote> .jar archive named
           "<filename>mysql-connector-java-[version]-bin.jar</filename>",
-          and starting with Connector/J 3.1.8 a "debug" build of the
-          driver in a file named
+          and starting with Connector/J 3.1.8 a <quote>debug</quote>
+          build of the driver in a file named
           "<filename>mysql-connector-java-[version]-bin-g.jar</filename>".
         </para>
 
         <para>
           Starting with Connector/J 3.1.9, we don't ship the .class
-          files "unbundled", they are only available in the JAR archives
-          that ship with the driver.
+          files <quote>unbundled</quote>, they are only available in the
+          JAR archives that ship with the driver.
         </para>
 
         <para>
-          You should not use the "debug" build of the driver unless
-          instructed to do so when reporting a problem or bug to MySQL
-          AB, as it is not designed to be run in production
+          You should not use the <quote>debug</quote> build of the
+          driver unless instructed to do so when reporting a problem or
+          bug to MySQL AB, as it is not designed to be run in production
           environments, and will have adverse performance impact when
           used. The debug binary also depends on the Aspect/J runtime
           library, which is located in the
@@ -990,12 +1003,12 @@
         <para>
           You will need to use the appropriate graphical or command-line
           utility to un-archive the distribution (for example, WinZip
-          for the .zip archive, and "tar" for the .tar.gz archive).
-          Because there are potentially long filenames in the
-          distribution, we use the GNU tar archive format. You will need
-          to use GNU tar (or an application that understands the GNU tar
-          archive format) to unpack the .tar.gz variant of the
-          distribution.
+          for the .zip archive, and <command>tar</command> for the
+          .tar.gz archive). Because there are potentially long filenames
+          in the distribution, we use the GNU tar archive format. You
+          will need to use GNU tar (or an application that understands
+          the GNU tar archive format) to unpack the .tar.gz variant of
+          the distribution.
         </para>
 
         <para>
@@ -1228,12 +1241,13 @@
             <para>
               New SQLState Codes - Connector/J 3.1 uses SQL:1999
               SQLState codes returned by the MySQL server (if
-              supported), which are different than the "legacy" X/Open
-              state codes that Connector/J 3.0 uses. If connected to a
-              MySQL server older than MySQL-4.1.0 (the oldest version to
-              return SQLStates as part of the error code), the driver
-              will use a built-in mapping. You can revert to the old
-              mapping by using the following configuration property:
+              supported), which are different than the
+              <quote>legacy</quote> X/Open state codes that Connector/J
+              3.0 uses. If connected to a MySQL server older than
+              MySQL-4.1.0 (the oldest version to return SQLStates as
+              part of the error code), the driver will use a built-in
+              mapping. You can revert to the old mapping by using the
+              following configuration property:
             </para>
 
             <para>
@@ -1259,27 +1273,27 @@
 
           <listitem>
             <para>
-              Starting with Connector/J 3.1.8 a "debug" build of the
-              driver in a file named
+              Starting with Connector/J 3.1.8 a <quote>debug</quote>
+              build of the driver in a file named
               "<filename>mysql-connector-java-[version]-bin-g.jar</filename>"
-              is shipped alongside the normal "binary" jar file that is
-              named
+              is shipped alongside the normal <quote>binary</quote> jar
+              file that is named
               "<filename>mysql-connector-java-[version]-bin.jar</filename>".
             </para>
 
             <para>
               Starting with Connector/J 3.1.9, we don't ship the .class
-              files "unbundled", they are only available in the JAR
-              archives that ship with the driver.
+              files <quote>unbundled</quote>, they are only available in
+              the JAR archives that ship with the driver.
             </para>
 
             <para>
-              You should not use the "debug" build of the driver unless
-              instructed to do so when reporting a problem or bug to
-              MySQL AB, as it is not designed to be run in production
-              environments, and will have adverse performance impact
-              when used. The debug binary also depends on the Aspect/J
-              runtime library, which is located in the
+              You should not use the <quote>debug</quote> build of the
+              driver unless instructed to do so when reporting a problem
+              or bug to MySQL AB, as it is not designed to be run in
+              production environments, and will have adverse performance
+              impact when used. The debug binary also depends on the
+              Aspect/J runtime library, which is located in the
               <filename>src/lib/aspectjrt.jar</filename> file that comes
               with the Connector/J distribution.
             </para>
@@ -1392,12 +1406,12 @@
 
       <para>
         MySQL Connector/J has fail-over support. This allows the driver
-        to fail-over to any number of "slave" hosts and still perform
-        read-only queries. Fail-over only happens when the connection is
-        in an autoCommit(true) state, because fail-over can not happen
-        reliably when a transaction is in progress. Most application
-        servers and connection pools set autoCommit to 'true' at the end
-        of every transaction/connection use.
+        to fail-over to any number of <quote>slave</quote> hosts and
+        still perform read-only queries. Fail-over only happens when the
+        connection is in an autoCommit(true) state, because fail-over
+        can not happen reliably when a transaction is in progress. Most
+        application servers and connection pools set autoCommit to
+        'true' at the end of every transaction/connection use.
       </para>
 
       <para>
@@ -1788,9 +1802,9 @@
             <row>
               <entry>cachePrepStmts</entry>
               <entry>Should the driver cache the parsing stage of PreparedStatements of
-                client-side prepared statements, the "check" for
-                suitability of server-side prepared and server-side
-                prepared statements themselves?</entry>
+                client-side prepared statements, the
+                <quote>check</quote> for suitability of server-side
+                prepared and server-side prepared statements themselves?</entry>
               <entry>No</entry>
               <entry>false</entry>
               <entry>3.0.10</entry>
@@ -2565,12 +2579,13 @@
 
           <para>
             Unlike older versions of MM.MySQL the 'isClosed()' method
-            does not "ping" the server to determine if it is alive. In
-            accordance with the JDBC specification, it only returns true
-            if 'closed()' has been called on the connection. If you need
-            to determine if the connection is still valid, you should
-            issue a simple query, such as "SELECT 1". The driver will
-            throw an exception if the connection is no longer valid.
+            does not <quote>ping</quote> the server to determine if it
+            is alive. In accordance with the JDBC specification, it only
+            returns true if 'closed()' has been called on the
+            connection. If you need to determine if the connection is
+            still valid, you should issue a simple query, such as
+            "SELECT 1". The driver will throw an exception if the
+            connection is no longer valid.
           </para>
         </listitem>
 
@@ -2616,12 +2631,13 @@
 
           <para>
             Take care when using a server-side prepared statement with
-            "large" parameters that are set via setBinaryStream(),
-            setAsciiStream(), setUnicodeStream(), setBlob(), or
-            setClob(). If you want to re-execute the statement with any
-            "large" parameter changed to a non-"large" parameter, it is
-            necessary to call clearParameters() and set all parameters
-            again. The reason for this is as follows:
+            <quote>large</quote> parameters that are set via
+            setBinaryStream(), setAsciiStream(), setUnicodeStream(),
+            setBlob(), or setClob(). If you want to re-execute the
+            statement with any <quote>large</quote> parameter changed to
+            a non-<quote>large</quote> parameter, it is necessary to
+            call clearParameters() and set all parameters again. The
+            reason for this is as follows:
           </para>
 
           <itemizedlist>
@@ -2652,24 +2668,25 @@
 
             <listitem>
               <para>
-                If a parameter changes from "large" to non-"large", the
-                driver must reset the server-side state of the prepared
-                statement to allow the parameter that is being changed
-                to take the place of the prior "large" value. This
-                removes all of the 'large' data that has already been
-                sent to the server, thus requiring the data to be
-                re-sent, via the setBinaryStream(), setAsciiStream(),
-                setUnicodeStream(), setBlob() or setClob() methods.
+                If a parameter changes from <quote>large</quote> to
+                non-<quote>large</quote>, the driver must reset the
+                server-side state of the prepared statement to allow the
+                parameter that is being changed to take the place of the
+                prior <quote>large</quote> value. This removes all of
+                the 'large' data that has already been sent to the
+                server, thus requiring the data to be re-sent, via the
+                setBinaryStream(), setAsciiStream(), setUnicodeStream(),
+                setBlob() or setClob() methods.
               </para>
             </listitem>
 
           </itemizedlist>
 
           <para>
-            Consequently, if you want to change the "type" of a
-            parameter to a non-"large" one, you must call
-            clearParameters() and set all parameters of the prepared
-            statement again before it can be re-executed.
+            Consequently, if you want to change the <quote>type</quote>
+            of a parameter to a non-<quote>large</quote> one, you must
+            call clearParameters() and set all parameters of the
+            prepared statement again before it can be re-executed.
           </para>
         </listitem>
 
@@ -2702,9 +2719,9 @@
           <para>
             The combination of a forward-only, read-only result set,
             with a fetch size of Integer.MIN_VALUE serves as a signal to
-            the driver to "stream" result sets row-by-row. After this
-            any result sets created with the statement will be retrieved
-            row-by-row.
+            the driver to <quote>stream</quote> result sets row-by-row.
+            After this any result sets created with the statement will
+            be retrieved row-by-row.
           </para>
 
           <para>
@@ -2731,10 +2748,10 @@
           </para>
 
           <para>
-            Therefore, if using "streaming" results, you should process
-            them as quickly as possible if you want to maintain
-            concurrent access to the tables referenced by the statement
-            producing the result set.
+            Therefore, if using <quote>streaming</quote> results, you
+            should process them as quickly as possible if you want to
+            maintain concurrent access to the tables referenced by the
+            statement producing the result set.
           </para>
         </listitem>
 
@@ -3496,17 +3513,17 @@
         <function>Connection.setReadOnly(true)</function>, this
         "replication-aware" connection will use one of the slave
         connections, which are load-balanced per-vm using a round-robin
-        scheme (a given connection is "sticky" to a slave unless that
-        slave is removed from service). If you have a write transaction,
-        or if you have a read that is "time-sensitive" (remember,
-        replication in MySQL is asynchronous), set the connection to be
-        not read-only, by calling
+        scheme (a given connection is <quote>sticky</quote> to a slave
+        unless that slave is removed from service). If you have a write
+        transaction, or if you have a read that is "time-sensitive"
+        (remember, replication in MySQL is asynchronous), set the
+        connection to be not read-only, by calling
         <function>Connection.setReadOnly(false)</function> and the
-        driver will ensure that further calls are sent to the "master"
-        MySQL server. The driver takes care of propagating the current
-        state of autocommit, isolation level, and catalog between all of
-        the connections that it uses to accomplish this load balancing
-        functionality.
+        driver will ensure that further calls are sent to the
+        <quote>master</quote> MySQL server. The driver takes care of
+        propagating the current state of autocommit, isolation level,
+        and catalog between all of the connections that it uses to
+        accomplish this load balancing functionality.
       </para>
 
       <para>
@@ -3615,14 +3632,14 @@
         </para>
 
         <para>
-          This technique of "pooling" connections is based on the fact
-          that most applications only need a thread to have access to a
-          JDBC connection when they are actively processing a
-          transaction, which usually take only milliseconds to complete.
-          When not processing a transaction, the connection would
-          otherwise sit idle. Instead, connection pooling allows the
-          idle connection to be used by some other thread to do useful
-          work.
+          This technique of <quote>pooling</quote> connections is based
+          on the fact that most applications only need a thread to have
+          access to a JDBC connection when they are actively processing
+          a transaction, which usually take only milliseconds to
+          complete. When not processing a transaction, the connection
+          would otherwise sit idle. Instead, connection pooling allows
+          the idle connection to be used by some other thread to do
+          useful work.
         </para>
 
         <para>
@@ -4057,10 +4074,10 @@
         that comes with Connector/J to the <filename>lib</filename>
         directory for your server configuration (which is usually called
         "<filename>default</filename>"). Then, in the same configuration
-        directory, in the subdirectory named "deploy", create a
-        datasource configuration file that ends with "-ds.xml", which
-        tells JBoss to deploy this file as a JDBC Datasource. The file
-        should have the following contents:
+        directory, in the subdirectory named <quote>deploy</quote>,
+        create a datasource configuration file that ends with "-ds.xml",
+        which tells JBoss to deploy this file as a JDBC Datasource. The
+        file should have the following contents:
       </para>
 
 <programlisting>&lt;datasources&gt;
@@ -4235,13 +4252,16 @@
             <note>
 
               <para>
-                Testing your connectivity with the "mysql" command-line
-                client will not work unless you add the "--host" flag,
-                and use something other than "localhost" for the host.
-                The "mysql" command-line client will use Unix domain
-                sockets if you use the special hostname "localhost". If
-                you are testing connectivity to "localhost", use
-                "127.0.0.1" as the hostname instead.
+                Testing your connectivity with the
+                <command>mysql</command> command-line client will not
+                work unless you add the <option>--host</option> flag,
+                and use something other than
+                <literal>localhost</literal> for the host. The
+                <command>mysql</command> command-line client will use
+                Unix domain sockets if you use the special hostname
+                <literal>localhost</literal>. If you are testing
+                connectivity to <literal>localhost</literal>, use
+                <literal>127.0.0.1</literal> as the hostname instead.
               </para>
 
             </note>
@@ -4344,15 +4364,15 @@
               option set (the Debian Linux package of MySQL server does
               this for example), you need to comment it out in the file
               /etc/mysql/my.cnf or /etc/my.cnf. Of course your my.cnf
-              file might also exist in the "data" directory of your
-              MySQL server, or anywhere else (depending on how MySQL was
-              compiled for your system). Binaries created by MySQL AB
-              always look in /etc/my.cnf and [datadir]/my.cnf. If your
-              MySQL server has been firewalled, you will need to have
-              the firewall configured to allow TCP/IP connections from
-              the host where your Java code is running to the MySQL
-              server on the port that MySQL is listening to (by default,
-              3306).
+              file might also exist in the <filename>data</filename>
+              directory of your MySQL server, or anywhere else
+              (depending on how MySQL was compiled for your system).
+              Binaries created by MySQL AB always look in /etc/my.cnf
+              and [datadir]/my.cnf. If your MySQL server has been
+              firewalled, you will need to have the firewall configured
+              to allow TCP/IP connections from the host where your Java
+              code is running to the MySQL server on the port that MySQL
+              is listening to (by default, 3306).
             </para>
 
           </answer>

Modified: trunk/refman-5.0/connector-j.xml
===================================================================
--- trunk/refman-5.0/connector-j.xml	2006-01-04 06:25:17 UTC (rev 666)
+++ trunk/refman-5.0/connector-j.xml	2006-01-04 06:54:26 UTC (rev 667)
@@ -11,7 +11,7 @@
 ]>
 <section id="java-connector">
 
-  <title>MySQL Connector/J</title>
+  <title>&title-java-connector;</title>
 
   <para>
     MySQL provides connectivity for client applications developed in the
@@ -20,28 +20,26 @@
   </para>
 
   <para>
-    MySQL Connector/J is a JDBC-3.0 "Type 4" driver, which means that is
-    is pure Java, implements version 3.0 of the JDBC specification, and
-    communicates directly with the MySQL server using the MySQL
-    protocol.
+    MySQL Connector/J is a JDBC-3.0 <quote>Type 4</quote> driver, which
+    means that is is pure Java, implements version 3.0 of the JDBC
+    specification, and communicates directly with the MySQL server using
+    the MySQL protocol.
   </para>
 
   <para>
     This document is arranged for a beginning JDBC developer. If you are
     already experienced with using JDBC, you might consider starting
-    with the section "<link linkend="cj-installing">Installing
-    Connector/J</link>".
+    with the section <xref linkend="cj-installing"/>.
   </para>
 
   <para>
     While JDBC is useful by itself, we would hope that if you are not
     familiar with JDBC that after reading the first few sections of this
-    manual, that you would avoid using "naked" JDBC for all but the most
-    trivial problems and consider using one of the popular persistence
-    frameworks such as
+    manual, that you would avoid using <quote>naked</quote> JDBC for all
+    but the most trivial problems and consider using one of the popular
+    persistence frameworks such as
     <ulink url="http://www.hibernate.org/">Hibernate</ulink>,
-    <ulink
-  url="http://www.springframework.org/">Spring's JDBC
+    <ulink url="http://www.springframework.org/">Spring's JDBC
     templates</ulink> or
     <ulink url="http://www.ibatis.com/common/sqlmaps.html">Ibatis SQL
     Maps</ulink> to do the majority of repetitive work and heavier
@@ -61,17 +59,16 @@
       <para>
         <ulink
       url="http://java.sun.com/docs/books/tutorial/jdbc/basics/index.html">JDBC
-        Basics </ulink>- A tutorial from Sun covering beginner topics in
-        JDBC
+        Basics </ulink> &mdash; A tutorial from Sun covering beginner
+        topics in JDBC
       </para>
     </listitem>
 
     <listitem>
       <para>
-        <ulink
-      url="http://java.sun.com/developer/onlineTraining/Database/JDBCShortCourse/index.html">JDBC
-        Short Course</ulink> - A more in-depth tutorial from Sun and
-        JGuru
+        <ulink url="http://java.sun.com/developer/onlineTraining/Database/JDBCShortCourse/index.html">JDBC
+        Short Course</ulink> &mdash; A more in-depth tutorial from Sun
+        and JGuru
       </para>
     </listitem>
 
@@ -79,7 +76,7 @@
 
   <section id="cj-basic-jdbc">
 
-    <title>Basic JDBC concepts</title>
+    <title>&title-cj-basic-jdbc;</title>
 
     <para>
       This section provides some general JDBC background.
@@ -87,26 +84,30 @@
 
     <section id="cj-connect-with-drivermanager">
 
-      <title>Connecting to MySQL using the DriverManager Interface</title>
+      <title>&title-cj-connect-with-drivermanager;</title>
 
       <para>
         When you are using JDBC outside of an application server, the
-        DriverManager class manages the establishment of Connections.
+        <literal>DriverManager</literal> class manages the establishment
+        of Connections.
       </para>
 
       <para>
-        The DriverManager needs to be told which JDBC drivers it should
-        try to make Connections with. The easiest way to do this is to
-        use Class.forName() on the class that implements the
-        java.sql.Driver interface. With MySQL Connector/J, the name of
-        this class is com.mysql.jdbc.Driver. With this method, you could
-        use an external configuration file to supply the driver class
-        name and driver parameters to use when connecting to a database.
+        The <literal>DriverManager</literal> needs to be told which JDBC
+        drivers it should try to make Connections with. The easiest way
+        to do this is to use <literal>Class.forName()</literal> on the
+        class that implements the <literal>java.sql.Driver</literal>
+        interface. With MySQL Connector/J, the name of this class is
+        <literal>com.mysql.jdbc.Driver</literal>. With this method, you
+        could use an external configuration file to supply the driver
+        class name and driver parameters to use when connecting to a
+        database.
       </para>
 
       <para>
         The following section of Java code shows how you might register
-        MySQL Connector/J from the main() method of your application:
+        MySQL Connector/J from the <literal>main()</literal> method of
+        your application:
       </para>
 
 <programlisting>import java.sql.Connection;
@@ -129,21 +130,24 @@
 }</programlisting>
 
       <para>
-        After the driver has been registered with the DriverManager, you
-        can obtain a Connection instance that is connected to a
-        particular database by calling DriverManager.getConnection():
+        After the driver has been registered with the
+        <literal>DriverManager</literal>, you can obtain a
+        <literal>Connection</literal> instance that is connected to a
+        particular database by calling
+        <literal>DriverManager.getConnection()</literal>:
       </para>
 
       <example>
 
-        <title>Obtaining a Connection From the DriverManager</title>
+        <title>Obtaining a Connection From the <literal>DriverManager</literal></title>
 
         <para>
-          This example shows how you can obtain a Connection instance
-          from the DriverManager. There are a few different signatures
-          for the getConnection() method. You should see the API
-          documentation that comes with your JDK for more specific
-          information on how to use them.
+          This example shows how you can obtain a
+          <literal>Connection</literal> instance from the
+          <literal>DriverManager</literal>. There are a few different
+          signatures for the <literal>getConnection()</literal> method.
+          You should see the API documentation that comes with your JDK
+          for more specific information on how to use them.
         </para>
 
 <programlisting>
@@ -166,9 +170,10 @@
 </programlisting>
 
         <para>
-          Once a Connection is established, it can be used to create
-          Statements and PreparedStatements, as well as retrieve
-          metadata about the database. This is explained in the
+          Once a <literal>Connection</literal> is established, it can be
+          used to create <literal>Statement</literal> and
+          <literal>PreparedStatement</literal> objects, as well as
+          retrieve metadata about the database. This is explained in the
           following sections.
         </para>
 
@@ -178,7 +183,7 @@
 
 <!--
         <section id="cj-connect-with-datasource">
-          <title>Connecting to MySQL using the DataSource Interface</title>
+          <title>&title-cj-connect-with-datasource;;</title>
 
           <para />
         </section>
@@ -197,47 +202,56 @@
       <title>Using Statements to Execute SQL</title>
 
       <para>
-        Statements allow you to execute basic SQL queries and retrieve
-        the results through the ResultSet class which is described
-        later.
+        <literal>Statement</literal> objects allow you to execute basic
+        SQL queries and retrieve the results through the
+        <literal>ResultSet</literal> class which is described later.
       </para>
 
       <para>
-        To create a Statement instance, you call the createStatement()
-        method on the Connection object you have retrieved via one of
-        the DriverManager.getConnection() or DataSource.getConnection()
-        methods described earlier.
+        To create a <literal>Statement</literal> instance, you call the
+        <literal>createStatement()</literal> method on the
+        <literal>Connection</literal> object you have retrieved via one
+        of the <literal>DriverManager.getConnection()</literal> or
+        <literal>DataSource.getConnection()</literal> methods described
+        earlier.
       </para>
 
       <para>
-        Once you have a Statement instance, you can execute a SELECT
-        query by calling the executeQuery(String) method with the SQL
-        you want to use.
+        Once you have a <literal>Statement</literal> instance, you can
+        execute a <literal>SELECT</literal> query by calling the
+        <literal>executeQuery(String)</literal> method with the SQL you
+        want to use.
       </para>
 
       <para>
-        To update data in the database use the executeUpdate(String SQL)
-        method. This method returns the number of rows affected by the
-        update statement.
+        To update data in the database use the
+        <literal>executeUpdate(String SQL)</literal> method. This method
+        returns the number of rows affected by the update statement.
       </para>
 
       <para>
         If you don't know ahead of time whether the SQL statement will
-        be a SELECT or an UPDATE/INSERT, then you can use the
-        execute(String SQL) method. This method will return true if the
-        SQL query was a SELECT, or false if an UPDATE/INSERT/DELETE
-        query. If the query was a SELECT query, you can retrieve the
-        results by calling the getResultSet() method. If the query was
-        an UPDATE/INSERT/DELETE query, you can retrieve the affected
-        rows count by calling getUpdateCount() on the Statement
-        instance.
+        be a <literal>SELECT</literal> or an
+        <literal>UPDATE</literal>/<literal>INSERT</literal>, then you
+        can use the <literal>execute(String SQL)</literal> method. This
+        method will return true if the SQL query was a
+        <literal>SELECT</literal>, or false if it was an
+        <literal>UPDATE</literal>, <literal>INSERT</literal>, or
+        <literal>DELETE</literal> statement. If the statement was a
+        <literal>SELECT</literal> query, you can retrieve the results by
+        calling the <literal>getResultSet()</literal> method. If the
+        statement was an <literal>UPDATE</literal>,
+        <literal>INSERT</literal>, or <literal>DELETE</literal>
+        statement, you can retrieve the affected rows count by calling
+        <literal>getUpdateCount()</literal> on the
+        <literal>Statement</literal> instance.
       </para>
 
       <example>
 
         <title>Using java.sql.Statement to Execute a SELECT Query</title>
 
-<programlisting>// assume conn is an already created JDBC connection
+<programlisting>// assume that conn is an already created JDBC connection
 Statement stmt = null;
 ResultSet rs = null;
 
@@ -302,8 +316,7 @@
 
       <para>
         MySQL's stored procedure syntax is documented in the
-        "<ulink
-      url="http://www.mysql.com/doc/en/Stored_Procedures.html">Stored
+        "<ulink url="http://www.mysql.com/doc/en/stored-procedures.html">Stored
         Procedures and Functions</ulink>" section of the MySQL Reference
         Manual.
       </para>
@@ -887,7 +900,7 @@
 
   <section id="cj-installing">
 
-    <title>Installing Connector/J</title>
+    <title>&title-cj-installing;</title>
 
     <para>
       Use the following instructions to install Connector/J
@@ -895,13 +908,13 @@
 
     <section id="cj-system-requirements">
 
-      <title>Required Software Versions</title>
+      <title>&title-cj-system-requirements;</title>
 
       <para></para>
 
       <section id="cj-supported-java-versions">
 
-        <title>Java Versions Supported</title>
+        <title>&title-cj-supported-java-versions;</title>
 
         <para>
           MySQL Connector/J supports Java-2 JVMs, including JDK-1.2.x,
@@ -963,23 +976,23 @@
         <para>
           MySQL Connector/J is distributed as a .zip or .tar.gz archive
           containing the sources, the class files a class-file only
-          "binary" .jar archive named
+          <quote>binary</quote> .jar archive named
           "<filename>mysql-connector-java-[version]-bin.jar</filename>",
-          and starting with Connector/J 3.1.8 a "debug" build of the
-          driver in a file named
+          and starting with Connector/J 3.1.8 a <quote>debug</quote>
+          build of the driver in a file named
           "<filename>mysql-connector-java-[version]-bin-g.jar</filename>".
         </para>
 
         <para>
           Starting with Connector/J 3.1.9, we don't ship the .class
-          files "unbundled", they are only available in the JAR archives
-          that ship with the driver.
+          files <quote>unbundled</quote>, they are only available in the
+          JAR archives that ship with the driver.
         </para>
 
         <para>
-          You should not use the "debug" build of the driver unless
-          instructed to do so when reporting a problem or bug to MySQL
-          AB, as it is not designed to be run in production
+          You should not use the <quote>debug</quote> build of the
+          driver unless instructed to do so when reporting a problem or
+          bug to MySQL AB, as it is not designed to be run in production
           environments, and will have adverse performance impact when
           used. The debug binary also depends on the Aspect/J runtime
           library, which is located in the
@@ -990,12 +1003,12 @@
         <para>
           You will need to use the appropriate graphical or command-line
           utility to un-archive the distribution (for example, WinZip
-          for the .zip archive, and "tar" for the .tar.gz archive).
-          Because there are potentially long filenames in the
-          distribution, we use the GNU tar archive format. You will need
-          to use GNU tar (or an application that understands the GNU tar
-          archive format) to unpack the .tar.gz variant of the
-          distribution.
+          for the .zip archive, and <command>tar</command> for the
+          .tar.gz archive). Because there are potentially long filenames
+          in the distribution, we use the GNU tar archive format. You
+          will need to use GNU tar (or an application that understands
+          the GNU tar archive format) to unpack the .tar.gz variant of
+          the distribution.
         </para>
 
         <para>
@@ -1228,12 +1241,13 @@
             <para>
               New SQLState Codes - Connector/J 3.1 uses SQL:1999
               SQLState codes returned by the MySQL server (if
-              supported), which are different than the "legacy" X/Open
-              state codes that Connector/J 3.0 uses. If connected to a
-              MySQL server older than MySQL-4.1.0 (the oldest version to
-              return SQLStates as part of the error code), the driver
-              will use a built-in mapping. You can revert to the old
-              mapping by using the following configuration property:
+              supported), which are different than the
+              <quote>legacy</quote> X/Open state codes that Connector/J
+              3.0 uses. If connected to a MySQL server older than
+              MySQL-4.1.0 (the oldest version to return SQLStates as
+              part of the error code), the driver will use a built-in
+              mapping. You can revert to the old mapping by using the
+              following configuration property:
             </para>
 
             <para>
@@ -1259,27 +1273,27 @@
 
           <listitem>
             <para>
-              Starting with Connector/J 3.1.8 a "debug" build of the
-              driver in a file named
+              Starting with Connector/J 3.1.8 a <quote>debug</quote>
+              build of the driver in a file named
               "<filename>mysql-connector-java-[version]-bin-g.jar</filename>"
-              is shipped alongside the normal "binary" jar file that is
-              named
+              is shipped alongside the normal <quote>binary</quote> jar
+              file that is named
               "<filename>mysql-connector-java-[version]-bin.jar</filename>".
             </para>
 
             <para>
               Starting with Connector/J 3.1.9, we don't ship the .class
-              files "unbundled", they are only available in the JAR
-              archives that ship with the driver.
+              files <quote>unbundled</quote>, they are only available in
+              the JAR archives that ship with the driver.
             </para>
 
             <para>
-              You should not use the "debug" build of the driver unless
-              instructed to do so when reporting a problem or bug to
-              MySQL AB, as it is not designed to be run in production
-              environments, and will have adverse performance impact
-              when used. The debug binary also depends on the Aspect/J
-              runtime library, which is located in the
+              You should not use the <quote>debug</quote> build of the
+              driver unless instructed to do so when reporting a problem
+              or bug to MySQL AB, as it is not designed to be run in
+              production environments, and will have adverse performance
+              impact when used. The debug binary also depends on the
+              Aspect/J runtime library, which is located in the
               <filename>src/lib/aspectjrt.jar</filename> file that comes
               with the Connector/J distribution.
             </para>
@@ -1392,12 +1406,12 @@
 
       <para>
         MySQL Connector/J has fail-over support. This allows the driver
-        to fail-over to any number of "slave" hosts and still perform
-        read-only queries. Fail-over only happens when the connection is
-        in an autoCommit(true) state, because fail-over can not happen
-        reliably when a transaction is in progress. Most application
-        servers and connection pools set autoCommit to 'true' at the end
-        of every transaction/connection use.
+        to fail-over to any number of <quote>slave</quote> hosts and
+        still perform read-only queries. Fail-over only happens when the
+        connection is in an autoCommit(true) state, because fail-over
+        can not happen reliably when a transaction is in progress. Most
+        application servers and connection pools set autoCommit to
+        'true' at the end of every transaction/connection use.
       </para>
 
       <para>
@@ -1788,9 +1802,9 @@
             <row>
               <entry>cachePrepStmts</entry>
               <entry>Should the driver cache the parsing stage of PreparedStatements of
-                client-side prepared statements, the "check" for
-                suitability of server-side prepared and server-side
-                prepared statements themselves?</entry>
+                client-side prepared statements, the
+                <quote>check</quote> for suitability of server-side
+                prepared and server-side prepared statements themselves?</entry>
               <entry>No</entry>
               <entry>false</entry>
               <entry>3.0.10</entry>
@@ -2565,12 +2579,13 @@
 
           <para>
             Unlike older versions of MM.MySQL the 'isClosed()' method
-            does not "ping" the server to determine if it is alive. In
-            accordance with the JDBC specification, it only returns true
-            if 'closed()' has been called on the connection. If you need
-            to determine if the connection is still valid, you should
-            issue a simple query, such as "SELECT 1". The driver will
-            throw an exception if the connection is no longer valid.
+            does not <quote>ping</quote> the server to determine if it
+            is alive. In accordance with the JDBC specification, it only
+            returns true if 'closed()' has been called on the
+            connection. If you need to determine if the connection is
+            still valid, you should issue a simple query, such as
+            "SELECT 1". The driver will throw an exception if the
+            connection is no longer valid.
           </para>
         </listitem>
 
@@ -2616,12 +2631,13 @@
 
           <para>
             Take care when using a server-side prepared statement with
-            "large" parameters that are set via setBinaryStream(),
-            setAsciiStream(), setUnicodeStream(), setBlob(), or
-            setClob(). If you want to re-execute the statement with any
-            "large" parameter changed to a non-"large" parameter, it is
-            necessary to call clearParameters() and set all parameters
-            again. The reason for this is as follows:
+            <quote>large</quote> parameters that are set via
+            setBinaryStream(), setAsciiStream(), setUnicodeStream(),
+            setBlob(), or setClob(). If you want to re-execute the
+            statement with any <quote>large</quote> parameter changed to
+            a non-<quote>large</quote> parameter, it is necessary to
+            call clearParameters() and set all parameters again. The
+            reason for this is as follows:
           </para>
 
           <itemizedlist>
@@ -2652,24 +2668,25 @@
 
             <listitem>
               <para>
-                If a parameter changes from "large" to non-"large", the
-                driver must reset the server-side state of the prepared
-                statement to allow the parameter that is being changed
-                to take the place of the prior "large" value. This
-                removes all of the 'large' data that has already been
-                sent to the server, thus requiring the data to be
-                re-sent, via the setBinaryStream(), setAsciiStream(),
-                setUnicodeStream(), setBlob() or setClob() methods.
+                If a parameter changes from <quote>large</quote> to
+                non-<quote>large</quote>, the driver must reset the
+                server-side state of the prepared statement to allow the
+                parameter that is being changed to take the place of the
+                prior <quote>large</quote> value. This removes all of
+                the 'large' data that has already been sent to the
+                server, thus requiring the data to be re-sent, via the
+                setBinaryStream(), setAsciiStream(), setUnicodeStream(),
+                setBlob() or setClob() methods.
               </para>
             </listitem>
 
           </itemizedlist>
 
           <para>
-            Consequently, if you want to change the "type" of a
-            parameter to a non-"large" one, you must call
-            clearParameters() and set all parameters of the prepared
-            statement again before it can be re-executed.
+            Consequently, if you want to change the <quote>type</quote>
+            of a parameter to a non-<quote>large</quote> one, you must
+            call clearParameters() and set all parameters of the
+            prepared statement again before it can be re-executed.
           </para>
         </listitem>
 
@@ -2702,9 +2719,9 @@
           <para>
             The combination of a forward-only, read-only result set,
             with a fetch size of Integer.MIN_VALUE serves as a signal to
-            the driver to "stream" result sets row-by-row. After this
-            any result sets created with the statement will be retrieved
-            row-by-row.
+            the driver to <quote>stream</quote> result sets row-by-row.
+            After this any result sets created with the statement will
+            be retrieved row-by-row.
           </para>
 
           <para>
@@ -2731,10 +2748,10 @@
           </para>
 
           <para>
-            Therefore, if using "streaming" results, you should process
-            them as quickly as possible if you want to maintain
-            concurrent access to the tables referenced by the statement
-            producing the result set.
+            Therefore, if using <quote>streaming</quote> results, you
+            should process them as quickly as possible if you want to
+            maintain concurrent access to the tables referenced by the
+            statement producing the result set.
           </para>
         </listitem>
 
@@ -3496,17 +3513,17 @@
         <function>Connection.setReadOnly(true)</function>, this
         "replication-aware" connection will use one of the slave
         connections, which are load-balanced per-vm using a round-robin
-        scheme (a given connection is "sticky" to a slave unless that
-        slave is removed from service). If you have a write transaction,
-        or if you have a read that is "time-sensitive" (remember,
-        replication in MySQL is asynchronous), set the connection to be
-        not read-only, by calling
+        scheme (a given connection is <quote>sticky</quote> to a slave
+        unless that slave is removed from service). If you have a write
+        transaction, or if you have a read that is "time-sensitive"
+        (remember, replication in MySQL is asynchronous), set the
+        connection to be not read-only, by calling
         <function>Connection.setReadOnly(false)</function> and the
-        driver will ensure that further calls are sent to the "master"
-        MySQL server. The driver takes care of propagating the current
-        state of autocommit, isolation level, and catalog between all of
-        the connections that it uses to accomplish this load balancing
-        functionality.
+        driver will ensure that further calls are sent to the
+        <quote>master</quote> MySQL server. The driver takes care of
+        propagating the current state of autocommit, isolation level,
+        and catalog between all of the connections that it uses to
+        accomplish this load balancing functionality.
       </para>
 
       <para>
@@ -3615,14 +3632,14 @@
         </para>
 
         <para>
-          This technique of "pooling" connections is based on the fact
-          that most applications only need a thread to have access to a
-          JDBC connection when they are actively processing a
-          transaction, which usually take only milliseconds to complete.
-          When not processing a transaction, the connection would
-          otherwise sit idle. Instead, connection pooling allows the
-          idle connection to be used by some other thread to do useful
-          work.
+          This technique of <quote>pooling</quote> connections is based
+          on the fact that most applications only need a thread to have
+          access to a JDBC connection when they are actively processing
+          a transaction, which usually take only milliseconds to
+          complete. When not processing a transaction, the connection
+          would otherwise sit idle. Instead, connection pooling allows
+          the idle connection to be used by some other thread to do
+          useful work.
         </para>
 
         <para>
@@ -4057,10 +4074,10 @@
         that comes with Connector/J to the <filename>lib</filename>
         directory for your server configuration (which is usually called
         "<filename>default</filename>"). Then, in the same configuration
-        directory, in the subdirectory named "deploy", create a
-        datasource configuration file that ends with "-ds.xml", which
-        tells JBoss to deploy this file as a JDBC Datasource. The file
-        should have the following contents:
+        directory, in the subdirectory named <quote>deploy</quote>,
+        create a datasource configuration file that ends with "-ds.xml",
+        which tells JBoss to deploy this file as a JDBC Datasource. The
+        file should have the following contents:
       </para>
 
 <programlisting>&lt;datasources&gt;
@@ -4235,13 +4252,16 @@
             <note>
 
               <para>
-                Testing your connectivity with the "mysql" command-line
-                client will not work unless you add the "--host" flag,
-                and use something other than "localhost" for the host.
-                The "mysql" command-line client will use Unix domain
-                sockets if you use the special hostname "localhost". If
-                you are testing connectivity to "localhost", use
-                "127.0.0.1" as the hostname instead.
+                Testing your connectivity with the
+                <command>mysql</command> command-line client will not
+                work unless you add the <option>--host</option> flag,
+                and use something other than
+                <literal>localhost</literal> for the host. The
+                <command>mysql</command> command-line client will use
+                Unix domain sockets if you use the special hostname
+                <literal>localhost</literal>. If you are testing
+                connectivity to <literal>localhost</literal>, use
+                <literal>127.0.0.1</literal> as the hostname instead.
               </para>
 
             </note>
@@ -4344,15 +4364,15 @@
               option set (the Debian Linux package of MySQL server does
               this for example), you need to comment it out in the file
               /etc/mysql/my.cnf or /etc/my.cnf. Of course your my.cnf
-              file might also exist in the "data" directory of your
-              MySQL server, or anywhere else (depending on how MySQL was
-              compiled for your system). Binaries created by MySQL AB
-              always look in /etc/my.cnf and [datadir]/my.cnf. If your
-              MySQL server has been firewalled, you will need to have
-              the firewall configured to allow TCP/IP connections from
-              the host where your Java code is running to the MySQL
-              server on the port that MySQL is listening to (by default,
-              3306).
+              file might also exist in the <filename>data</filename>
+              directory of your MySQL server, or anywhere else
+              (depending on how MySQL was compiled for your system).
+              Binaries created by MySQL AB always look in /etc/my.cnf
+              and [datadir]/my.cnf. If your MySQL server has been
+              firewalled, you will need to have the firewall configured
+              to allow TCP/IP connections from the host where your Java
+              code is running to the MySQL server on the port that MySQL
+              is listening to (by default, 3306).
             </para>
 
           </answer>

Modified: trunk/refman-5.1/connector-j.xml
===================================================================
--- trunk/refman-5.1/connector-j.xml	2006-01-04 06:25:17 UTC (rev 666)
+++ trunk/refman-5.1/connector-j.xml	2006-01-04 06:54:26 UTC (rev 667)
@@ -11,7 +11,7 @@
 ]>
 <section id="java-connector">
 
-  <title>MySQL Connector/J</title>
+  <title>&title-java-connector;</title>
 
   <para>
     MySQL provides connectivity for client applications developed in the
@@ -20,28 +20,26 @@
   </para>
 
   <para>
-    MySQL Connector/J is a JDBC-3.0 "Type 4" driver, which means that is
-    is pure Java, implements version 3.0 of the JDBC specification, and
-    communicates directly with the MySQL server using the MySQL
-    protocol.
+    MySQL Connector/J is a JDBC-3.0 <quote>Type 4</quote> driver, which
+    means that is is pure Java, implements version 3.0 of the JDBC
+    specification, and communicates directly with the MySQL server using
+    the MySQL protocol.
   </para>
 
   <para>
     This document is arranged for a beginning JDBC developer. If you are
     already experienced with using JDBC, you might consider starting
-    with the section "<link linkend="cj-installing">Installing
-    Connector/J</link>".
+    with the section <xref linkend="cj-installing"/>.
   </para>
 
   <para>
     While JDBC is useful by itself, we would hope that if you are not
     familiar with JDBC that after reading the first few sections of this
-    manual, that you would avoid using "naked" JDBC for all but the most
-    trivial problems and consider using one of the popular persistence
-    frameworks such as
+    manual, that you would avoid using <quote>naked</quote> JDBC for all
+    but the most trivial problems and consider using one of the popular
+    persistence frameworks such as
     <ulink url="http://www.hibernate.org/">Hibernate</ulink>,
-    <ulink
-  url="http://www.springframework.org/">Spring's JDBC
+    <ulink url="http://www.springframework.org/">Spring's JDBC
     templates</ulink> or
     <ulink url="http://www.ibatis.com/common/sqlmaps.html">Ibatis SQL
     Maps</ulink> to do the majority of repetitive work and heavier
@@ -61,17 +59,16 @@
       <para>
         <ulink
       url="http://java.sun.com/docs/books/tutorial/jdbc/basics/index.html">JDBC
-        Basics </ulink>- A tutorial from Sun covering beginner topics in
-        JDBC
+        Basics </ulink> &mdash; A tutorial from Sun covering beginner
+        topics in JDBC
       </para>
     </listitem>
 
     <listitem>
       <para>
-        <ulink
-      url="http://java.sun.com/developer/onlineTraining/Database/JDBCShortCourse/index.html">JDBC
-        Short Course</ulink> - A more in-depth tutorial from Sun and
-        JGuru
+        <ulink url="http://java.sun.com/developer/onlineTraining/Database/JDBCShortCourse/index.html">JDBC
+        Short Course</ulink> &mdash; A more in-depth tutorial from Sun
+        and JGuru
       </para>
     </listitem>
 
@@ -79,7 +76,7 @@
 
   <section id="cj-basic-jdbc">
 
-    <title>Basic JDBC concepts</title>
+    <title>&title-cj-basic-jdbc;</title>
 
     <para>
       This section provides some general JDBC background.
@@ -87,26 +84,30 @@
 
     <section id="cj-connect-with-drivermanager">
 
-      <title>Connecting to MySQL using the DriverManager Interface</title>
+      <title>&title-cj-connect-with-drivermanager;</title>
 
       <para>
         When you are using JDBC outside of an application server, the
-        DriverManager class manages the establishment of Connections.
+        <literal>DriverManager</literal> class manages the establishment
+        of Connections.
       </para>
 
       <para>
-        The DriverManager needs to be told which JDBC drivers it should
-        try to make Connections with. The easiest way to do this is to
-        use Class.forName() on the class that implements the
-        java.sql.Driver interface. With MySQL Connector/J, the name of
-        this class is com.mysql.jdbc.Driver. With this method, you could
-        use an external configuration file to supply the driver class
-        name and driver parameters to use when connecting to a database.
+        The <literal>DriverManager</literal> needs to be told which JDBC
+        drivers it should try to make Connections with. The easiest way
+        to do this is to use <literal>Class.forName()</literal> on the
+        class that implements the <literal>java.sql.Driver</literal>
+        interface. With MySQL Connector/J, the name of this class is
+        <literal>com.mysql.jdbc.Driver</literal>. With this method, you
+        could use an external configuration file to supply the driver
+        class name and driver parameters to use when connecting to a
+        database.
       </para>
 
       <para>
         The following section of Java code shows how you might register
-        MySQL Connector/J from the main() method of your application:
+        MySQL Connector/J from the <literal>main()</literal> method of
+        your application:
       </para>
 
 <programlisting>import java.sql.Connection;
@@ -129,21 +130,24 @@
 }</programlisting>
 
       <para>
-        After the driver has been registered with the DriverManager, you
-        can obtain a Connection instance that is connected to a
-        particular database by calling DriverManager.getConnection():
+        After the driver has been registered with the
+        <literal>DriverManager</literal>, you can obtain a
+        <literal>Connection</literal> instance that is connected to a
+        particular database by calling
+        <literal>DriverManager.getConnection()</literal>:
       </para>
 
       <example>
 
-        <title>Obtaining a Connection From the DriverManager</title>
+        <title>Obtaining a Connection From the <literal>DriverManager</literal></title>
 
         <para>
-          This example shows how you can obtain a Connection instance
-          from the DriverManager. There are a few different signatures
-          for the getConnection() method. You should see the API
-          documentation that comes with your JDK for more specific
-          information on how to use them.
+          This example shows how you can obtain a
+          <literal>Connection</literal> instance from the
+          <literal>DriverManager</literal>. There are a few different
+          signatures for the <literal>getConnection()</literal> method.
+          You should see the API documentation that comes with your JDK
+          for more specific information on how to use them.
         </para>
 
 <programlisting>
@@ -166,9 +170,10 @@
 </programlisting>
 
         <para>
-          Once a Connection is established, it can be used to create
-          Statements and PreparedStatements, as well as retrieve
-          metadata about the database. This is explained in the
+          Once a <literal>Connection</literal> is established, it can be
+          used to create <literal>Statement</literal> and
+          <literal>PreparedStatement</literal> objects, as well as
+          retrieve metadata about the database. This is explained in the
           following sections.
         </para>
 
@@ -178,7 +183,7 @@
 
 <!--
         <section id="cj-connect-with-datasource">
-          <title>Connecting to MySQL using the DataSource Interface</title>
+          <title>&title-cj-connect-with-datasource;;</title>
 
           <para />
         </section>
@@ -197,47 +202,56 @@
       <title>Using Statements to Execute SQL</title>
 
       <para>
-        Statements allow you to execute basic SQL queries and retrieve
-        the results through the ResultSet class which is described
-        later.
+        <literal>Statement</literal> objects allow you to execute basic
+        SQL queries and retrieve the results through the
+        <literal>ResultSet</literal> class which is described later.
       </para>
 
       <para>
-        To create a Statement instance, you call the createStatement()
-        method on the Connection object you have retrieved via one of
-        the DriverManager.getConnection() or DataSource.getConnection()
-        methods described earlier.
+        To create a <literal>Statement</literal> instance, you call the
+        <literal>createStatement()</literal> method on the
+        <literal>Connection</literal> object you have retrieved via one
+        of the <literal>DriverManager.getConnection()</literal> or
+        <literal>DataSource.getConnection()</literal> methods described
+        earlier.
       </para>
 
       <para>
-        Once you have a Statement instance, you can execute a SELECT
-        query by calling the executeQuery(String) method with the SQL
-        you want to use.
+        Once you have a <literal>Statement</literal> instance, you can
+        execute a <literal>SELECT</literal> query by calling the
+        <literal>executeQuery(String)</literal> method with the SQL you
+        want to use.
       </para>
 
       <para>
-        To update data in the database use the executeUpdate(String SQL)
-        method. This method returns the number of rows affected by the
-        update statement.
+        To update data in the database use the
+        <literal>executeUpdate(String SQL)</literal> method. This method
+        returns the number of rows affected by the update statement.
       </para>
 
       <para>
         If you don't know ahead of time whether the SQL statement will
-        be a SELECT or an UPDATE/INSERT, then you can use the
-        execute(String SQL) method. This method will return true if the
-        SQL query was a SELECT, or false if an UPDATE/INSERT/DELETE
-        query. If the query was a SELECT query, you can retrieve the
-        results by calling the getResultSet() method. If the query was
-        an UPDATE/INSERT/DELETE query, you can retrieve the affected
-        rows count by calling getUpdateCount() on the Statement
-        instance.
+        be a <literal>SELECT</literal> or an
+        <literal>UPDATE</literal>/<literal>INSERT</literal>, then you
+        can use the <literal>execute(String SQL)</literal> method. This
+        method will return true if the SQL query was a
+        <literal>SELECT</literal>, or false if it was an
+        <literal>UPDATE</literal>, <literal>INSERT</literal>, or
+        <literal>DELETE</literal> statement. If the statement was a
+        <literal>SELECT</literal> query, you can retrieve the results by
+        calling the <literal>getResultSet()</literal> method. If the
+        statement was an <literal>UPDATE</literal>,
+        <literal>INSERT</literal>, or <literal>DELETE</literal>
+        statement, you can retrieve the affected rows count by calling
+        <literal>getUpdateCount()</literal> on the
+        <literal>Statement</literal> instance.
       </para>
 
       <example>
 
         <title>Using java.sql.Statement to Execute a SELECT Query</title>
 
-<programlisting>// assume conn is an already created JDBC connection
+<programlisting>// assume that conn is an already created JDBC connection
 Statement stmt = null;
 ResultSet rs = null;
 
@@ -302,8 +316,7 @@
 
       <para>
         MySQL's stored procedure syntax is documented in the
-        "<ulink
-      url="http://www.mysql.com/doc/en/Stored_Procedures.html">Stored
+        "<ulink url="http://www.mysql.com/doc/en/stored-procedures.html">Stored
         Procedures and Functions</ulink>" section of the MySQL Reference
         Manual.
       </para>
@@ -887,7 +900,7 @@
 
   <section id="cj-installing">
 
-    <title>Installing Connector/J</title>
+    <title>&title-cj-installing;</title>
 
     <para>
       Use the following instructions to install Connector/J
@@ -895,13 +908,13 @@
 
     <section id="cj-system-requirements">
 
-      <title>Required Software Versions</title>
+      <title>&title-cj-system-requirements;</title>
 
       <para></para>
 
       <section id="cj-supported-java-versions">
 
-        <title>Java Versions Supported</title>
+        <title>&title-cj-supported-java-versions;</title>
 
         <para>
           MySQL Connector/J supports Java-2 JVMs, including JDK-1.2.x,
@@ -963,23 +976,23 @@
         <para>
           MySQL Connector/J is distributed as a .zip or .tar.gz archive
           containing the sources, the class files a class-file only
-          "binary" .jar archive named
+          <quote>binary</quote> .jar archive named
           "<filename>mysql-connector-java-[version]-bin.jar</filename>",
-          and starting with Connector/J 3.1.8 a "debug" build of the
-          driver in a file named
+          and starting with Connector/J 3.1.8 a <quote>debug</quote>
+          build of the driver in a file named
           "<filename>mysql-connector-java-[version]-bin-g.jar</filename>".
         </para>
 
         <para>
           Starting with Connector/J 3.1.9, we don't ship the .class
-          files "unbundled", they are only available in the JAR archives
-          that ship with the driver.
+          files <quote>unbundled</quote>, they are only available in the
+          JAR archives that ship with the driver.
         </para>
 
         <para>
-          You should not use the "debug" build of the driver unless
-          instructed to do so when reporting a problem or bug to MySQL
-          AB, as it is not designed to be run in production
+          You should not use the <quote>debug</quote> build of the
+          driver unless instructed to do so when reporting a problem or
+          bug to MySQL AB, as it is not designed to be run in production
           environments, and will have adverse performance impact when
           used. The debug binary also depends on the Aspect/J runtime
           library, which is located in the
@@ -990,12 +1003,12 @@
         <para>
           You will need to use the appropriate graphical or command-line
           utility to un-archive the distribution (for example, WinZip
-          for the .zip archive, and "tar" for the .tar.gz archive).
-          Because there are potentially long filenames in the
-          distribution, we use the GNU tar archive format. You will need
-          to use GNU tar (or an application that understands the GNU tar
-          archive format) to unpack the .tar.gz variant of the
-          distribution.
+          for the .zip archive, and <command>tar</command> for the
+          .tar.gz archive). Because there are potentially long filenames
+          in the distribution, we use the GNU tar archive format. You
+          will need to use GNU tar (or an application that understands
+          the GNU tar archive format) to unpack the .tar.gz variant of
+          the distribution.
         </para>
 
         <para>
@@ -1228,12 +1241,13 @@
             <para>
               New SQLState Codes - Connector/J 3.1 uses SQL:1999
               SQLState codes returned by the MySQL server (if
-              supported), which are different than the "legacy" X/Open
-              state codes that Connector/J 3.0 uses. If connected to a
-              MySQL server older than MySQL-4.1.0 (the oldest version to
-              return SQLStates as part of the error code), the driver
-              will use a built-in mapping. You can revert to the old
-              mapping by using the following configuration property:
+              supported), which are different than the
+              <quote>legacy</quote> X/Open state codes that Connector/J
+              3.0 uses. If connected to a MySQL server older than
+              MySQL-4.1.0 (the oldest version to return SQLStates as
+              part of the error code), the driver will use a built-in
+              mapping. You can revert to the old mapping by using the
+              following configuration property:
             </para>
 
             <para>
@@ -1259,27 +1273,27 @@
 
           <listitem>
             <para>
-              Starting with Connector/J 3.1.8 a "debug" build of the
-              driver in a file named
+              Starting with Connector/J 3.1.8 a <quote>debug</quote>
+              build of the driver in a file named
               "<filename>mysql-connector-java-[version]-bin-g.jar</filename>"
-              is shipped alongside the normal "binary" jar file that is
-              named
+              is shipped alongside the normal <quote>binary</quote> jar
+              file that is named
               "<filename>mysql-connector-java-[version]-bin.jar</filename>".
             </para>
 
             <para>
               Starting with Connector/J 3.1.9, we don't ship the .class
-              files "unbundled", they are only available in the JAR
-              archives that ship with the driver.
+              files <quote>unbundled</quote>, they are only available in
+              the JAR archives that ship with the driver.
             </para>
 
             <para>
-              You should not use the "debug" build of the driver unless
-              instructed to do so when reporting a problem or bug to
-              MySQL AB, as it is not designed to be run in production
-              environments, and will have adverse performance impact
-              when used. The debug binary also depends on the Aspect/J
-              runtime library, which is located in the
+              You should not use the <quote>debug</quote> build of the
+              driver unless instructed to do so when reporting a problem
+              or bug to MySQL AB, as it is not designed to be run in
+              production environments, and will have adverse performance
+              impact when used. The debug binary also depends on the
+              Aspect/J runtime library, which is located in the
               <filename>src/lib/aspectjrt.jar</filename> file that comes
               with the Connector/J distribution.
             </para>
@@ -1392,12 +1406,12 @@
 
       <para>
         MySQL Connector/J has fail-over support. This allows the driver
-        to fail-over to any number of "slave" hosts and still perform
-        read-only queries. Fail-over only happens when the connection is
-        in an autoCommit(true) state, because fail-over can not happen
-        reliably when a transaction is in progress. Most application
-        servers and connection pools set autoCommit to 'true' at the end
-        of every transaction/connection use.
+        to fail-over to any number of <quote>slave</quote> hosts and
+        still perform read-only queries. Fail-over only happens when the
+        connection is in an autoCommit(true) state, because fail-over
+        can not happen reliably when a transaction is in progress. Most
+        application servers and connection pools set autoCommit to
+        'true' at the end of every transaction/connection use.
       </para>
 
       <para>
@@ -1788,9 +1802,9 @@
             <row>
               <entry>cachePrepStmts</entry>
               <entry>Should the driver cache the parsing stage of PreparedStatements of
-                client-side prepared statements, the "check" for
-                suitability of server-side prepared and server-side
-                prepared statements themselves?</entry>
+                client-side prepared statements, the
+                <quote>check</quote> for suitability of server-side
+                prepared and server-side prepared statements themselves?</entry>
               <entry>No</entry>
               <entry>false</entry>
               <entry>3.0.10</entry>
@@ -2565,12 +2579,13 @@
 
           <para>
             Unlike older versions of MM.MySQL the 'isClosed()' method
-            does not "ping" the server to determine if it is alive. In
-            accordance with the JDBC specification, it only returns true
-            if 'closed()' has been called on the connection. If you need
-            to determine if the connection is still valid, you should
-            issue a simple query, such as "SELECT 1". The driver will
-            throw an exception if the connection is no longer valid.
+            does not <quote>ping</quote> the server to determine if it
+            is alive. In accordance with the JDBC specification, it only
+            returns true if 'closed()' has been called on the
+            connection. If you need to determine if the connection is
+            still valid, you should issue a simple query, such as
+            "SELECT 1". The driver will throw an exception if the
+            connection is no longer valid.
           </para>
         </listitem>
 
@@ -2616,12 +2631,13 @@
 
           <para>
             Take care when using a server-side prepared statement with
-            "large" parameters that are set via setBinaryStream(),
-            setAsciiStream(), setUnicodeStream(), setBlob(), or
-            setClob(). If you want to re-execute the statement with any
-            "large" parameter changed to a non-"large" parameter, it is
-            necessary to call clearParameters() and set all parameters
-            again. The reason for this is as follows:
+            <quote>large</quote> parameters that are set via
+            setBinaryStream(), setAsciiStream(), setUnicodeStream(),
+            setBlob(), or setClob(). If you want to re-execute the
+            statement with any <quote>large</quote> parameter changed to
+            a non-<quote>large</quote> parameter, it is necessary to
+            call clearParameters() and set all parameters again. The
+            reason for this is as follows:
           </para>
 
           <itemizedlist>
@@ -2652,24 +2668,25 @@
 
             <listitem>
               <para>
-                If a parameter changes from "large" to non-"large", the
-                driver must reset the server-side state of the prepared
-                statement to allow the parameter that is being changed
-                to take the place of the prior "large" value. This
-                removes all of the 'large' data that has already been
-                sent to the server, thus requiring the data to be
-                re-sent, via the setBinaryStream(), setAsciiStream(),
-                setUnicodeStream(), setBlob() or setClob() methods.
+                If a parameter changes from <quote>large</quote> to
+                non-<quote>large</quote>, the driver must reset the
+                server-side state of the prepared statement to allow the
+                parameter that is being changed to take the place of the
+                prior <quote>large</quote> value. This removes all of
+                the 'large' data that has already been sent to the
+                server, thus requiring the data to be re-sent, via the
+                setBinaryStream(), setAsciiStream(), setUnicodeStream(),
+                setBlob() or setClob() methods.
               </para>
             </listitem>
 
           </itemizedlist>
 
           <para>
-            Consequently, if you want to change the "type" of a
-            parameter to a non-"large" one, you must call
-            clearParameters() and set all parameters of the prepared
-            statement again before it can be re-executed.
+            Consequently, if you want to change the <quote>type</quote>
+            of a parameter to a non-<quote>large</quote> one, you must
+            call clearParameters() and set all parameters of the
+            prepared statement again before it can be re-executed.
           </para>
         </listitem>
 
@@ -2702,9 +2719,9 @@
           <para>
             The combination of a forward-only, read-only result set,
             with a fetch size of Integer.MIN_VALUE serves as a signal to
-            the driver to "stream" result sets row-by-row. After this
-            any result sets created with the statement will be retrieved
-            row-by-row.
+            the driver to <quote>stream</quote> result sets row-by-row.
+            After this any result sets created with the statement will
+            be retrieved row-by-row.
           </para>
 
           <para>
@@ -2731,10 +2748,10 @@
           </para>
 
           <para>
-            Therefore, if using "streaming" results, you should process
-            them as quickly as possible if you want to maintain
-            concurrent access to the tables referenced by the statement
-            producing the result set.
+            Therefore, if using <quote>streaming</quote> results, you
+            should process them as quickly as possible if you want to
+            maintain concurrent access to the tables referenced by the
+            statement producing the result set.
           </para>
         </listitem>
 
@@ -3496,17 +3513,17 @@
         <function>Connection.setReadOnly(true)</function>, this
         "replication-aware" connection will use one of the slave
         connections, which are load-balanced per-vm using a round-robin
-        scheme (a given connection is "sticky" to a slave unless that
-        slave is removed from service). If you have a write transaction,
-        or if you have a read that is "time-sensitive" (remember,
-        replication in MySQL is asynchronous), set the connection to be
-        not read-only, by calling
+        scheme (a given connection is <quote>sticky</quote> to a slave
+        unless that slave is removed from service). If you have a write
+        transaction, or if you have a read that is "time-sensitive"
+        (remember, replication in MySQL is asynchronous), set the
+        connection to be not read-only, by calling
         <function>Connection.setReadOnly(false)</function> and the
-        driver will ensure that further calls are sent to the "master"
-        MySQL server. The driver takes care of propagating the current
-        state of autocommit, isolation level, and catalog between all of
-        the connections that it uses to accomplish this load balancing
-        functionality.
+        driver will ensure that further calls are sent to the
+        <quote>master</quote> MySQL server. The driver takes care of
+        propagating the current state of autocommit, isolation level,
+        and catalog between all of the connections that it uses to
+        accomplish this load balancing functionality.
       </para>
 
       <para>
@@ -3615,14 +3632,14 @@
         </para>
 
         <para>
-          This technique of "pooling" connections is based on the fact
-          that most applications only need a thread to have access to a
-          JDBC connection when they are actively processing a
-          transaction, which usually take only milliseconds to complete.
-          When not processing a transaction, the connection would
-          otherwise sit idle. Instead, connection pooling allows the
-          idle connection to be used by some other thread to do useful
-          work.
+          This technique of <quote>pooling</quote> connections is based
+          on the fact that most applications only need a thread to have
+          access to a JDBC connection when they are actively processing
+          a transaction, which usually take only milliseconds to
+          complete. When not processing a transaction, the connection
+          would otherwise sit idle. Instead, connection pooling allows
+          the idle connection to be used by some other thread to do
+          useful work.
         </para>
 
         <para>
@@ -4057,10 +4074,10 @@
         that comes with Connector/J to the <filename>lib</filename>
         directory for your server configuration (which is usually called
         "<filename>default</filename>"). Then, in the same configuration
-        directory, in the subdirectory named "deploy", create a
-        datasource configuration file that ends with "-ds.xml", which
-        tells JBoss to deploy this file as a JDBC Datasource. The file
-        should have the following contents:
+        directory, in the subdirectory named <quote>deploy</quote>,
+        create a datasource configuration file that ends with "-ds.xml",
+        which tells JBoss to deploy this file as a JDBC Datasource. The
+        file should have the following contents:
       </para>
 
 <programlisting>&lt;datasources&gt;
@@ -4235,13 +4252,16 @@
             <note>
 
               <para>
-                Testing your connectivity with the "mysql" command-line
-                client will not work unless you add the "--host" flag,
-                and use something other than "localhost" for the host.
-                The "mysql" command-line client will use Unix domain
-                sockets if you use the special hostname "localhost". If
-                you are testing connectivity to "localhost", use
-                "127.0.0.1" as the hostname instead.
+                Testing your connectivity with the
+                <command>mysql</command> command-line client will not
+                work unless you add the <option>--host</option> flag,
+                and use something other than
+                <literal>localhost</literal> for the host. The
+                <command>mysql</command> command-line client will use
+                Unix domain sockets if you use the special hostname
+                <literal>localhost</literal>. If you are testing
+                connectivity to <literal>localhost</literal>, use
+                <literal>127.0.0.1</literal> as the hostname instead.
               </para>
 
             </note>
@@ -4344,15 +4364,15 @@
               option set (the Debian Linux package of MySQL server does
               this for example), you need to comment it out in the file
               /etc/mysql/my.cnf or /etc/my.cnf. Of course your my.cnf
-              file might also exist in the "data" directory of your
-              MySQL server, or anywhere else (depending on how MySQL was
-              compiled for your system). Binaries created by MySQL AB
-              always look in /etc/my.cnf and [datadir]/my.cnf. If your
-              MySQL server has been firewalled, you will need to have
-              the firewall configured to allow TCP/IP connections from
-              the host where your Java code is running to the MySQL
-              server on the port that MySQL is listening to (by default,
-              3306).
+              file might also exist in the <filename>data</filename>
+              directory of your MySQL server, or anywhere else
+              (depending on how MySQL was compiled for your system).
+              Binaries created by MySQL AB always look in /etc/my.cnf
+              and [datadir]/my.cnf. If your MySQL server has been
+              firewalled, you will need to have the firewall configured
+              to allow TCP/IP connections from the host where your Java
+              code is running to the MySQL server on the port that MySQL
+              is listening to (by default, 3306).
             </para>
 
           </answer>

Modified: trunk/refman-common/titles.en.ent
===================================================================
--- trunk/refman-common/titles.en.ent	2006-01-04 06:25:17 UTC (rev 666)
+++ trunk/refman-common/titles.en.ent	2006-01-04 06:54:26 UTC (rev 667)
@@ -176,8 +176,8 @@
 <!ENTITY title-cj-character-sets "Using Character Sets and Unicode">
 <!ENTITY title-cj-classpath "Installing the Driver and Configuring the CLASSPATH">
 <!ENTITY title-cj-configuration-properties "Driver/Datasource Class Names, URL Syntax and Configuration Properties for Connector/J">
-<!ENTITY title-cj-connect-with-datasource "Connecting to MySQL using the DataSource Interface">
-<!ENTITY title-cj-connect-with-drivermanager "Connecting to MySQL using the DriverManager Interface">
+<!ENTITY title-cj-connect-with-datasource "Connecting to MySQL using the <literal>DataSource</literal> Interface">
+<!ENTITY title-cj-connect-with-drivermanager "Connecting to MySQL using the <literal>DriverManager</literal> Interface">
 <!ENTITY title-cj-connection-pooling "Understanding Connection Pooling">
 <!ENTITY title-cj-controlling-transactions "Controlling transactions">
 <!ENTITY title-cj-faq "Common Problems and Solutions">

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