From: shinz
Date: November 3 2005 5:04pm
Subject: svn commit - mysqldoc@docsrva: r234 - branches/MikePluggable/trunk/refman-5.1
List-Archive: http://lists.mysql.com/internals/31895
Message-Id: <200511031704.jA3H4OJJ003827@docsrva.mysql.com>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Author: shinz
Date: 2005-11-03 18:04:24 +0100 (Thu, 03 Nov 2005)
New Revision: 234

Log:
Proofreading up to line 380

Modified:
   branches/MikePluggable/trunk/refman-5.1/custom-engine.xml

Modified: branches/MikePluggable/trunk/refman-5.1/custom-engine.xml
===================================================================
--- branches/MikePluggable/trunk/refman-5.1/custom-engine.xml	2005-11-03 16:05:34 UTC (rev 233)
+++ branches/MikePluggable/trunk/refman-5.1/custom-engine.xml	2005-11-03 17:04:24 UTC (rev 234)
@@ -46,7 +46,7 @@
     <title>Overview</title>
 
     <para>
-      The MySQL server is build in a modular fashion:
+      The MySQL server is built in a modular fashion:
     </para>
 
     <figure>
@@ -80,7 +80,7 @@
     </para>
 
     <para>
-      One a handler instance is created, the MySQL server issues
+      Once a handler instance is created, the MySQL server issues
       commands to the handler to perform data storage and retrieval
       tasks such as opening a table, manipulating rows, and managing
       indexes.
@@ -88,10 +88,10 @@
 
     <para>
       Custom storage engines can be built in a progressive manner:
-      developers can start with read-only storage engine and later add
+      Developers can start with a read-only storage engine and later add
       support for <literal>INSERT</literal>, <literal>UPDATE</literal>,
-      and <literal>DELETE</literal> operations and later add support for
-      indexing, transactions, and other advanced operations.
+      and <literal>DELETE</literal> operations, and even later add 
+      support for indexing, transactions, and other advanced operations.
     </para>
 
   </section>
@@ -115,11 +115,14 @@
       <filename>ha_example.h</filename> files can be found in the
       <filename>sql/examples/</filename> directory of the MySQL 5.1
       source tree.
+      For instructions how to obtain the 5.1 source tree, see
+      <xref linkend="installing-source-tree"/>.
     </para>
 
     <para>
-      When copying the files, change the names from ha_example to
-      something appropriate to your storage engine such as
+      When copying the files, change the names from 
+      <literal>ha_example.cc</literal> and <literal>ha_example.h</literal>
+      to something appropriate to your storage engine, such as
       <filename>ha_foo.cc</filename> and <filename>ha_foo.h</filename>.
     </para>
 
@@ -136,21 +139,16 @@
 sed s/EXAMPLE/FOO/g ha_example.cc | sed s/example/foo/g ha_foo.cc
 </programlisting>
 
-    <para>
-      For information on accessing the MySQL 5.1 bitkeeper tree, see
-      <xref linkend="installing-source"/>.
-    </para>
-
   </section>
 
   <section id="custom-engine-handlerton">
 
-    <title>Creating the handlerton</title>
+    <title>Creating the <literal>handlerton</literal></title>
 
     <para>
-      The <literal>handlerton</literal> (short for 'handler singleton')
+      The <literal>handlerton</literal> (short for <quote>handler singleton</quote>)
       defines the storage engine and contains function pointers to those
-      functions that apply to the storage engine as a whole as opposed
+      functions that apply to the storage engine as a whole, as opposed
       to functions that work inside a single handler instance. Some
       examples of such functions include transaction functions to handle
       commits and rollbacks.
@@ -197,7 +195,7 @@
 </programlisting>
 
     <para>
-      This is the definition of the handlerton from
+      This is the definition of the <literal>handlerton</literal> from
       <filename>handler.h</filename>:
     </para>
 
@@ -239,20 +237,23 @@
 </programlisting>
 
     <para>
-      The first element in the handlerton is the name of the storage
+      The first element in the <literal>handlerton</literal> is the 
+      name of the storage
       engine. This is the name that will be used when creating tables
       (<literal>CREATE TABLE ... ENGINE =
       <replaceable>FOO</replaceable>;</literal>).
     </para>
 
     <para>
-      The second element in the handlerton determines whether the
+      The second element in the <literal>handlerton</literal> 
+      determines whether or not the
       storage engine will be listed when using the <literal>SHOW STORAGE
       ENGINES</literal> command.
     </para>
 
     <para>
-      The third element in the handlerton is the storage engine comment,
+      The third element in the <literal>handlerton</literal> is 
+      the storage engine comment,
       a description of the storage engine displayed when using the
       <literal>SHOW STORAGE ENGINES</literal> command.
     </para>
@@ -264,29 +265,35 @@
     </remark>
 
     <para>
-      The fourth element in the handlerton is an integer that uniquely
+      The fourth element in the <literal>handlerton</literal> is 
+      an integer that uniquely
       identifies the storage engine within the MySQL server. The
-      constants used by the build-in storage engines are defined in the
+      constants used by the built-in storage engines are defined in the
       <filename>handler.h</filename> file. As an alternative to creating
       a constant you can use an integer that is greater than 25.
+      <remark>[SH] Why 25?</remark>
     </para>
 
     <para>
-      The remaining sections of the handlerton are only implemented if
+      The remaining sections of the <literal>handlerton</literal> 
+      are only implemented if
       the functionality referred to is supported by a given storage
       engine.
     </para>
 
     <para>
-      The fifth element in the handlerton is a function pointer to the
+      The fifth element in the <literal>handlerton</literal> is 
+      a function pointer to the
       storage engine initializer. This function is only called once when
       the server starts to allow the storage engine class to perform any
       housekeeping that is necessary before handlers are instanced.
     </para>
 
     <para>
-      The sixth element in the handlerton is the slot. Each storage
-      engine has it's own memory area (actually a pointer) in the thd,
+      The sixth element in the <literal>handlerton</literal> is 
+      the slot. Each storage
+      engine has its own memory area (actually a pointer) in the 
+      <literal>thd</literal><remark>[SH] Short explanation of thd would be nice-to-have here</remark>,
       for storing per-connection information. It is accessed as
       <literal>thd->ha_data[<replaceable>foo</replaceable>_hton.slot]</literal>.
       The slot number is initialized by MySQL after
@@ -295,9 +302,11 @@
     </para>
 
     <para>
-      The seventh element in the handlerton is the savepoint offset. To
+      The seventh element in the <literal>handlerton</literal> is 
+      the savepoint offset. To
       store per-savepoint data the storage engine is provided with an
-      area of a requested size (0 is ok here).
+      area of a requested size (0 is okay here).
+      <remark>[SH] Loose language. Rather than "okay here" I'd prefer "In most cases, 0 can be used, which means 'no offset'."</remark>
     </para>
 
     <para>
@@ -305,12 +314,14 @@
       the needed memory to store per-savepoint information. After
       <literal><replaceable>foo</replaceable>_init</literal> it is
       changed to be an offset to the savepoint storage area and need not
-      be used by storage engine.
+      be used by the storage engine.
     </para>
 
     <para>
-      The eighth element in the handlerton is a function pointer to the
-      handler's close connection function. This is used by the NDB
+      The eighth element in the <literal>handlerton</literal> is a 
+      function pointer to the
+      handler's <literal>close connection</literal><remark>[SH] close_connection() ?</remark> function. 
+      This is used by the NDB
       storage engine to manage connections between the SQL nodes and the
       storage nodes and should not be needed for most storage engines.
       This function is only called if the slot is set to a non-zero
@@ -318,36 +329,49 @@
     </para>
 
     <para>
-      The ninth element in the handlerton points to an uninitialized
+      The ninth element in the <literal>handlerton</literal> points 
+      to an uninitialized
       storage area of requested size (see the savepoint offset
-      description)
+      description, seventh element).
     </para>
 
     <para>
-      The tenth element in the handlerton is a function pointer to the
-      handler's rollback to savepoint function. This is used to return
-      to a savepoint during a transaction. This is only populated for
+      The tenth element in the <literal>handlerton</literal> is a 
+      function pointer to the
+      handler's 
+      <literal>rollback to savepoint</literal>
+      <remark>[SH] rollback_to_savepoint() ?</remark>
+      function. This is used to return
+      to a savepoint during a transaction. It's only populated for
       storage engines that support savepoints.
     </para>
 
     <para>
-      The eleventh element in the handlerton is a function pointer to
-      the handler's release savepoint function. This is used to release
-      the resources of a savepoint during a transaction. This is only
+      The eleventh element in the <literal>handlerton</literal> is 
+      a function pointer to
+      the handler's 
+      <literal>release savepoint</literal>
+      <remark>[SH] release_savepoint() ?</remark>
+      function. This is used to release
+      the resources of a savepoint during a transaction. It's only
       populated for storage engines that support savepoints.
     </para>
 
     <para>
-      The twelfth element in the handlerton is a function pointer to the
-      handler's commit function. This is used to commit a transaction.
-      This is only populated for storage engines that support
+      The twelfth element in the <literal>handlerton</literal> is 
+      a function pointer to the
+      handler's <literal>commit</literal> function. 
+      This is used to commit a transaction.
+      It's only populated for storage engines that support
       transactions.
     </para>
 
     <para>
-      The thirteenth element in the handlerton is a function pointer to
-      the handler's rollback function. This is used to roll back a
-      transaction. This is only populated for storage engines that
+      The thirteenth element in the <literal>handlerton</literal> is 
+      a function pointer to
+      the handler's <literal>rollback</literal> function. 
+      This is used to roll back a
+      transaction. It's only populated for storage engines that
       support transactions.
     </para>
 
@@ -570,6 +594,11 @@
   <section id="custom-engine-open-table">
     <title>Opening a Table</title>
     
+    <para>
+      <remark>
+        [SH] Add description about opening a table.
+      </remark>
+    </para>
     
   </section>
   
@@ -607,18 +636,26 @@
 
   <section id="custom-engine-delete">
 
-    <title>Adding Support for DELETE to a Storage Engine</title>
+    <title>Adding Support for UPDATE to a Storage Engine</title>
 
-    <para/>
-
+    <para>
+      <remark>
+        [SH] Add description about updating a table.
+      </remark>
+    </para>
+    
   </section>
 
   <section id="custom-engine-update">
 
     <title>Adding Support for DELETE to a Storage Engine</title>
 
-    <para/>
-
+    <para>
+      <remark>
+        [SH] Add description about deleting from a table.
+      </remark>
+    </para>
+    
   </section>
 
   <section id="custom-engine-api-reference">