List:Commits« Previous MessageNext Message »
From:paul Date:January 19 2006 3:38pm
Subject:svn commit - mysqldoc@docsrva: r930 - in trunk: . refman-4.1 refman-5.0 refman-5.1 refman-common
View as plain text  
Author: paul
Date: 2006-01-19 16:38:54 +0100 (Thu, 19 Jan 2006)
New Revision: 930

Log:
 r6429@frost:  paul | 2006-01-19 09:37:13 -0600
 General revisions.


Modified:
   trunk/
   trunk/refman-4.1/renamed-nodes.txt
   trunk/refman-4.1/spatial-extensions.xml
   trunk/refman-5.0/renamed-nodes.txt
   trunk/refman-5.0/spatial-extensions.xml
   trunk/refman-5.1/renamed-nodes.txt
   trunk/refman-5.1/spatial-extensions.xml
   trunk/refman-common/titles.en.ent


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

Modified: trunk/refman-4.1/renamed-nodes.txt
===================================================================
--- trunk/refman-4.1/renamed-nodes.txt	2006-01-19 15:38:42 UTC (rev 929)
+++ trunk/refman-4.1/renamed-nodes.txt	2006-01-19 15:38:54 UTC (rev 930)
@@ -101,3 +101,7 @@
 charset-config-file adding-character-set
 open-tables table-cache
 variables user-variables
+fetching-spatial-data-in-internal-format fetching-spatial-data
+fetching-spatial-data-in-wkb-format fetching-spatial-data
+fetching-spatial-data-in-wkt-format fetching-spatial-data
+gis-features-that-are-not-yet-implemented mysql-gis-conformance-and-compatibility

Modified: trunk/refman-4.1/spatial-extensions.xml
===================================================================
--- trunk/refman-4.1/spatial-extensions.xml	2006-01-19 15:38:42 UTC (rev 929)
+++ trunk/refman-4.1/spatial-extensions.xml	2006-01-19 15:38:54 UTC (rev 930)
@@ -65,11 +65,32 @@
   </itemizedlist>
 
   <para>
-    If you have questions or concerns about the use of the spatial
-    extensions to MySQL, you can discuss these in the GIS forum:
-    <ulink url="&base-url-forum-list;?23"/>.
+    <emphasis role="bold">Additional resources</emphasis>
   </para>
 
+  <itemizedlist>
+
+    <listitem>
+      <para>
+        The Open Geospatial Consortium publishes the
+        <citetitle>OpenGIS&reg; Simple Features Specifications For
+        SQL</citetitle>, a document that proposes several conceptual
+        ways for extending an SQL RDBMS to support spatial data. This
+        specification is available from the OGC Web site at
+        <ulink url="http://www.opengis.org/docs/99-049.pdf"/>.
+      </para>
+    </listitem>
+
+    <listitem>
+      <para>
+        If you have questions or concerns about the use of the spatial
+        extensions to MySQL, you can discuss them in the GIS forum:
+        <ulink url="&base-url-forum-list;?23"/>.
+      </para>
+    </listitem>
+
+  </itemizedlist>
+
   <section id="gis-introduction">
 
     <title>&title-gis-introduction;</title>
@@ -88,20 +109,20 @@
 
     <para>
       MySQL implements spatial extensions following the specification of
-      the <literal>Open GIS Consortium</literal> (OGC). This is an
-      international consortium of more than 250 companies, agencies, and
-      universities participating in the development of publicly
-      available conceptual solutions that can be useful with all kinds
-      of applications that manage spatial data. The OGC maintains a Web
-      site at <ulink url="http://www.opengis.org/"/>.
+      the Open Geospatial Consortium (OGC). This is an international
+      consortium of more than 250 companies, agencies, and universities
+      participating in the development of publicly available conceptual
+      solutions that can be useful with all kinds of applications that
+      manage spatial data. The OGC maintains a Web site at
+      <ulink url="http://www.opengis.org/"/>.
     </para>
 
     <para>
-      In 1997, the Open GIS Consortium published the
+      In 1997, the Open Geospatial Consortium published the
       <citetitle>OpenGIS&reg; Simple Features Specifications For
       SQL</citetitle>, a document that proposes several conceptual ways
       for extending an SQL RDBMS to support spatial data. This
-      specification is available from the Open GIS Web site at
+      specification is available from the OGC Web site at
       <ulink url="http://www.opengis.org/docs/99-049.pdf"/>. It contains
       additional information relevant to this chapter.
     </para>
@@ -111,7 +132,7 @@
       Geometry Types</emphasis> environment proposed by OGC. This term
       refers to an SQL environment that has been extended with a set of
       geometry types. A geometry-valued SQL column is implemented as a
-      column that has a geometry type. The specifications describe a set
+      column that has a geometry type. The specification describe a set
       of SQL geometry types, as well as functions on those types to
       create and analyze geometry values.
     </para>
@@ -153,9 +174,8 @@
     </indexterm>
 
     <para>
-      You can also find documents that use the term
-      <emphasis role="bold">geospatial feature</emphasis> to refer to
-      geographic features.
+      Some documents use the term <emphasis role="bold">geospatial
+      feature</emphasis> to refer to geographic features.
     </para>
 
     <indexterm>
@@ -175,16 +195,12 @@
       <emphasis role="bold">geographic feature</emphasis>,
       <emphasis role="bold">geospatial feature</emphasis>,
       <emphasis role="bold">feature</emphasis>, or
-      <emphasis role="bold">geometry</emphasis>. The term most commonly
-      used here is <emphasis role="bold">geometry</emphasis>.
+      <emphasis role="bold">geometry</emphasis>. Here, the term most
+      commonly used is <emphasis role="bold">geometry</emphasis>,
+      defined as <emphasis>a point or an aggregate of points
+      representing anything in the world that has a location</emphasis>.
     </para>
 
-    <para>
-      Let's define a <emphasis role="bold">geometry</emphasis> as
-      <emphasis>a point or an aggregate of points representing anything
-      in the world that has a location</emphasis>.
-    </para>
-
   </section>
 
   <section id="opengis-geometry-model">
@@ -354,7 +370,7 @@
       <remark role="help-description-begin"/>
 
       <para>
-        <literal>Geometry</literal> is the base class. It's an abstract
+        <literal>Geometry</literal> is the base class. It is an abstract
         class. The instantiable subclasses of
         <literal>Geometry</literal> are restricted to zero-, one-, and
         two-dimensional geometric objects that exist in two-dimensional
@@ -445,8 +461,8 @@
         It is a non-instantiable class but has a number of properties
         that are common to all geometry values created from any of the
         <literal>Geometry</literal> subclasses. These properties are
-        described in the following list. (Particular subclasses have
-        their own specific properties, described later.)
+        described in the following list. Particular subclasses have
+        their own specific properties, described later.
       </para>
 
       <para>
@@ -1408,7 +1424,7 @@
       </remark>
 
       <para>
-        Examples of WKT representations of geometry objects are:
+        Examples of WKT representations of geometry objects:
       </para>
 
       <itemizedlist>
@@ -1514,7 +1530,7 @@
 
       <para>
         A Backus-Naur grammar that specifies the formal production rules
-        for writing WKT values can be found in the OGC specification
+        for writing WKT values can be found in the OpenGIS specification
         document referenced near the beginning of this chapter.
       </para>
 
@@ -1534,8 +1550,8 @@
 
       <para>
         The Well-Known Binary (WKB) representation for geometric values
-        is defined by the OpenGIS specifications. It is also defined in
-        the ISO <quote>SQL/MM Part 3: Spatial</quote> standard.
+        is defined by the OpenGIS specification. It is also defined in
+        the ISO <citetitle>SQL/MM Part 3: Spatial</citetitle> standard.
       </para>
 
       <para>
@@ -1749,8 +1765,8 @@
 
       <para>
         <literal>GEOMETRY</literal> can store geometry values of any
-        type. The other single-value types, <literal>POINT</literal> and
-        <literal>LINESTRING</literal> and <literal>POLYGON</literal>,
+        type. The other single-value types (<literal>POINT</literal>,
+        <literal>LINESTRING</literal>, and <literal>POLYGON</literal>)
         restrict their values to a particular geometry type.
       </para>
 
@@ -1788,11 +1804,11 @@
 
       <para>
         <literal>GEOMETRYCOLLECTION</literal> can store a collection of
-        objects of any type. The other collection types,
-        <literal>MULTIPOINT</literal> and
-        <literal>MULTILINESTRING</literal> and
-        <literal>MULTIPOLYGON</literal> and
-        <literal>GEOMETRYCOLLECTION</literal>, restrict collection
+        objects of any type. The other collection types
+        (<literal>MULTIPOINT</literal>,
+        <literal>MULTILINESTRING</literal>,
+        <literal>MULTIPOLYGON</literal>, and
+        <literal>GEOMETRYCOLLECTION</literal>) restrict collection
         members to those having a particular geometry type.
       </para>
 
@@ -2064,12 +2080,13 @@
         </itemizedlist>
 
         <para>
-          The OpenGIS specification also describes optional functions
-          for constructing <literal>Polygon</literal> or
+          The OpenGIS specification also defines the following optional
+          functions, which MySQL does not implement. These functions
+          construct <literal>Polygon</literal> or
           <literal>MultiPolygon</literal> values based on the WKT
           representation of a collection of rings or closed
           <literal>LineString</literal> values. These values may
-          intersect. MySQL does not implement these functions:
+          intersect.
         </para>
 
         <itemizedlist>
@@ -2426,14 +2443,15 @@
         <title>&title-gis-mysql-specific-functions;</title>
 
         <para>
-          MySQL provides a set of useful functions for creating geometry
-          WKB representations. The functions described in this section
-          are MySQL extensions to the OpenGIS specifications. The
-          results of these functions are <literal>BLOB</literal> values
-          containing WKB representations of geometry values with no
-          SRID. The results of these functions can be substituted as the
-          first argument for any function in the
-          <literal>GeomFromWKB()</literal> function family.
+          MySQL provides a set of useful non-standard functions for
+          creating geometry WKB representations. The functions described
+          in this section are MySQL extensions to the OpenGIS
+          specification. The results of these functions are
+          <literal>BLOB</literal> values containing WKB representations
+          of geometry values with no SRID. The results of these
+          functions can be substituted as the first argument for any
+          function in the <literal>GeomFromWKB()</literal> function
+          family.
         </para>
 
         <remark role="help-category" condition="Geometry constructors@Geographic Features"/>
@@ -2639,8 +2657,7 @@
           <remark role="help-example"/>
 
 <programlisting>
-mysql&gt; <userinput>CREATE TABLE geom (g GEOMETRY);</userinput>
-Query OK, 0 rows affected (0.02 sec)
+CREATE TABLE geom (g GEOMETRY);
 </programlisting>
         </listitem>
 
@@ -2651,12 +2668,8 @@
           </para>
 
 <programlisting>
-mysql&gt; <userinput>ALTER TABLE geom ADD pt POINT;</userinput>
-Query OK, 0 rows affected (0.00 sec)
-Records: 0  Duplicates: 0  Warnings: 0
-mysql&gt; <userinput>ALTER TABLE geom DROP pt;</userinput>
-Query OK, 0 rows affected (0.00 sec)
-Records: 0  Duplicates: 0  Warnings: 0
+ALTER TABLE geom ADD pt POINT;
+ALTER TABLE geom DROP pt;
 </programlisting>
         </listitem>
 
@@ -2678,31 +2691,39 @@
         convert them to that format from either Well-Known Text (WKT) or
         Well-Known Binary (WKB) format. The following examples
         demonstrate how to insert geometry values into a table by
-        converting WKT values into internal geometry format.
+        converting WKT values into internal geometry format:
       </para>
 
-      <para>
-        You can perform the conversion directly in the
-        <literal>INSERT</literal> statement:
-      </para>
+      <itemizedlist>
 
+        <listitem>
+          <para>
+            Perform the conversion directly in the
+            <literal>INSERT</literal> statement:
+          </para>
+
 <programlisting>
 INSERT INTO geom VALUES (GeomFromText('POINT(1 1)'));
 
 SET @g = 'POINT(1 1)';
 INSERT INTO geom VALUES (GeomFromText(@g));
 </programlisting>
+        </listitem>
 
-      <para>
-        Or you can perform the conversion prior to the
-        <literal>INSERT</literal>:
-      </para>
+        <listitem>
+          <para>
+            Perform the conversion prior to the
+            <literal>INSERT</literal>:
+          </para>
 
 <programlisting>
 SET @g = GeomFromText('POINT(1 1)');
 INSERT INTO geom VALUES (@g);
 </programlisting>
+        </listitem>
 
+      </itemizedlist>
+
       <para>
         The following examples insert more complex geometries into the
         table:
@@ -2802,51 +2823,55 @@
         format. You can also convert them into WKT or WKB format.
       </para>
 
-      <section id="fetching-spatial-data-in-internal-format">
+      <itemizedlist>
 
-        <title>&title-fetching-spatial-data-in-internal-format;</title>
+        <listitem>
+          <para>
+            Fetching spatial data in internal format:
+          </para>
 
-        <para>
-          Fetching geometry values using internal format can be useful
-          in table-to-table transfers:
-        </para>
+          <para>
+            Fetching geometry values using internal format can be useful
+            in table-to-table transfers:
+          </para>
 
 <programlisting>
 CREATE TABLE geom2 (g GEOMETRY) SELECT g FROM geom;
 </programlisting>
+        </listitem>
 
-      </section>
+        <listitem>
+          <para>
+            Fetching spatial data in WKT format:
+          </para>
 
-      <section id="fetching-spatial-data-in-wkt-format">
+          <para>
+            The <literal>AsText()</literal> function converts a geometry
+            from internal format into a WKT string.
+          </para>
 
-        <title>&title-fetching-spatial-data-in-wkt-format;</title>
-
-        <para>
-          The <literal>AsText()</literal> function converts a geometry
-          from internal format into a WKT string.
-        </para>
-
 <programlisting>
 SELECT AsText(g) FROM geom;
 </programlisting>
+        </listitem>
 
-      </section>
+        <listitem>
+          <para>
+            Fetching spatial data in WKB format:
+          </para>
 
-      <section id="fetching-spatial-data-in-wkb-format">
+          <para>
+            The <literal>AsBinary()</literal> function converts a
+            geometry from internal format into a <literal>BLOB</literal>
+            containing the WKB value.
+          </para>
 
-        <title>&title-fetching-spatial-data-in-wkb-format;</title>
-
-        <para>
-          The <literal>AsBinary()</literal> function converts a geometry
-          from internal format into a <literal>BLOB</literal> containing
-          the WKB value.
-        </para>
-
 <programlisting>
 SELECT AsBinary(g) FROM geom;
 </programlisting>
+        </listitem>
 
-      </section>
+      </itemizedlist>
 
     </section>
 
@@ -3004,7 +3029,7 @@
             internal geometry format and returns the result. A number of
             type-specific functions are also supported, such as
             <literal>PointFromText()</literal> and
-            <literal>LineFromText()</literal>; see
+            <literal>LineFromText()</literal>. See
             <xref linkend="gis-wkt-functions"/>.
           </para>
         </listitem>
@@ -3023,7 +3048,7 @@
             internal geometry format and returns the result. A number of
             type-specific functions are also supported, such as
             <literal>PointFromWKB()</literal> and
-            <literal>LineFromWKB()</literal>; see
+            <literal>LineFromWKB()</literal>. See
             <xref linkend="gis-wkb-functions"/>.
           </para>
         </listitem>
@@ -3075,9 +3100,9 @@
 
             <para>
               Returns the inherent dimension of the geometry value
-              <replaceable>g</replaceable>. The result can be &minus;1, 0,
-              1, or 2. (The meaning of these values is given in
-              <xref linkend="gis-class-geometry"/>.)
+              <replaceable>g</replaceable>. The result can be &minus;1,
+              0, 1, or 2. The meaning of these values is given in
+              <xref linkend="gis-class-geometry"/>.
             </para>
 
             <remark role="help-description-end"/>
@@ -3294,7 +3319,8 @@
               The description of each instantiable geometric class given
               earlier in the chapter includes the specific conditions
               that cause an instance of that class to be classified as
-              not simple.
+              not simple. (See
+              <xref linkend= "gis-geometry-class-hierarchy"/>.)
             </para>
 
             <remark role="help-description-end"/>
@@ -3340,12 +3366,13 @@
             <remark role="help-example"/>
 
 <programlisting>
-mysql&gt; <userinput>SELECT X(GeomFromText('Point(56.7 53.34)'));</userinput>
-+--------------------------------------+
-| X(GeomFromText('Point(56.7 53.34)')) |
-+--------------------------------------+
-|                                 56.7 |
-+--------------------------------------+
+mysql&gt; <userinput>SET @pt = 'Point(56.7 53.34)';</userinput>
+mysql&gt; <userinput>SELECT X(GeomFromText(@pt));</userinput>
++----------------------+
+| X(GeomFromText(@pt)) |
++----------------------+
+|                 56.7 |
++----------------------+
 </programlisting>
           </listitem>
 
@@ -3372,12 +3399,13 @@
             <remark role="help-example"/>
 
 <programlisting>
-mysql&gt; <userinput>SELECT Y(GeomFromText('Point(56.7 53.34)'));</userinput>
-+--------------------------------------+
-| Y(GeomFromText('Point(56.7 53.34)')) |
-+--------------------------------------+
-|                                53.34 |
-+--------------------------------------+
+mysql&gt; <userinput>SET @pt = 'Point(56.7 53.34)';</userinput>
+mysql&gt; <userinput>SELECT Y(GeomFromText(@pt));</userinput>
++----------------------+
+| Y(GeomFromText(@pt)) |
++----------------------+
+|                53.34 |
++----------------------+
 </programlisting>
           </listitem>
 
@@ -3467,6 +3495,12 @@
 |            2.8284271247462 |
 +----------------------------+
 </programlisting>
+
+            <para>
+              <literal>GLength()</literal> is a non-standard name. It
+              corresponds to the OpenGIS <literal>Length()</literal>
+              function.
+            </para>
           </listitem>
 
           <listitem>
@@ -3483,8 +3517,8 @@
             </para>
 
             <para>
-              Returns the number of points in the
-              <literal>LineString</literal> value
+              Returns the number of <literal>Point</literal> objects in
+              the <literal>LineString</literal> value
               <replaceable>ls</replaceable>.
             </para>
 
@@ -3517,9 +3551,11 @@
             </para>
 
             <para>
-              Returns the <replaceable>n</replaceable>-th point in the
+              Returns the <replaceable>n</replaceable>-th
+              <literal>Point</literal> in the
               <literal>Linestring</literal> value
-              <replaceable>ls</replaceable>. Point numbers begin at 1.
+              <replaceable>ls</replaceable>. Points are numbered
+              beginning with 1.
             </para>
 
             <remark role="help-description-end"/>
@@ -3615,6 +3651,12 @@
         <itemizedlist>
 
           <listitem>
+            <remark role="note">
+              There is no help-table markup for GLength because there is
+              another marked-up entry in the LineString functions
+              section.
+            </remark>
+
             <para>
               <indexterm type="function">
                 <primary>GLength()</primary>
@@ -3640,6 +3682,12 @@
 |             4.2426406871193 |
 +-----------------------------+
 </programlisting>
+
+            <para>
+              <literal>GLength()</literal> is a non-standard name. It
+              corresponds to the OpenGIS <literal>Length()</literal>
+              function.
+            </para>
           </listitem>
 
           <listitem>
@@ -3658,8 +3706,8 @@
               <literal>EndPoint()</literal> values are the same for each
               <literal>LineString</literal> in
               <replaceable>mls</replaceable>). Returns 0 if
-              <replaceable>mls</replaceable> is not closed, and &minus;1 if
-              it is <literal>NULL</literal>.
+              <replaceable>mls</replaceable> is not closed, and &minus;1
+              if it is <literal>NULL</literal>.
             </para>
 
 <programlisting>
@@ -3777,7 +3825,8 @@
               Returns the <replaceable>n</replaceable>-th interior ring
               for the <literal>Polygon</literal> value
               <replaceable>poly</replaceable> as a
-              <literal>LineString</literal>. Ring numbers begin at 1.
+              <literal>LineString</literal>. Rings are numbered
+              beginning with 1.
             </para>
 
             <remark role="help-description-end"/>
@@ -3948,8 +3997,8 @@
             <para>
               Returns the <replaceable>n</replaceable>-th geometry in
               the <literal>GeometryCollection</literal> value
-              <replaceable>gc</replaceable>. Geometry numbers begin at
-              1.
+              <replaceable>gc</replaceable>. Geometries are numbered
+              beginning with 1.
             </para>
 
             <remark role="help-description-end"/>
@@ -4020,9 +4069,9 @@
         <title>&title-functions-that-produce-new-geometries;</title>
 
         <para>
-          In <xref linkend="geometry-property-functions"/>,
-          we've discussed some functions that can construct new
-          geometries from the existing ones:
+          <xref linkend="geometry-property-functions"/>, discusses
+          several functions that construct new geometries from existing
+          ones. See that section for descriptions of these functions:
         </para>
 
         <itemizedlist>
@@ -4251,9 +4300,10 @@
       <remark role="help-category" condition="MBR@Geographic Features"/>
 
       <para>
-        MySQL provides some functions that can test relations between
+        MySQL provides several functions that test relations between
         minimal bounding rectangles of two geometries
-        <literal>g1</literal> and <literal>g2</literal>. They include:
+        <literal>g1</literal> and <literal>g2</literal>. The return
+        values 1 and 0 indicate true and false, respectively.
       </para>
 
       <itemizedlist>
@@ -4272,10 +4322,9 @@
           </para>
 
           <para>
-            Returns 1 or 0 to indicate whether or not the Minimum
-            Bounding Rectangle of <replaceable>g1</replaceable> contains
-            the Minimum Bounding Rectangle of
-            <replaceable>g2</replaceable>.
+            Returns 1 or 0 to indicate whether the Minimum Bounding
+            Rectangle of <replaceable>g1</replaceable> contains the
+            Minimum Bounding Rectangle of <replaceable>g2</replaceable>.
           </para>
 
           <remark role="help-description-end"/>
@@ -4308,8 +4357,8 @@
           </para>
 
           <para>
-            Returns 1 or 0 to indicate whether or not the Minimum
-            Bounding Rectangles of the two geometries
+            Returns 1 or 0 to indicate whether the Minimum Bounding
+            Rectangles of the two geometries
             <replaceable>g1</replaceable> and
             <replaceable>g2</replaceable> are disjoint (do not
             intersect).
@@ -4332,8 +4381,8 @@
           </para>
 
           <para>
-            Returns 1 or 0 to indicate whether or not the Minimum
-            Bounding Rectangles of the two geometries
+            Returns 1 or 0 to indicate whether the Minimum Bounding
+            Rectangles of the two geometries
             <replaceable>g1</replaceable> and
             <replaceable>g2</replaceable> are the same.
           </para>
@@ -4355,8 +4404,8 @@
           </para>
 
           <para>
-            Returns 1 or 0 to indicate whether or not the Minimum
-            Bounding Rectangles of the two geometries
+            Returns 1 or 0 to indicate whether the Minimum Bounding
+            Rectangles of the two geometries
             <replaceable>g1</replaceable> and
             <replaceable>g2</replaceable> intersect.
           </para>
@@ -4378,8 +4427,8 @@
           </para>
 
           <para>
-            Returns 1 or 0 to indicate whether or not the Minimum
-            Bounding Rectangles of the two geometries
+            Returns 1 or 0 to indicate whether the Minimum Bounding
+            Rectangles of the two geometries
             <replaceable>g1</replaceable> and
             <replaceable>g2</replaceable> overlap.
           </para>
@@ -4401,8 +4450,8 @@
           </para>
 
           <para>
-            Returns 1 or 0 to indicate whether or not the Minimum
-            Bounding Rectangles of the two geometries
+            Returns 1 or 0 to indicate whether the Minimum Bounding
+            Rectangles of the two geometries
             <replaceable>g1</replaceable> and
             <replaceable>g2</replaceable> touch.
           </para>
@@ -4424,10 +4473,9 @@
           </para>
 
           <para>
-            Returns 1 or 0 to indicate whether or not the Minimum
-            Bounding Rectangle of <replaceable>g1</replaceable> is
-            within the Minimum Bounding Rectangle of
-            <replaceable>g2</replaceable>.
+            Returns 1 or 0 to indicate whether the Minimum Bounding
+            Rectangle of <replaceable>g1</replaceable> is within the
+            Minimum Bounding Rectangle of <replaceable>g2</replaceable>.
           </para>
 
           <remark role="help-description-end"/>
@@ -4455,10 +4503,15 @@
       <title>&title-functions-that-test-spatial-relationships-between-geometries;</title>
 
       <para>
-        The OpenGIS specification defines the following functions.
-        Currently, MySQL does not implement them according to the
-        specification. Those that are implemented return the same result
-        as the corresponding MBR-based functions. This includes
+        The OpenGIS specification defines the following functions. They
+        test the relationship between two geometry values
+        <literal>g1</literal> and <literal>g2</literal>.
+      </para>
+
+      <para>
+        Currently, MySQL does not implement these functions according to
+        the specification. Those that are implemented return the same
+        result as the corresponding MBR-based functions. This includes
         functions in the following list other than
         <literal>Distance()</literal> and <literal>Related()</literal>.
       </para>
@@ -4474,8 +4527,7 @@
       </para>
 
       <para>
-        The functions operate on two geometry values
-        <literal>g1</literal> and <literal>g2</literal>.
+        The return values 1 and 0 indicate true and false, respectively.
       </para>
 
       <remark role="help-category" condition="Geometry relations@Geographic Features"/>
@@ -4496,7 +4548,7 @@
           </para>
 
           <para>
-            Returns 1 or 0 to indicate whether or not
+            Returns 1 or 0 to indicate whether
             <replaceable>g1</replaceable> completely contains
             <replaceable>g2</replaceable>.
           </para>
@@ -4575,7 +4627,7 @@
           </para>
 
           <para>
-            Returns 1 or 0 to indicate whether or not
+            Returns 1 or 0 to indicate whether
             <replaceable>g1</replaceable> is spatially disjoint from
             (does not intersect) <replaceable>g2</replaceable>.
           </para>
@@ -4617,7 +4669,7 @@
           </para>
 
           <para>
-            Returns 1 or 0 to indicate whether or not
+            Returns 1 or 0 to indicate whether
             <replaceable>g1</replaceable> is spatially equal to
             <replaceable>g2</replaceable>.
           </para>
@@ -4639,7 +4691,7 @@
           </para>
 
           <para>
-            Returns 1 or 0 to indicate whether or not
+            Returns 1 or 0 to indicate whether
             <replaceable>g1</replaceable> spatially intersects
             <replaceable>g2</replaceable>.
           </para>
@@ -4661,7 +4713,7 @@
           </para>
 
           <para>
-            Returns 1 or 0 to indicate whether or not
+            Returns 1 or 0 to indicate whether
             <replaceable>g1</replaceable> spatially overlaps
             <replaceable>g2</replaceable>. The term <emphasis>spatially
             overlaps</emphasis> is used if two geometries intersect and
@@ -4687,14 +4739,13 @@
           </para>
 
           <para>
-            Returns 1 or 0 to indicate whether or not the spatial
-            relationship specified by
-            <replaceable>pattern_matrix</replaceable> exists between
-            <replaceable>g1</replaceable> and
-            <replaceable>g2</replaceable>. Returns &minus;1 if the arguments
-            are <literal>NULL</literal>. The pattern matrix is a string.
-            Its specification will be noted here if this function is
-            implemented.
+            Returns 1 or 0 to indicate whether the spatial relationship
+            specified by <replaceable>pattern_matrix</replaceable>
+            exists between <replaceable>g1</replaceable> and
+            <replaceable>g2</replaceable>. Returns &minus;1 if the
+            arguments are <literal>NULL</literal>. The pattern matrix is
+            a string. Its specification will be noted here if this
+            function is implemented.
           </para>
         </listitem>
 
@@ -4712,7 +4763,7 @@
           </para>
 
           <para>
-            Returns 1 or 0 to indicate whether or not
+            Returns 1 or 0 to indicate whether
             <replaceable>g1</replaceable> spatially touches
             <replaceable>g2</replaceable>. Two geometries
             <emphasis>spatially touch</emphasis> if the interiors of the
@@ -4738,7 +4789,7 @@
           </para>
 
           <para>
-            Returns 1 or 0 to indicate whether or not
+            Returns 1 or 0 to indicate whether
             <replaceable>g1</replaceable> is spatially within
             <replaceable>g2</replaceable>.
           </para>
@@ -4809,10 +4860,10 @@
       <para>
         MySQL can create spatial indexes using syntax similar to that
         for creating regular indexes, but extended with the
-        <literal>SPATIAL</literal> keyword. Spatial columns that are
-        indexed currently must be declared <literal>NOT NULL</literal>.
+        <literal>SPATIAL</literal> keyword. Currently, spatial columns
+        that are indexed must be declared <literal>NOT NULL</literal>.
         The following examples demonstrate how to create spatial
-        indexes.
+        indexes:
       </para>
 
       <itemizedlist>
@@ -4823,7 +4874,7 @@
           </para>
 
 <programlisting>
-mysql&gt; <userinput>CREATE TABLE geom (g GEOMETRY NOT NULL, SPATIAL INDEX(g));</userinput>
+CREATE TABLE geom (g GEOMETRY NOT NULL, SPATIAL INDEX(g));
 </programlisting>
         </listitem>
 
@@ -4833,7 +4884,7 @@
           </para>
 
 <programlisting>
-mysql&gt; <userinput>ALTER TABLE geom ADD SPATIAL INDEX(g);</userinput>
+ALTER TABLE geom ADD SPATIAL INDEX(g);
 </programlisting>
         </listitem>
 
@@ -4843,7 +4894,7 @@
           </para>
 
 <programlisting>
-mysql&gt; <userinput>CREATE SPATIAL INDEX sp_index ON geom (g);</userinput>
+CREATE SPATIAL INDEX sp_index ON geom (g);
 </programlisting>
         </listitem>
 
@@ -4862,7 +4913,7 @@
           </para>
 
 <programlisting>
-mysql&gt; <userinput>ALTER TABLE geom DROP INDEX g;</userinput>
+ALTER TABLE geom DROP INDEX g;
 </programlisting>
         </listitem>
 
@@ -4872,7 +4923,7 @@
           </para>
 
 <programlisting>
-mysql&gt; <userinput>DROP INDEX sp_index ON geom;</userinput>
+DROP INDEX sp_index ON geom;
 </programlisting>
         </listitem>
 
@@ -4929,13 +4980,15 @@
         be involved in the search for queries that use a function such
         as <literal>MBRContains()</literal> or
         <literal>MBRWithin()</literal> in the <literal>WHERE</literal>
-        clause. For example, let's say we want to find all objects that
-        are in the given rectangle:
+        clause. The following query finds all objects that are in the
+        given rectangle:
       </para>
 
 <programlisting>
+mysql&gt; <userinput>SET @poly =</userinput>
+    -&gt; <userinput>'Polygon((30000 15000,31000 15000,31000 16000,30000 16000,30000 15000))';</userinput>
 mysql&gt; <userinput>SELECT fid,AsText(g) FROM geom WHERE</userinput>
-mysql&gt; <userinput>MBRContains(GeomFromText('Polygon((30000 15000,31000 15000,31000 16000,30000 16000,30000 15000))'),g);</userinput>
+    -&gt; <userinput>MBRContains(GeomFromText(@poly),g);</userinput>
 +-----+-----------------------------------------------------------------------------+
 | fid | AsText(g)                                                                   |
 +-----+-----------------------------------------------------------------------------+
@@ -4964,45 +5017,64 @@
 </programlisting>
 
       <para>
-        Let's use <literal>EXPLAIN</literal> to check the way this query
-        is executed (the <literal>id</literal> column has been removed
-        so the output better fits the page):
+        Use <literal>EXPLAIN</literal> to check the way this query is
+        executed (the <literal>id</literal> column has been removed so
+        the output better fits the page):
       </para>
 
 <programlisting>
+mysql&gt; <userinput>SET @poly =</userinput>
+    -&gt; <userinput>'Polygon((30000 15000,31000 15000,31000 16000,30000 16000,30000 15000))';</userinput>
 mysql&gt; <userinput>EXPLAIN SELECT fid,AsText(g) FROM geom WHERE</userinput>
-mysql&gt; <userinput>MBRContains(GeomFromText('Polygon((30000 15000,31000 15000,31000 16000,30000 16000,30000 15000))'),g);</userinput>
-+-------------+-------+-------+---------------+------+---------+------+------+-------------+
-| select_type | table | type  | possible_keys | key  | key_len | ref  | rows | Extra       |
-+-------------+-------+-------+---------------+------+---------+------+------+-------------+
-| SIMPLE      | geom  | range | g             | g    |      32 | NULL |   50 | Using where |
-+-------------+-------+-------+---------------+------+---------+------+------+-------------+
+    -&gt; <userinput>MBRContains(GeomFromText(@poly),g)\G</userinput>
+*************************** 1. row ***************************
+           id: 1
+  select_type: SIMPLE
+        table: geom
+         type: range
+possible_keys: g
+          key: g
+      key_len: 32
+          ref: NULL
+         rows: 50
+        Extra: Using where
 1 row in set (0.00 sec)
 </programlisting>
 
       <para>
-        Let's check what would happen without a spatial index:
+        Check what would happen without a spatial index:
       </para>
 
 <programlisting>
+mysql&gt; <userinput>SET @poly =</userinput>
+    -&gt; <userinput>'Polygon((30000 15000,31000 15000,31000 16000,30000 16000,30000 15000))';</userinput>
 mysql&gt; <userinput>EXPLAIN SELECT fid,AsText(g) FROM g IGNORE INDEX (g) WHERE</userinput>
-mysql&gt; <userinput>MBRContains(GeomFromText('Polygon((30000 15000,31000 15000,31000 16000,30000 16000,30000 15000))'),g);</userinput>
-+-------------+-------+------+---------------+------+---------+------+-------+-------------+
-| select_type | table | type | possible_keys | key  | key_len | ref  | rows  | Extra       |
-+-------------+-------+------+---------------+------+---------+------+-------+-------------+
-| SIMPLE      | geom  | ALL  | NULL          | NULL |    NULL | NULL | 32376 | Using where |
-+-------------+-------+------+---------------+------+---------+------+-------+-------------+
+    -&gt; <userinput>MBRContains(GeomFromText(@poly),g)\G</userinput>
+*************************** 1. row ***************************
+           id: 1
+  select_type: SIMPLE
+        table: geom
+         type: ALL
+possible_keys: NULL
+          key: NULL
+      key_len: NULL
+          ref: NULL
+         rows: 32376
+        Extra: Using where
 1 row in set (0.00 sec)
 </programlisting>
 
       <para>
-        Let's execute the <literal>SELECT</literal> statement, ignoring
-        the spatial key we have:
+        Executing the <literal>SELECT</literal> statement without the
+        spatial index yields the same result but causes the execution
+        time to rise from 0.00 seconds to 0.46 seconds:
       </para>
 
 <programlisting>
+mysql&gt; <userinput>SET @poly =</userinput>
+    -&gt; <userinput>'Polygon((30000 15000,31000 15000,31000 16000,30000 16000,30000 15000))';</userinput>
 mysql&gt; <userinput>SELECT fid,AsText(g) FROM geom IGNORE INDEX (g) WHERE</userinput>
-mysql&gt; <userinput>MBRContains(GeomFromText('Polygon((30000 15000,31000 15000,31000 16000,30000 16000,30000 15000))'),g);</userinput>
+    -&gt; <userinput>MBRContains(GeomFromText(@poly),g);</userinput>
 +-----+-----------------------------------------------------------------------------+
 | fid | AsText(g)                                                                   |
 +-----+-----------------------------------------------------------------------------+
@@ -5031,11 +5103,6 @@
 </programlisting>
 
       <para>
-        When the index is not used, the execution time for this query
-        rises from 0.00 seconds to 0.46 seconds.
-      </para>
-
-      <para>
         In future releases, spatial indexes may also be used for
         optimizing other functions. See
         <xref linkend="functions-for-testing-spatial-relations-between-geometric-objects"/>.
@@ -5049,72 +5116,65 @@
 
     <title>&title-mysql-gis-conformance-and-compatibility;</title>
 
-    <remark role="todo">
-      Add introductory descriptive sentence.
-    </remark>
+    <para>
+      MySQL does not yet implement the following GIS features:
+    </para>
 
-    <section id="gis-features-that-are-not-yet-implemented">
+    <itemizedlist>
 
-      <title>&title-gis-features-that-are-not-yet-implemented;</title>
+      <listitem>
+        <para>
+          Additional Metadata Views
+        </para>
 
-      <itemizedlist>
+        <para>
+          OpenGIS specifications propose several additional metadata
+          views. For example, a system view named
+          <literal>GEOMETRY_COLUMNS</literal> contains a description of
+          geometry columns, one row for each geometry column in the
+          database.
+        </para>
 
-        <listitem>
-          <para>
-            Additional Metadata Views
-          </para>
+        <remark>
+          @item Functions to add/drop spatial columns OpenGIS assumes
+          that columns can be added or dropped using special
+          @code{AddGeometryColumn()} and @code{DropGeometryColumn()}
+          functions. In MySQL, this is done using the @code{ALTER
+          TABLE}, @code{CREATE INDEX}, and @code{DROP INDEX} statements
+          instead. @item Factors related to Spatial Reference Systems
+          and their IDs (SRIDs): @itemize @bullet @item Functions like
+          @code{Length()} and @code{Area()} assume a planar coordinate
+          system. @item All objects currently are considered to be in
+          the same planar coordinate system. @end itemize
+        </remark>
+      </listitem>
 
-          <para>
-            OpenGIS specifications propose several additional metadata
-            views. For example, a system view named
-            <literal>GEOMETRY_COLUMNS</literal> contains a description
-            of geometry columns, one row for each geometry column in the
-            database.
-          </para>
+      <listitem>
+        <para>
+          The OpenGIS function <literal>Length()</literal> on
+          <literal>LineString</literal> and
+          <literal>MultiLineString</literal> currently should be called
+          in MySQL as <literal>GLength()</literal>
+        </para>
 
-          <remark>
-            @item Functions to add/drop spatial columns OpenGIS assumes
-            that columns can be added or dropped using special
-            @code{AddGeometryColumn()} and @code{DropGeometryColumn()}
-            functions. In MySQL, this is done using the @code{ALTER
-            TABLE}, @code{CREATE INDEX}, and @code{DROP INDEX}
-            statements instead. @item Factors related to Spatial
-            Reference Systems and their IDs (SRIDs): @itemize @bullet
-            @item Functions like @code{Length()} and @code{Area()}
-            assume a planar coordinate system. @item All objects
-            currently are considered to be in the same planar coordinate
-            system. @end itemize
-          </remark>
-        </listitem>
+        <para>
+          The problem is that there is an existing SQL function
+          <literal>Length()</literal> that calculates the length of
+          string values, and sometimes it is not possible to distinguish
+          whether the function is called in a textual or spatial
+          context. We need either to solve this somehow, or decide on
+          another function name.
+        </para>
+      </listitem>
 
-        <listitem>
-          <para>
-            The OpenGIS function <literal>Length()</literal> on
-            <literal>LineString</literal> and
-            <literal>MultiLineString</literal> currently should be
-            called in MySQL as <literal>GLength()</literal>
-          </para>
+    </itemizedlist>
 
-          <para>
-            The problem is that there is an existing SQL function
-            <literal>Length()</literal> which calculates the length of
-            string values, and sometimes it is not possible to
-            distinguish whether the function is called in a textual or
-            spatial context. We need either to solve this somehow, or
-            decide on another function name.
-          </para>
-        </listitem>
+    <remark>
+      @node GIS writing a GIS application @section Writing a GIS
+      Application @node GIS Java GIS Object Model @section Java GIS
+      Object Model
+    </remark>
 
-      </itemizedlist>
-
-      <remark>
-        @node GIS writing a GIS application @section Writing a GIS
-        Application @node GIS Java GIS Object Model @section Java GIS
-        Object Model
-      </remark>
-
-    </section>
-
   </section>
 
 </chapter>

Modified: trunk/refman-5.0/renamed-nodes.txt
===================================================================
--- trunk/refman-5.0/renamed-nodes.txt	2006-01-19 15:38:42 UTC (rev 929)
+++ trunk/refman-5.0/renamed-nodes.txt	2006-01-19 15:38:54 UTC (rev 930)
@@ -398,3 +398,7 @@
 charset-config-file adding-character-set
 open-tables table-cache
 variables user-variables
+fetching-spatial-data-in-internal-format fetching-spatial-data
+fetching-spatial-data-in-wkb-format fetching-spatial-data
+fetching-spatial-data-in-wkt-format fetching-spatial-data
+gis-features-that-are-not-yet-implemented mysql-gis-conformance-and-compatibility

Modified: trunk/refman-5.0/spatial-extensions.xml
===================================================================
--- trunk/refman-5.0/spatial-extensions.xml	2006-01-19 15:38:42 UTC (rev 929)
+++ trunk/refman-5.0/spatial-extensions.xml	2006-01-19 15:38:54 UTC (rev 930)
@@ -72,20 +72,31 @@
 
   <para>
     <emphasis role="bold">Additional resources</emphasis>
+  </para>
 
-    <itemizedlist>
+  <itemizedlist>
 
-      <listitem>
-        <para>
-          If you have questions or concerns about the use of the spatial
-          extensions to MySQL, you can discuss these in the GIS forum:
-          <ulink url="&base-url-forum-list;?23"/>.
-        </para>
-      </listitem>
+    <listitem>
+      <para>
+        The Open Geospatial Consortium publishes the
+        <citetitle>OpenGIS&reg; Simple Features Specifications For
+        SQL</citetitle>, a document that proposes several conceptual
+        ways for extending an SQL RDBMS to support spatial data. This
+        specification is available from the OGC Web site at
+        <ulink url="http://www.opengis.org/docs/99-049.pdf"/>.
+      </para>
+    </listitem>
 
-    </itemizedlist>
-  </para>
+    <listitem>
+      <para>
+        If you have questions or concerns about the use of the spatial
+        extensions to MySQL, you can discuss them in the GIS forum:
+        <ulink url="&base-url-forum-list;?23"/>.
+      </para>
+    </listitem>
 
+  </itemizedlist>
+
   <section id="gis-introduction">
 
     <title>&title-gis-introduction;</title>
@@ -104,20 +115,20 @@
 
     <para>
       MySQL implements spatial extensions following the specification of
-      the <literal>Open GIS Consortium</literal> (OGC). This is an
-      international consortium of more than 250 companies, agencies, and
-      universities participating in the development of publicly
-      available conceptual solutions that can be useful with all kinds
-      of applications that manage spatial data. The OGC maintains a Web
-      site at <ulink url="http://www.opengis.org/"/>.
+      the Open Geospatial Consortium (OGC). This is an international
+      consortium of more than 250 companies, agencies, and universities
+      participating in the development of publicly available conceptual
+      solutions that can be useful with all kinds of applications that
+      manage spatial data. The OGC maintains a Web site at
+      <ulink url="http://www.opengis.org/"/>.
     </para>
 
     <para>
-      In 1997, the Open GIS Consortium published the
+      In 1997, the Open Geospatial Consortium published the
       <citetitle>OpenGIS&reg; Simple Features Specifications For
       SQL</citetitle>, a document that proposes several conceptual ways
       for extending an SQL RDBMS to support spatial data. This
-      specification is available from the Open GIS Web site at
+      specification is available from the OGC Web site at
       <ulink url="http://www.opengis.org/docs/99-049.pdf"/>. It contains
       additional information relevant to this chapter.
     </para>
@@ -127,7 +138,7 @@
       Geometry Types</emphasis> environment proposed by OGC. This term
       refers to an SQL environment that has been extended with a set of
       geometry types. A geometry-valued SQL column is implemented as a
-      column that has a geometry type. The specifications describe a set
+      column that has a geometry type. The specification describe a set
       of SQL geometry types, as well as functions on those types to
       create and analyze geometry values.
     </para>
@@ -169,9 +180,8 @@
     </indexterm>
 
     <para>
-      You can also find documents that use the term
-      <emphasis role="bold">geospatial feature</emphasis> to refer to
-      geographic features.
+      Some documents use the term <emphasis role="bold">geospatial
+      feature</emphasis> to refer to geographic features.
     </para>
 
     <indexterm>
@@ -191,16 +201,12 @@
       <emphasis role="bold">geographic feature</emphasis>,
       <emphasis role="bold">geospatial feature</emphasis>,
       <emphasis role="bold">feature</emphasis>, or
-      <emphasis role="bold">geometry</emphasis>. The term most commonly
-      used here is <emphasis role="bold">geometry</emphasis>.
+      <emphasis role="bold">geometry</emphasis>. Here, the term most
+      commonly used is <emphasis role="bold">geometry</emphasis>,
+      defined as <emphasis>a point or an aggregate of points
+      representing anything in the world that has a location</emphasis>.
     </para>
 
-    <para>
-      Let's define a <emphasis role="bold">geometry</emphasis> as
-      <emphasis>a point or an aggregate of points representing anything
-      in the world that has a location</emphasis>.
-    </para>
-
   </section>
 
   <section id="opengis-geometry-model">
@@ -370,7 +376,7 @@
       <remark role="help-description-begin"/>
 
       <para>
-        <literal>Geometry</literal> is the base class. It's an abstract
+        <literal>Geometry</literal> is the base class. It is an abstract
         class. The instantiable subclasses of
         <literal>Geometry</literal> are restricted to zero-, one-, and
         two-dimensional geometric objects that exist in two-dimensional
@@ -461,8 +467,8 @@
         It is a non-instantiable class but has a number of properties
         that are common to all geometry values created from any of the
         <literal>Geometry</literal> subclasses. These properties are
-        described in the following list. (Particular subclasses have
-        their own specific properties, described later.)
+        described in the following list. Particular subclasses have
+        their own specific properties, described later.
       </para>
 
       <para>
@@ -1424,7 +1430,7 @@
       </remark>
 
       <para>
-        Examples of WKT representations of geometry objects are:
+        Examples of WKT representations of geometry objects:
       </para>
 
       <itemizedlist>
@@ -1530,7 +1536,7 @@
 
       <para>
         A Backus-Naur grammar that specifies the formal production rules
-        for writing WKT values can be found in the OGC specification
+        for writing WKT values can be found in the OpenGIS specification
         document referenced near the beginning of this chapter.
       </para>
 
@@ -1550,8 +1556,8 @@
 
       <para>
         The Well-Known Binary (WKB) representation for geometric values
-        is defined by the OpenGIS specifications. It is also defined in
-        the ISO <quote>SQL/MM Part 3: Spatial</quote> standard.
+        is defined by the OpenGIS specification. It is also defined in
+        the ISO <citetitle>SQL/MM Part 3: Spatial</citetitle> standard.
       </para>
 
       <para>
@@ -1765,8 +1771,8 @@
 
       <para>
         <literal>GEOMETRY</literal> can store geometry values of any
-        type. The other single-value types, <literal>POINT</literal> and
-        <literal>LINESTRING</literal> and <literal>POLYGON</literal>,
+        type. The other single-value types (<literal>POINT</literal>,
+        <literal>LINESTRING</literal>, and <literal>POLYGON</literal>)
         restrict their values to a particular geometry type.
       </para>
 
@@ -1804,11 +1810,11 @@
 
       <para>
         <literal>GEOMETRYCOLLECTION</literal> can store a collection of
-        objects of any type. The other collection types,
-        <literal>MULTIPOINT</literal> and
-        <literal>MULTILINESTRING</literal> and
-        <literal>MULTIPOLYGON</literal> and
-        <literal>GEOMETRYCOLLECTION</literal>, restrict collection
+        objects of any type. The other collection types
+        (<literal>MULTIPOINT</literal>,
+        <literal>MULTILINESTRING</literal>,
+        <literal>MULTIPOLYGON</literal>, and
+        <literal>GEOMETRYCOLLECTION</literal>) restrict collection
         members to those having a particular geometry type.
       </para>
 
@@ -2080,12 +2086,13 @@
         </itemizedlist>
 
         <para>
-          The OpenGIS specification also describes optional functions
-          for constructing <literal>Polygon</literal> or
+          The OpenGIS specification also defines the following optional
+          functions, which MySQL does not implement. These functions
+          construct <literal>Polygon</literal> or
           <literal>MultiPolygon</literal> values based on the WKT
           representation of a collection of rings or closed
           <literal>LineString</literal> values. These values may
-          intersect. MySQL does not implement these functions:
+          intersect.
         </para>
 
         <itemizedlist>
@@ -2442,14 +2449,15 @@
         <title>&title-gis-mysql-specific-functions;</title>
 
         <para>
-          MySQL provides a set of useful functions for creating geometry
-          WKB representations. The functions described in this section
-          are MySQL extensions to the OpenGIS specifications. The
-          results of these functions are <literal>BLOB</literal> values
-          containing WKB representations of geometry values with no
-          SRID. The results of these functions can be substituted as the
-          first argument for any function in the
-          <literal>GeomFromWKB()</literal> function family.
+          MySQL provides a set of useful non-standard functions for
+          creating geometry WKB representations. The functions described
+          in this section are MySQL extensions to the OpenGIS
+          specification. The results of these functions are
+          <literal>BLOB</literal> values containing WKB representations
+          of geometry values with no SRID. The results of these
+          functions can be substituted as the first argument for any
+          function in the <literal>GeomFromWKB()</literal> function
+          family.
         </para>
 
         <remark role="help-category" condition="Geometry constructors@Geographic Features"/>
@@ -2660,8 +2668,7 @@
           <remark role="help-example"/>
 
 <programlisting>
-mysql&gt; <userinput>CREATE TABLE geom (g GEOMETRY);</userinput>
-Query OK, 0 rows affected (0.02 sec)
+CREATE TABLE geom (g GEOMETRY);
 </programlisting>
         </listitem>
 
@@ -2672,12 +2679,8 @@
           </para>
 
 <programlisting>
-mysql&gt; <userinput>ALTER TABLE geom ADD pt POINT;</userinput>
-Query OK, 0 rows affected (0.00 sec)
-Records: 0  Duplicates: 0  Warnings: 0
-mysql&gt; <userinput>ALTER TABLE geom DROP pt;</userinput>
-Query OK, 0 rows affected (0.00 sec)
-Records: 0  Duplicates: 0  Warnings: 0
+ALTER TABLE geom ADD pt POINT;
+ALTER TABLE geom DROP pt;
 </programlisting>
         </listitem>
 
@@ -2699,31 +2702,39 @@
         convert them to that format from either Well-Known Text (WKT) or
         Well-Known Binary (WKB) format. The following examples
         demonstrate how to insert geometry values into a table by
-        converting WKT values into internal geometry format.
+        converting WKT values into internal geometry format:
       </para>
 
-      <para>
-        You can perform the conversion directly in the
-        <literal>INSERT</literal> statement:
-      </para>
+      <itemizedlist>
 
+        <listitem>
+          <para>
+            Perform the conversion directly in the
+            <literal>INSERT</literal> statement:
+          </para>
+
 <programlisting>
 INSERT INTO geom VALUES (GeomFromText('POINT(1 1)'));
 
 SET @g = 'POINT(1 1)';
 INSERT INTO geom VALUES (GeomFromText(@g));
 </programlisting>
+        </listitem>
 
-      <para>
-        Or you can perform the conversion prior to the
-        <literal>INSERT</literal>:
-      </para>
+        <listitem>
+          <para>
+            Perform the conversion prior to the
+            <literal>INSERT</literal>:
+          </para>
 
 <programlisting>
 SET @g = GeomFromText('POINT(1 1)');
 INSERT INTO geom VALUES (@g);
 </programlisting>
+        </listitem>
 
+      </itemizedlist>
+
       <para>
         The following examples insert more complex geometries into the
         table:
@@ -2823,51 +2834,55 @@
         format. You can also convert them into WKT or WKB format.
       </para>
 
-      <section id="fetching-spatial-data-in-internal-format">
+      <itemizedlist>
 
-        <title>&title-fetching-spatial-data-in-internal-format;</title>
+        <listitem>
+          <para>
+            Fetching spatial data in internal format:
+          </para>
 
-        <para>
-          Fetching geometry values using internal format can be useful
-          in table-to-table transfers:
-        </para>
+          <para>
+            Fetching geometry values using internal format can be useful
+            in table-to-table transfers:
+          </para>
 
 <programlisting>
 CREATE TABLE geom2 (g GEOMETRY) SELECT g FROM geom;
 </programlisting>
+        </listitem>
 
-      </section>
+        <listitem>
+          <para>
+            Fetching spatial data in WKT format:
+          </para>
 
-      <section id="fetching-spatial-data-in-wkt-format">
+          <para>
+            The <literal>AsText()</literal> function converts a geometry
+            from internal format into a WKT string.
+          </para>
 
-        <title>&title-fetching-spatial-data-in-wkt-format;</title>
-
-        <para>
-          The <literal>AsText()</literal> function converts a geometry
-          from internal format into a WKT string.
-        </para>
-
 <programlisting>
 SELECT AsText(g) FROM geom;
 </programlisting>
+        </listitem>
 
-      </section>
+        <listitem>
+          <para>
+            Fetching spatial data in WKB format:
+          </para>
 
-      <section id="fetching-spatial-data-in-wkb-format">
+          <para>
+            The <literal>AsBinary()</literal> function converts a
+            geometry from internal format into a <literal>BLOB</literal>
+            containing the WKB value.
+          </para>
 
-        <title>&title-fetching-spatial-data-in-wkb-format;</title>
-
-        <para>
-          The <literal>AsBinary()</literal> function converts a geometry
-          from internal format into a <literal>BLOB</literal> containing
-          the WKB value.
-        </para>
-
 <programlisting>
 SELECT AsBinary(g) FROM geom;
 </programlisting>
+        </listitem>
 
-      </section>
+      </itemizedlist>
 
     </section>
 
@@ -3025,7 +3040,7 @@
             internal geometry format and returns the result. A number of
             type-specific functions are also supported, such as
             <literal>PointFromText()</literal> and
-            <literal>LineFromText()</literal>; see
+            <literal>LineFromText()</literal>. See
             <xref linkend="gis-wkt-functions"/>.
           </para>
         </listitem>
@@ -3044,7 +3059,7 @@
             internal geometry format and returns the result. A number of
             type-specific functions are also supported, such as
             <literal>PointFromWKB()</literal> and
-            <literal>LineFromWKB()</literal>; see
+            <literal>LineFromWKB()</literal>. See
             <xref linkend="gis-wkb-functions"/>.
           </para>
         </listitem>
@@ -3096,9 +3111,9 @@
 
             <para>
               Returns the inherent dimension of the geometry value
-              <replaceable>g</replaceable>. The result can be &minus;1, 0,
-              1, or 2. (The meaning of these values is given in
-              <xref linkend="gis-class-geometry"/>.)
+              <replaceable>g</replaceable>. The result can be &minus;1,
+              0, 1, or 2. The meaning of these values is given in
+              <xref linkend="gis-class-geometry"/>.
             </para>
 
             <remark role="help-description-end"/>
@@ -3315,7 +3330,8 @@
               The description of each instantiable geometric class given
               earlier in the chapter includes the specific conditions
               that cause an instance of that class to be classified as
-              not simple.
+              not simple. (See
+              <xref linkend= "gis-geometry-class-hierarchy"/>.)
             </para>
 
             <remark role="help-description-end"/>
@@ -3361,12 +3377,13 @@
             <remark role="help-example"/>
 
 <programlisting>
-mysql&gt; <userinput>SELECT X(GeomFromText('Point(56.7 53.34)'));</userinput>
-+--------------------------------------+
-| X(GeomFromText('Point(56.7 53.34)')) |
-+--------------------------------------+
-|                                 56.7 |
-+--------------------------------------+
+mysql&gt; <userinput>SET @pt = 'Point(56.7 53.34)';</userinput>
+mysql&gt; <userinput>SELECT X(GeomFromText(@pt));</userinput>
++----------------------+
+| X(GeomFromText(@pt)) |
++----------------------+
+|                 56.7 |
++----------------------+
 </programlisting>
           </listitem>
 
@@ -3393,12 +3410,13 @@
             <remark role="help-example"/>
 
 <programlisting>
-mysql&gt; <userinput>SELECT Y(GeomFromText('Point(56.7 53.34)'));</userinput>
-+--------------------------------------+
-| Y(GeomFromText('Point(56.7 53.34)')) |
-+--------------------------------------+
-|                                53.34 |
-+--------------------------------------+
+mysql&gt; <userinput>SET @pt = 'Point(56.7 53.34)';</userinput>
+mysql&gt; <userinput>SELECT Y(GeomFromText(@pt));</userinput>
++----------------------+
+| Y(GeomFromText(@pt)) |
++----------------------+
+|                53.34 |
++----------------------+
 </programlisting>
           </listitem>
 
@@ -3488,6 +3506,12 @@
 |            2.8284271247462 |
 +----------------------------+
 </programlisting>
+
+            <para>
+              <literal>GLength()</literal> is a non-standard name. It
+              corresponds to the OpenGIS <literal>Length()</literal>
+              function.
+            </para>
           </listitem>
 
           <listitem>
@@ -3504,8 +3528,8 @@
             </para>
 
             <para>
-              Returns the number of points in the
-              <literal>LineString</literal> value
+              Returns the number of <literal>Point</literal> objects in
+              the <literal>LineString</literal> value
               <replaceable>ls</replaceable>.
             </para>
 
@@ -3538,9 +3562,11 @@
             </para>
 
             <para>
-              Returns the <replaceable>n</replaceable>-th point in the
+              Returns the <replaceable>n</replaceable>-th
+              <literal>Point</literal> in the
               <literal>Linestring</literal> value
-              <replaceable>ls</replaceable>. Point numbers begin at 1.
+              <replaceable>ls</replaceable>. Points are numbered
+              beginning with 1.
             </para>
 
             <remark role="help-description-end"/>
@@ -3636,6 +3662,12 @@
         <itemizedlist>
 
           <listitem>
+            <remark role="note">
+              There is no help-table markup for GLength because there is
+              another marked-up entry in the LineString functions
+              section.
+            </remark>
+
             <para>
               <indexterm type="function">
                 <primary>GLength()</primary>
@@ -3661,6 +3693,12 @@
 |             4.2426406871193 |
 +-----------------------------+
 </programlisting>
+
+            <para>
+              <literal>GLength()</literal> is a non-standard name. It
+              corresponds to the OpenGIS <literal>Length()</literal>
+              function.
+            </para>
           </listitem>
 
           <listitem>
@@ -3679,8 +3717,8 @@
               <literal>EndPoint()</literal> values are the same for each
               <literal>LineString</literal> in
               <replaceable>mls</replaceable>). Returns 0 if
-              <replaceable>mls</replaceable> is not closed, and &minus;1 if
-              it is <literal>NULL</literal>.
+              <replaceable>mls</replaceable> is not closed, and &minus;1
+              if it is <literal>NULL</literal>.
             </para>
 
 <programlisting>
@@ -3798,7 +3836,8 @@
               Returns the <replaceable>n</replaceable>-th interior ring
               for the <literal>Polygon</literal> value
               <replaceable>poly</replaceable> as a
-              <literal>LineString</literal>. Ring numbers begin at 1.
+              <literal>LineString</literal>. Rings are numbered
+              beginning with 1.
             </para>
 
             <remark role="help-description-end"/>
@@ -3969,8 +4008,8 @@
             <para>
               Returns the <replaceable>n</replaceable>-th geometry in
               the <literal>GeometryCollection</literal> value
-              <replaceable>gc</replaceable>. Geometry numbers begin at
-              1.
+              <replaceable>gc</replaceable>. Geometries are numbered
+              beginning with 1.
             </para>
 
             <remark role="help-description-end"/>
@@ -4041,9 +4080,9 @@
         <title>&title-functions-that-produce-new-geometries;</title>
 
         <para>
-          In <xref linkend="geometry-property-functions"/>,
-          we've discussed some functions that can construct new
-          geometries from the existing ones:
+          <xref linkend="geometry-property-functions"/>, discusses
+          several functions that construct new geometries from existing
+          ones. See that section for descriptions of these functions:
         </para>
 
         <itemizedlist>
@@ -4272,9 +4311,10 @@
       <remark role="help-category" condition="MBR@Geographic Features"/>
 
       <para>
-        MySQL provides some functions that can test relations between
+        MySQL provides several functions that test relations between
         minimal bounding rectangles of two geometries
-        <literal>g1</literal> and <literal>g2</literal>. They include:
+        <literal>g1</literal> and <literal>g2</literal>. The return
+        values 1 and 0 indicate true and false, respectively.
       </para>
 
       <itemizedlist>
@@ -4293,10 +4333,9 @@
           </para>
 
           <para>
-            Returns 1 or 0 to indicate whether or not the Minimum
-            Bounding Rectangle of <replaceable>g1</replaceable> contains
-            the Minimum Bounding Rectangle of
-            <replaceable>g2</replaceable>.
+            Returns 1 or 0 to indicate whether the Minimum Bounding
+            Rectangle of <replaceable>g1</replaceable> contains the
+            Minimum Bounding Rectangle of <replaceable>g2</replaceable>.
           </para>
 
           <remark role="help-description-end"/>
@@ -4329,8 +4368,8 @@
           </para>
 
           <para>
-            Returns 1 or 0 to indicate whether or not the Minimum
-            Bounding Rectangles of the two geometries
+            Returns 1 or 0 to indicate whether the Minimum Bounding
+            Rectangles of the two geometries
             <replaceable>g1</replaceable> and
             <replaceable>g2</replaceable> are disjoint (do not
             intersect).
@@ -4353,8 +4392,8 @@
           </para>
 
           <para>
-            Returns 1 or 0 to indicate whether or not the Minimum
-            Bounding Rectangles of the two geometries
+            Returns 1 or 0 to indicate whether the Minimum Bounding
+            Rectangles of the two geometries
             <replaceable>g1</replaceable> and
             <replaceable>g2</replaceable> are the same.
           </para>
@@ -4376,8 +4415,8 @@
           </para>
 
           <para>
-            Returns 1 or 0 to indicate whether or not the Minimum
-            Bounding Rectangles of the two geometries
+            Returns 1 or 0 to indicate whether the Minimum Bounding
+            Rectangles of the two geometries
             <replaceable>g1</replaceable> and
             <replaceable>g2</replaceable> intersect.
           </para>
@@ -4399,8 +4438,8 @@
           </para>
 
           <para>
-            Returns 1 or 0 to indicate whether or not the Minimum
-            Bounding Rectangles of the two geometries
+            Returns 1 or 0 to indicate whether the Minimum Bounding
+            Rectangles of the two geometries
             <replaceable>g1</replaceable> and
             <replaceable>g2</replaceable> overlap.
           </para>
@@ -4422,8 +4461,8 @@
           </para>
 
           <para>
-            Returns 1 or 0 to indicate whether or not the Minimum
-            Bounding Rectangles of the two geometries
+            Returns 1 or 0 to indicate whether the Minimum Bounding
+            Rectangles of the two geometries
             <replaceable>g1</replaceable> and
             <replaceable>g2</replaceable> touch.
           </para>
@@ -4445,10 +4484,9 @@
           </para>
 
           <para>
-            Returns 1 or 0 to indicate whether or not the Minimum
-            Bounding Rectangle of <replaceable>g1</replaceable> is
-            within the Minimum Bounding Rectangle of
-            <replaceable>g2</replaceable>.
+            Returns 1 or 0 to indicate whether the Minimum Bounding
+            Rectangle of <replaceable>g1</replaceable> is within the
+            Minimum Bounding Rectangle of <replaceable>g2</replaceable>.
           </para>
 
           <remark role="help-description-end"/>
@@ -4476,10 +4514,15 @@
       <title>&title-functions-that-test-spatial-relationships-between-geometries;</title>
 
       <para>
-        The OpenGIS specification defines the following functions.
-        Currently, MySQL does not implement them according to the
-        specification. Those that are implemented return the same result
-        as the corresponding MBR-based functions. This includes
+        The OpenGIS specification defines the following functions. They
+        test the relationship between two geometry values
+        <literal>g1</literal> and <literal>g2</literal>.
+      </para>
+
+      <para>
+        Currently, MySQL does not implement these functions according to
+        the specification. Those that are implemented return the same
+        result as the corresponding MBR-based functions. This includes
         functions in the following list other than
         <literal>Distance()</literal> and <literal>Related()</literal>.
       </para>
@@ -4495,8 +4538,7 @@
       </para>
 
       <para>
-        The functions operate on two geometry values
-        <literal>g1</literal> and <literal>g2</literal>.
+        The return values 1 and 0 indicate true and false, respectively.
       </para>
 
       <remark role="help-category" condition="Geometry relations@Geographic Features"/>
@@ -4517,7 +4559,7 @@
           </para>
 
           <para>
-            Returns 1 or 0 to indicate whether or not
+            Returns 1 or 0 to indicate whether
             <replaceable>g1</replaceable> completely contains
             <replaceable>g2</replaceable>.
           </para>
@@ -4596,7 +4638,7 @@
           </para>
 
           <para>
-            Returns 1 or 0 to indicate whether or not
+            Returns 1 or 0 to indicate whether
             <replaceable>g1</replaceable> is spatially disjoint from
             (does not intersect) <replaceable>g2</replaceable>.
           </para>
@@ -4638,7 +4680,7 @@
           </para>
 
           <para>
-            Returns 1 or 0 to indicate whether or not
+            Returns 1 or 0 to indicate whether
             <replaceable>g1</replaceable> is spatially equal to
             <replaceable>g2</replaceable>.
           </para>
@@ -4660,7 +4702,7 @@
           </para>
 
           <para>
-            Returns 1 or 0 to indicate whether or not
+            Returns 1 or 0 to indicate whether
             <replaceable>g1</replaceable> spatially intersects
             <replaceable>g2</replaceable>.
           </para>
@@ -4682,7 +4724,7 @@
           </para>
 
           <para>
-            Returns 1 or 0 to indicate whether or not
+            Returns 1 or 0 to indicate whether
             <replaceable>g1</replaceable> spatially overlaps
             <replaceable>g2</replaceable>. The term <emphasis>spatially
             overlaps</emphasis> is used if two geometries intersect and
@@ -4708,14 +4750,13 @@
           </para>
 
           <para>
-            Returns 1 or 0 to indicate whether or not the spatial
-            relationship specified by
-            <replaceable>pattern_matrix</replaceable> exists between
-            <replaceable>g1</replaceable> and
-            <replaceable>g2</replaceable>. Returns &minus;1 if the arguments
-            are <literal>NULL</literal>. The pattern matrix is a string.
-            Its specification will be noted here if this function is
-            implemented.
+            Returns 1 or 0 to indicate whether the spatial relationship
+            specified by <replaceable>pattern_matrix</replaceable>
+            exists between <replaceable>g1</replaceable> and
+            <replaceable>g2</replaceable>. Returns &minus;1 if the
+            arguments are <literal>NULL</literal>. The pattern matrix is
+            a string. Its specification will be noted here if this
+            function is implemented.
           </para>
         </listitem>
 
@@ -4733,7 +4774,7 @@
           </para>
 
           <para>
-            Returns 1 or 0 to indicate whether or not
+            Returns 1 or 0 to indicate whether
             <replaceable>g1</replaceable> spatially touches
             <replaceable>g2</replaceable>. Two geometries
             <emphasis>spatially touch</emphasis> if the interiors of the
@@ -4759,7 +4800,7 @@
           </para>
 
           <para>
-            Returns 1 or 0 to indicate whether or not
+            Returns 1 or 0 to indicate whether
             <replaceable>g1</replaceable> is spatially within
             <replaceable>g2</replaceable>.
           </para>
@@ -4837,10 +4878,10 @@
       <para>
         MySQL can create spatial indexes using syntax similar to that
         for creating regular indexes, but extended with the
-        <literal>SPATIAL</literal> keyword. Spatial columns that are
-        indexed currently must be declared <literal>NOT NULL</literal>.
+        <literal>SPATIAL</literal> keyword. Currently, spatial columns
+        that are indexed must be declared <literal>NOT NULL</literal>.
         The following examples demonstrate how to create spatial
-        indexes.
+        indexes:
       </para>
 
       <itemizedlist>
@@ -4851,7 +4892,7 @@
           </para>
 
 <programlisting>
-mysql&gt; <userinput>CREATE TABLE geom (g GEOMETRY NOT NULL, SPATIAL INDEX(g));</userinput>
+CREATE TABLE geom (g GEOMETRY NOT NULL, SPATIAL INDEX(g));
 </programlisting>
         </listitem>
 
@@ -4861,7 +4902,7 @@
           </para>
 
 <programlisting>
-mysql&gt; <userinput>ALTER TABLE geom ADD SPATIAL INDEX(g);</userinput>
+ALTER TABLE geom ADD SPATIAL INDEX(g);
 </programlisting>
         </listitem>
 
@@ -4871,7 +4912,7 @@
           </para>
 
 <programlisting>
-mysql&gt; <userinput>CREATE SPATIAL INDEX sp_index ON geom (g);</userinput>
+CREATE SPATIAL INDEX sp_index ON geom (g);
 </programlisting>
         </listitem>
 
@@ -4880,7 +4921,7 @@
       <para>
         For <literal>MyISAM</literal> tables, <literal>SPATIAL
         INDEX</literal> creates an R-tree index. For other storage
-        engines that support spatial index, <literal>SPATIAL
+        engines that support spatial indexing, <literal>SPATIAL
         INDEX</literal> creates a B-tree index. A B-tree index on
         spatial values will be useful for exact-value lookups, but not
         for range scans.
@@ -4899,7 +4940,7 @@
           </para>
 
 <programlisting>
-mysql&gt; <userinput>ALTER TABLE geom DROP INDEX g;</userinput>
+ALTER TABLE geom DROP INDEX g;
 </programlisting>
         </listitem>
 
@@ -4909,7 +4950,7 @@
           </para>
 
 <programlisting>
-mysql&gt; <userinput>DROP INDEX sp_index ON geom;</userinput>
+DROP INDEX sp_index ON geom;
 </programlisting>
         </listitem>
 
@@ -4966,13 +5007,15 @@
         be involved in the search for queries that use a function such
         as <literal>MBRContains()</literal> or
         <literal>MBRWithin()</literal> in the <literal>WHERE</literal>
-        clause. For example, let's say we want to find all objects that
-        are in the given rectangle:
+        clause. The following query finds all objects that are in the
+        given rectangle:
       </para>
 
 <programlisting>
+mysql&gt; <userinput>SET @poly =</userinput>
+    -&gt; <userinput>'Polygon((30000 15000,31000 15000,31000 16000,30000 16000,30000 15000))';</userinput>
 mysql&gt; <userinput>SELECT fid,AsText(g) FROM geom WHERE</userinput>
-mysql&gt; <userinput>MBRContains(GeomFromText('Polygon((30000 15000,31000 15000,31000 16000,30000 16000,30000 15000))'),g);</userinput>
+    -&gt; <userinput>MBRContains(GeomFromText(@poly),g);</userinput>
 +-----+-----------------------------------------------------------------------------+
 | fid | AsText(g)                                                                   |
 +-----+-----------------------------------------------------------------------------+
@@ -5001,45 +5044,64 @@
 </programlisting>
 
       <para>
-        Let's use <literal>EXPLAIN</literal> to check the way this query
-        is executed (the <literal>id</literal> column has been removed
-        so the output better fits the page):
+        Use <literal>EXPLAIN</literal> to check the way this query is
+        executed (the <literal>id</literal> column has been removed so
+        the output better fits the page):
       </para>
 
 <programlisting>
+mysql&gt; <userinput>SET @poly =</userinput>
+    -&gt; <userinput>'Polygon((30000 15000,31000 15000,31000 16000,30000 16000,30000 15000))';</userinput>
 mysql&gt; <userinput>EXPLAIN SELECT fid,AsText(g) FROM geom WHERE</userinput>
-mysql&gt; <userinput>MBRContains(GeomFromText('Polygon((30000 15000,31000 15000,31000 16000,30000 16000,30000 15000))'),g);</userinput>
-+-------------+-------+-------+---------------+------+---------+------+------+-------------+
-| select_type | table | type  | possible_keys | key  | key_len | ref  | rows | Extra       |
-+-------------+-------+-------+---------------+------+---------+------+------+-------------+
-| SIMPLE      | geom  | range | g             | g    |      32 | NULL |   50 | Using where |
-+-------------+-------+-------+---------------+------+---------+------+------+-------------+
+    -&gt; <userinput>MBRContains(GeomFromText(@poly),g)\G</userinput>
+*************************** 1. row ***************************
+           id: 1
+  select_type: SIMPLE
+        table: geom
+         type: range
+possible_keys: g
+          key: g
+      key_len: 32
+          ref: NULL
+         rows: 50
+        Extra: Using where
 1 row in set (0.00 sec)
 </programlisting>
 
       <para>
-        Let's check what would happen without a spatial index:
+        Check what would happen without a spatial index:
       </para>
 
 <programlisting>
+mysql&gt; <userinput>SET @poly =</userinput>
+    -&gt; <userinput>'Polygon((30000 15000,31000 15000,31000 16000,30000 16000,30000 15000))';</userinput>
 mysql&gt; <userinput>EXPLAIN SELECT fid,AsText(g) FROM g IGNORE INDEX (g) WHERE</userinput>
-mysql&gt; <userinput>MBRContains(GeomFromText('Polygon((30000 15000,31000 15000,31000 16000,30000 16000,30000 15000))'),g);</userinput>
-+-------------+-------+------+---------------+------+---------+------+-------+-------------+
-| select_type | table | type | possible_keys | key  | key_len | ref  | rows  | Extra       |
-+-------------+-------+------+---------------+------+---------+------+-------+-------------+
-| SIMPLE      | geom  | ALL  | NULL          | NULL |    NULL | NULL | 32376 | Using where |
-+-------------+-------+------+---------------+------+---------+------+-------+-------------+
+    -&gt; <userinput>MBRContains(GeomFromText(@poly),g)\G</userinput>
+*************************** 1. row ***************************
+           id: 1
+  select_type: SIMPLE
+        table: geom
+         type: ALL
+possible_keys: NULL
+          key: NULL
+      key_len: NULL
+          ref: NULL
+         rows: 32376
+        Extra: Using where
 1 row in set (0.00 sec)
 </programlisting>
 
       <para>
-        Let's execute the <literal>SELECT</literal> statement, ignoring
-        the spatial key we have:
+        Executing the <literal>SELECT</literal> statement without the
+        spatial index yields the same result but causes the execution
+        time to rise from 0.00 seconds to 0.46 seconds:
       </para>
 
 <programlisting>
+mysql&gt; <userinput>SET @poly =</userinput>
+    -&gt; <userinput>'Polygon((30000 15000,31000 15000,31000 16000,30000 16000,30000 15000))';</userinput>
 mysql&gt; <userinput>SELECT fid,AsText(g) FROM geom IGNORE INDEX (g) WHERE</userinput>
-mysql&gt; <userinput>MBRContains(GeomFromText('Polygon((30000 15000,31000 15000,31000 16000,30000 16000,30000 15000))'),g);</userinput>
+    -&gt; <userinput>MBRContains(GeomFromText(@poly),g);</userinput>
 +-----+-----------------------------------------------------------------------------+
 | fid | AsText(g)                                                                   |
 +-----+-----------------------------------------------------------------------------+
@@ -5068,11 +5130,6 @@
 </programlisting>
 
       <para>
-        When the index is not used, the execution time for this query
-        rises from 0.00 seconds to 0.46 seconds.
-      </para>
-
-      <para>
         In future releases, spatial indexes may also be used for
         optimizing other functions. See
         <xref linkend="functions-for-testing-spatial-relations-between-geometric-objects"/>.
@@ -5086,72 +5143,65 @@
 
     <title>&title-mysql-gis-conformance-and-compatibility;</title>
 
-    <remark role="todo">
-      Add introductory descriptive sentence.
-    </remark>
+    <para>
+      MySQL does not yet implement the following GIS features:
+    </para>
 
-    <section id="gis-features-that-are-not-yet-implemented">
+    <itemizedlist>
 
-      <title>&title-gis-features-that-are-not-yet-implemented;</title>
+      <listitem>
+        <para>
+          Additional Metadata Views
+        </para>
 
-      <itemizedlist>
+        <para>
+          OpenGIS specifications propose several additional metadata
+          views. For example, a system view named
+          <literal>GEOMETRY_COLUMNS</literal> contains a description of
+          geometry columns, one row for each geometry column in the
+          database.
+        </para>
 
-        <listitem>
-          <para>
-            Additional Metadata Views
-          </para>
+        <remark>
+          @item Functions to add/drop spatial columns OpenGIS assumes
+          that columns can be added or dropped using special
+          @code{AddGeometryColumn()} and @code{DropGeometryColumn()}
+          functions. In MySQL, this is done using the @code{ALTER
+          TABLE}, @code{CREATE INDEX}, and @code{DROP INDEX} statements
+          instead. @item Factors related to Spatial Reference Systems
+          and their IDs (SRIDs): @itemize @bullet @item Functions like
+          @code{Length()} and @code{Area()} assume a planar coordinate
+          system. @item All objects currently are considered to be in
+          the same planar coordinate system. @end itemize
+        </remark>
+      </listitem>
 
-          <para>
-            OpenGIS specifications propose several additional metadata
-            views. For example, a system view named
-            <literal>GEOMETRY_COLUMNS</literal> contains a description
-            of geometry columns, one row for each geometry column in the
-            database.
-          </para>
+      <listitem>
+        <para>
+          The OpenGIS function <literal>Length()</literal> on
+          <literal>LineString</literal> and
+          <literal>MultiLineString</literal> currently should be called
+          in MySQL as <literal>GLength()</literal>
+        </para>
 
-          <remark>
-            @item Functions to add/drop spatial columns OpenGIS assumes
-            that columns can be added or dropped using special
-            @code{AddGeometryColumn()} and @code{DropGeometryColumn()}
-            functions. In MySQL, this is done using the @code{ALTER
-            TABLE}, @code{CREATE INDEX}, and @code{DROP INDEX}
-            statements instead. @item Factors related to Spatial
-            Reference Systems and their IDs (SRIDs): @itemize @bullet
-            @item Functions like @code{Length()} and @code{Area()}
-            assume a planar coordinate system. @item All objects
-            currently are considered to be in the same planar coordinate
-            system. @end itemize
-          </remark>
-        </listitem>
+        <para>
+          The problem is that there is an existing SQL function
+          <literal>Length()</literal> that calculates the length of
+          string values, and sometimes it is not possible to distinguish
+          whether the function is called in a textual or spatial
+          context. We need either to solve this somehow, or decide on
+          another function name.
+        </para>
+      </listitem>
 
-        <listitem>
-          <para>
-            The OpenGIS function <literal>Length()</literal> on
-            <literal>LineString</literal> and
-            <literal>MultiLineString</literal> currently should be
-            called in MySQL as <literal>GLength()</literal>
-          </para>
+    </itemizedlist>
 
-          <para>
-            The problem is that there is an existing SQL function
-            <literal>Length()</literal> which calculates the length of
-            string values, and sometimes it is not possible to
-            distinguish whether the function is called in a textual or
-            spatial context. We need either to solve this somehow, or
-            decide on another function name.
-          </para>
-        </listitem>
+    <remark>
+      @node GIS writing a GIS application @section Writing a GIS
+      Application @node GIS Java GIS Object Model @section Java GIS
+      Object Model
+    </remark>
 
-      </itemizedlist>
-
-      <remark>
-        @node GIS writing a GIS application @section Writing a GIS
-        Application @node GIS Java GIS Object Model @section Java GIS
-        Object Model
-      </remark>
-
-    </section>
-
   </section>
 
 </chapter>

Modified: trunk/refman-5.1/renamed-nodes.txt
===================================================================
--- trunk/refman-5.1/renamed-nodes.txt	2006-01-19 15:38:42 UTC (rev 929)
+++ trunk/refman-5.1/renamed-nodes.txt	2006-01-19 15:38:54 UTC (rev 930)
@@ -102,3 +102,7 @@
 charset-config-file adding-character-set
 open-tables table-cache
 variables user-variables
+fetching-spatial-data-in-internal-format fetching-spatial-data
+fetching-spatial-data-in-wkb-format fetching-spatial-data
+fetching-spatial-data-in-wkt-format fetching-spatial-data
+gis-features-that-are-not-yet-implemented mysql-gis-conformance-and-compatibility

Modified: trunk/refman-5.1/spatial-extensions.xml
===================================================================
--- trunk/refman-5.1/spatial-extensions.xml	2006-01-19 15:38:42 UTC (rev 929)
+++ trunk/refman-5.1/spatial-extensions.xml	2006-01-19 15:38:54 UTC (rev 930)
@@ -72,20 +72,31 @@
 
   <para>
     <emphasis role="bold">Additional resources</emphasis>
+  </para>
 
-    <itemizedlist>
+  <itemizedlist>
 
-      <listitem>
-        <para>
-          If you have questions or concerns about the use of the spatial
-          extensions to MySQL, you can discuss these in the GIS forum:
-          <ulink url="&base-url-forum-list;?23"/>.
-        </para>
-      </listitem>
+    <listitem>
+      <para>
+        The Open Geospatial Consortium publishes the
+        <citetitle>OpenGIS&reg; Simple Features Specifications For
+        SQL</citetitle>, a document that proposes several conceptual
+        ways for extending an SQL RDBMS to support spatial data. This
+        specification is available from the OGC Web site at
+        <ulink url="http://www.opengis.org/docs/99-049.pdf"/>.
+      </para>
+    </listitem>
 
-    </itemizedlist>
-  </para>
+    <listitem>
+      <para>
+        If you have questions or concerns about the use of the spatial
+        extensions to MySQL, you can discuss them in the GIS forum:
+        <ulink url="&base-url-forum-list;?23"/>.
+      </para>
+    </listitem>
 
+  </itemizedlist>
+
   <section id="gis-introduction">
 
     <title>&title-gis-introduction;</title>
@@ -104,20 +115,20 @@
 
     <para>
       MySQL implements spatial extensions following the specification of
-      the <literal>Open GIS Consortium</literal> (OGC). This is an
-      international consortium of more than 250 companies, agencies, and
-      universities participating in the development of publicly
-      available conceptual solutions that can be useful with all kinds
-      of applications that manage spatial data. The OGC maintains a Web
-      site at <ulink url="http://www.opengis.org/"/>.
+      the Open Geospatial Consortium (OGC). This is an international
+      consortium of more than 250 companies, agencies, and universities
+      participating in the development of publicly available conceptual
+      solutions that can be useful with all kinds of applications that
+      manage spatial data. The OGC maintains a Web site at
+      <ulink url="http://www.opengis.org/"/>.
     </para>
 
     <para>
-      In 1997, the Open GIS Consortium published the
+      In 1997, the Open Geospatial Consortium published the
       <citetitle>OpenGIS&reg; Simple Features Specifications For
       SQL</citetitle>, a document that proposes several conceptual ways
       for extending an SQL RDBMS to support spatial data. This
-      specification is available from the Open GIS Web site at
+      specification is available from the OGC Web site at
       <ulink url="http://www.opengis.org/docs/99-049.pdf"/>. It contains
       additional information relevant to this chapter.
     </para>
@@ -127,7 +138,7 @@
       Geometry Types</emphasis> environment proposed by OGC. This term
       refers to an SQL environment that has been extended with a set of
       geometry types. A geometry-valued SQL column is implemented as a
-      column that has a geometry type. The specifications describe a set
+      column that has a geometry type. The specification describe a set
       of SQL geometry types, as well as functions on those types to
       create and analyze geometry values.
     </para>
@@ -169,9 +180,8 @@
     </indexterm>
 
     <para>
-      You can also find documents that use the term
-      <emphasis role="bold">geospatial feature</emphasis> to refer to
-      geographic features.
+      Some documents use the term <emphasis role="bold">geospatial
+      feature</emphasis> to refer to geographic features.
     </para>
 
     <indexterm>
@@ -191,16 +201,12 @@
       <emphasis role="bold">geographic feature</emphasis>,
       <emphasis role="bold">geospatial feature</emphasis>,
       <emphasis role="bold">feature</emphasis>, or
-      <emphasis role="bold">geometry</emphasis>. The term most commonly
-      used here is <emphasis role="bold">geometry</emphasis>.
+      <emphasis role="bold">geometry</emphasis>. Here, the term most
+      commonly used is <emphasis role="bold">geometry</emphasis>,
+      defined as <emphasis>a point or an aggregate of points
+      representing anything in the world that has a location</emphasis>.
     </para>
 
-    <para>
-      Let's define a <emphasis role="bold">geometry</emphasis> as
-      <emphasis>a point or an aggregate of points representing anything
-      in the world that has a location</emphasis>.
-    </para>
-
   </section>
 
   <section id="opengis-geometry-model">
@@ -370,7 +376,7 @@
       <remark role="help-description-begin"/>
 
       <para>
-        <literal>Geometry</literal> is the base class. It's an abstract
+        <literal>Geometry</literal> is the base class. It is an abstract
         class. The instantiable subclasses of
         <literal>Geometry</literal> are restricted to zero-, one-, and
         two-dimensional geometric objects that exist in two-dimensional
@@ -461,8 +467,8 @@
         It is a non-instantiable class but has a number of properties
         that are common to all geometry values created from any of the
         <literal>Geometry</literal> subclasses. These properties are
-        described in the following list. (Particular subclasses have
-        their own specific properties, described later.)
+        described in the following list. Particular subclasses have
+        their own specific properties, described later.
       </para>
 
       <para>
@@ -1424,7 +1430,7 @@
       </remark>
 
       <para>
-        Examples of WKT representations of geometry objects are:
+        Examples of WKT representations of geometry objects:
       </para>
 
       <itemizedlist>
@@ -1530,7 +1536,7 @@
 
       <para>
         A Backus-Naur grammar that specifies the formal production rules
-        for writing WKT values can be found in the OGC specification
+        for writing WKT values can be found in the OpenGIS specification
         document referenced near the beginning of this chapter.
       </para>
 
@@ -1550,8 +1556,8 @@
 
       <para>
         The Well-Known Binary (WKB) representation for geometric values
-        is defined by the OpenGIS specifications. It is also defined in
-        the ISO <quote>SQL/MM Part 3: Spatial</quote> standard.
+        is defined by the OpenGIS specification. It is also defined in
+        the ISO <citetitle>SQL/MM Part 3: Spatial</citetitle> standard.
       </para>
 
       <para>
@@ -1765,8 +1771,8 @@
 
       <para>
         <literal>GEOMETRY</literal> can store geometry values of any
-        type. The other single-value types, <literal>POINT</literal> and
-        <literal>LINESTRING</literal> and <literal>POLYGON</literal>,
+        type. The other single-value types (<literal>POINT</literal>,
+        <literal>LINESTRING</literal>, and <literal>POLYGON</literal>)
         restrict their values to a particular geometry type.
       </para>
 
@@ -1804,11 +1810,11 @@
 
       <para>
         <literal>GEOMETRYCOLLECTION</literal> can store a collection of
-        objects of any type. The other collection types,
-        <literal>MULTIPOINT</literal> and
-        <literal>MULTILINESTRING</literal> and
-        <literal>MULTIPOLYGON</literal> and
-        <literal>GEOMETRYCOLLECTION</literal>, restrict collection
+        objects of any type. The other collection types
+        (<literal>MULTIPOINT</literal>,
+        <literal>MULTILINESTRING</literal>,
+        <literal>MULTIPOLYGON</literal>, and
+        <literal>GEOMETRYCOLLECTION</literal>) restrict collection
         members to those having a particular geometry type.
       </para>
 
@@ -2080,12 +2086,13 @@
         </itemizedlist>
 
         <para>
-          The OpenGIS specification also describes optional functions
-          for constructing <literal>Polygon</literal> or
+          The OpenGIS specification also defines the following optional
+          functions, which MySQL does not implement. These functions
+          construct <literal>Polygon</literal> or
           <literal>MultiPolygon</literal> values based on the WKT
           representation of a collection of rings or closed
           <literal>LineString</literal> values. These values may
-          intersect. MySQL does not implement these functions:
+          intersect.
         </para>
 
         <itemizedlist>
@@ -2442,14 +2449,15 @@
         <title>&title-gis-mysql-specific-functions;</title>
 
         <para>
-          MySQL provides a set of useful functions for creating geometry
-          WKB representations. The functions described in this section
-          are MySQL extensions to the OpenGIS specifications. The
-          results of these functions are <literal>BLOB</literal> values
-          containing WKB representations of geometry values with no
-          SRID. The results of these functions can be substituted as the
-          first argument for any function in the
-          <literal>GeomFromWKB()</literal> function family.
+          MySQL provides a set of useful non-standard functions for
+          creating geometry WKB representations. The functions described
+          in this section are MySQL extensions to the OpenGIS
+          specification. The results of these functions are
+          <literal>BLOB</literal> values containing WKB representations
+          of geometry values with no SRID. The results of these
+          functions can be substituted as the first argument for any
+          function in the <literal>GeomFromWKB()</literal> function
+          family.
         </para>
 
         <remark role="help-category" condition="Geometry constructors@Geographic Features"/>
@@ -2658,8 +2666,7 @@
           <remark role="help-example"/>
 
 <programlisting>
-mysql&gt; <userinput>CREATE TABLE geom (g GEOMETRY);</userinput>
-Query OK, 0 rows affected (0.02 sec)
+CREATE TABLE geom (g GEOMETRY);
 </programlisting>
         </listitem>
 
@@ -2670,12 +2677,8 @@
           </para>
 
 <programlisting>
-mysql&gt; <userinput>ALTER TABLE geom ADD pt POINT;</userinput>
-Query OK, 0 rows affected (0.00 sec)
-Records: 0  Duplicates: 0  Warnings: 0
-mysql&gt; <userinput>ALTER TABLE geom DROP pt;</userinput>
-Query OK, 0 rows affected (0.00 sec)
-Records: 0  Duplicates: 0  Warnings: 0
+ALTER TABLE geom ADD pt POINT;
+ALTER TABLE geom DROP pt;
 </programlisting>
         </listitem>
 
@@ -2697,31 +2700,39 @@
         convert them to that format from either Well-Known Text (WKT) or
         Well-Known Binary (WKB) format. The following examples
         demonstrate how to insert geometry values into a table by
-        converting WKT values into internal geometry format.
+        converting WKT values into internal geometry format:
       </para>
 
-      <para>
-        You can perform the conversion directly in the
-        <literal>INSERT</literal> statement:
-      </para>
+      <itemizedlist>
 
+        <listitem>
+          <para>
+            Perform the conversion directly in the
+            <literal>INSERT</literal> statement:
+          </para>
+
 <programlisting>
 INSERT INTO geom VALUES (GeomFromText('POINT(1 1)'));
 
 SET @g = 'POINT(1 1)';
 INSERT INTO geom VALUES (GeomFromText(@g));
 </programlisting>
+        </listitem>
 
-      <para>
-        Or you can perform the conversion prior to the
-        <literal>INSERT</literal>:
-      </para>
+        <listitem>
+          <para>
+            Perform the conversion prior to the
+            <literal>INSERT</literal>:
+          </para>
 
 <programlisting>
 SET @g = GeomFromText('POINT(1 1)');
 INSERT INTO geom VALUES (@g);
 </programlisting>
+        </listitem>
 
+      </itemizedlist>
+
       <para>
         The following examples insert more complex geometries into the
         table:
@@ -2821,51 +2832,55 @@
         format. You can also convert them into WKT or WKB format.
       </para>
 
-      <section id="fetching-spatial-data-in-internal-format">
+      <itemizedlist>
 
-        <title>&title-fetching-spatial-data-in-internal-format;</title>
+        <listitem>
+          <para>
+            Fetching spatial data in internal format:
+          </para>
 
-        <para>
-          Fetching geometry values using internal format can be useful
-          in table-to-table transfers:
-        </para>
+          <para>
+            Fetching geometry values using internal format can be useful
+            in table-to-table transfers:
+          </para>
 
 <programlisting>
 CREATE TABLE geom2 (g GEOMETRY) SELECT g FROM geom;
 </programlisting>
+        </listitem>
 
-      </section>
+        <listitem>
+          <para>
+            Fetching spatial data in WKT format:
+          </para>
 
-      <section id="fetching-spatial-data-in-wkt-format">
+          <para>
+            The <literal>AsText()</literal> function converts a geometry
+            from internal format into a WKT string.
+          </para>
 
-        <title>&title-fetching-spatial-data-in-wkt-format;</title>
-
-        <para>
-          The <literal>AsText()</literal> function converts a geometry
-          from internal format into a WKT string.
-        </para>
-
 <programlisting>
 SELECT AsText(g) FROM geom;
 </programlisting>
+        </listitem>
 
-      </section>
+        <listitem>
+          <para>
+            Fetching spatial data in WKB format:
+          </para>
 
-      <section id="fetching-spatial-data-in-wkb-format">
+          <para>
+            The <literal>AsBinary()</literal> function converts a
+            geometry from internal format into a <literal>BLOB</literal>
+            containing the WKB value.
+          </para>
 
-        <title>&title-fetching-spatial-data-in-wkb-format;</title>
-
-        <para>
-          The <literal>AsBinary()</literal> function converts a geometry
-          from internal format into a <literal>BLOB</literal> containing
-          the WKB value.
-        </para>
-
 <programlisting>
 SELECT AsBinary(g) FROM geom;
 </programlisting>
+        </listitem>
 
-      </section>
+      </itemizedlist>
 
     </section>
 
@@ -3023,7 +3038,7 @@
             internal geometry format and returns the result. A number of
             type-specific functions are also supported, such as
             <literal>PointFromText()</literal> and
-            <literal>LineFromText()</literal>; see
+            <literal>LineFromText()</literal>. See
             <xref linkend="gis-wkt-functions"/>.
           </para>
         </listitem>
@@ -3042,7 +3057,7 @@
             internal geometry format and returns the result. A number of
             type-specific functions are also supported, such as
             <literal>PointFromWKB()</literal> and
-            <literal>LineFromWKB()</literal>; see
+            <literal>LineFromWKB()</literal>. See
             <xref linkend="gis-wkb-functions"/>.
           </para>
         </listitem>
@@ -3094,9 +3109,9 @@
 
             <para>
               Returns the inherent dimension of the geometry value
-              <replaceable>g</replaceable>. The result can be &minus;1, 0,
-              1, or 2. (The meaning of these values is given in
-              <xref linkend="gis-class-geometry"/>.)
+              <replaceable>g</replaceable>. The result can be &minus;1,
+              0, 1, or 2. The meaning of these values is given in
+              <xref linkend="gis-class-geometry"/>.
             </para>
 
             <remark role="help-description-end"/>
@@ -3313,7 +3328,8 @@
               The description of each instantiable geometric class given
               earlier in the chapter includes the specific conditions
               that cause an instance of that class to be classified as
-              not simple.
+              not simple. (See
+              <xref linkend= "gis-geometry-class-hierarchy"/>.)
             </para>
 
             <remark role="help-description-end"/>
@@ -3359,12 +3375,13 @@
             <remark role="help-example"/>
 
 <programlisting>
-mysql&gt; <userinput>SELECT X(GeomFromText('Point(56.7 53.34)'));</userinput>
-+--------------------------------------+
-| X(GeomFromText('Point(56.7 53.34)')) |
-+--------------------------------------+
-|                                 56.7 |
-+--------------------------------------+
+mysql&gt; <userinput>SET @pt = 'Point(56.7 53.34)';</userinput>
+mysql&gt; <userinput>SELECT X(GeomFromText(@pt));</userinput>
++----------------------+
+| X(GeomFromText(@pt)) |
++----------------------+
+|                 56.7 |
++----------------------+
 </programlisting>
           </listitem>
 
@@ -3391,12 +3408,13 @@
             <remark role="help-example"/>
 
 <programlisting>
-mysql&gt; <userinput>SELECT Y(GeomFromText('Point(56.7 53.34)'));</userinput>
-+--------------------------------------+
-| Y(GeomFromText('Point(56.7 53.34)')) |
-+--------------------------------------+
-|                                53.34 |
-+--------------------------------------+
+mysql&gt; <userinput>SET @pt = 'Point(56.7 53.34)';</userinput>
+mysql&gt; <userinput>SELECT Y(GeomFromText(@pt));</userinput>
++----------------------+
+| Y(GeomFromText(@pt)) |
++----------------------+
+|                53.34 |
++----------------------+
 </programlisting>
           </listitem>
 
@@ -3486,6 +3504,12 @@
 |            2.8284271247462 |
 +----------------------------+
 </programlisting>
+
+            <para>
+              <literal>GLength()</literal> is a non-standard name. It
+              corresponds to the OpenGIS <literal>Length()</literal>
+              function.
+            </para>
           </listitem>
 
           <listitem>
@@ -3502,8 +3526,8 @@
             </para>
 
             <para>
-              Returns the number of points in the
-              <literal>LineString</literal> value
+              Returns the number of <literal>Point</literal> objects in
+              the <literal>LineString</literal> value
               <replaceable>ls</replaceable>.
             </para>
 
@@ -3536,9 +3560,11 @@
             </para>
 
             <para>
-              Returns the <replaceable>n</replaceable>-th point in the
+              Returns the <replaceable>n</replaceable>-th
+              <literal>Point</literal> in the
               <literal>Linestring</literal> value
-              <replaceable>ls</replaceable>. Point numbers begin at 1.
+              <replaceable>ls</replaceable>. Points are numbered
+              beginning with 1.
             </para>
 
             <remark role="help-description-end"/>
@@ -3634,6 +3660,12 @@
         <itemizedlist>
 
           <listitem>
+            <remark role="note">
+              There is no help-table markup for GLength because there is
+              another marked-up entry in the LineString functions
+              section.
+            </remark>
+
             <para>
               <indexterm type="function">
                 <primary>GLength()</primary>
@@ -3659,6 +3691,12 @@
 |             4.2426406871193 |
 +-----------------------------+
 </programlisting>
+
+            <para>
+              <literal>GLength()</literal> is a non-standard name. It
+              corresponds to the OpenGIS <literal>Length()</literal>
+              function.
+            </para>
           </listitem>
 
           <listitem>
@@ -3677,8 +3715,8 @@
               <literal>EndPoint()</literal> values are the same for each
               <literal>LineString</literal> in
               <replaceable>mls</replaceable>). Returns 0 if
-              <replaceable>mls</replaceable> is not closed, and &minus;1 if
-              it is <literal>NULL</literal>.
+              <replaceable>mls</replaceable> is not closed, and &minus;1
+              if it is <literal>NULL</literal>.
             </para>
 
 <programlisting>
@@ -3796,7 +3834,8 @@
               Returns the <replaceable>n</replaceable>-th interior ring
               for the <literal>Polygon</literal> value
               <replaceable>poly</replaceable> as a
-              <literal>LineString</literal>. Ring numbers begin at 1.
+              <literal>LineString</literal>. Rings are numbered
+              beginning with 1.
             </para>
 
             <remark role="help-description-end"/>
@@ -3967,8 +4006,8 @@
             <para>
               Returns the <replaceable>n</replaceable>-th geometry in
               the <literal>GeometryCollection</literal> value
-              <replaceable>gc</replaceable>. Geometry numbers begin at
-              1.
+              <replaceable>gc</replaceable>. Geometries are numbered
+              beginning with 1.
             </para>
 
             <remark role="help-description-end"/>
@@ -4039,9 +4078,9 @@
         <title>&title-functions-that-produce-new-geometries;</title>
 
         <para>
-          In <xref linkend="geometry-property-functions"/>,
-          we've discussed some functions that can construct new
-          geometries from the existing ones:
+          <xref linkend="geometry-property-functions"/>, discusses
+          several functions that construct new geometries from existing
+          ones. See that section for descriptions of these functions:
         </para>
 
         <itemizedlist>
@@ -4270,9 +4309,10 @@
       <remark role="help-category" condition="MBR@Geographic Features"/>
 
       <para>
-        MySQL provides some functions that can test relations between
+        MySQL provides several functions that test relations between
         minimal bounding rectangles of two geometries
-        <literal>g1</literal> and <literal>g2</literal>. They include:
+        <literal>g1</literal> and <literal>g2</literal>. The return
+        values 1 and 0 indicate true and false, respectively.
       </para>
 
       <itemizedlist>
@@ -4291,10 +4331,9 @@
           </para>
 
           <para>
-            Returns 1 or 0 to indicate whether or not the Minimum
-            Bounding Rectangle of <replaceable>g1</replaceable> contains
-            the Minimum Bounding Rectangle of
-            <replaceable>g2</replaceable>.
+            Returns 1 or 0 to indicate whether the Minimum Bounding
+            Rectangle of <replaceable>g1</replaceable> contains the
+            Minimum Bounding Rectangle of <replaceable>g2</replaceable>.
           </para>
 
           <remark role="help-description-end"/>
@@ -4327,8 +4366,8 @@
           </para>
 
           <para>
-            Returns 1 or 0 to indicate whether or not the Minimum
-            Bounding Rectangles of the two geometries
+            Returns 1 or 0 to indicate whether the Minimum Bounding
+            Rectangles of the two geometries
             <replaceable>g1</replaceable> and
             <replaceable>g2</replaceable> are disjoint (do not
             intersect).
@@ -4351,8 +4390,8 @@
           </para>
 
           <para>
-            Returns 1 or 0 to indicate whether or not the Minimum
-            Bounding Rectangles of the two geometries
+            Returns 1 or 0 to indicate whether the Minimum Bounding
+            Rectangles of the two geometries
             <replaceable>g1</replaceable> and
             <replaceable>g2</replaceable> are the same.
           </para>
@@ -4374,8 +4413,8 @@
           </para>
 
           <para>
-            Returns 1 or 0 to indicate whether or not the Minimum
-            Bounding Rectangles of the two geometries
+            Returns 1 or 0 to indicate whether the Minimum Bounding
+            Rectangles of the two geometries
             <replaceable>g1</replaceable> and
             <replaceable>g2</replaceable> intersect.
           </para>
@@ -4397,8 +4436,8 @@
           </para>
 
           <para>
-            Returns 1 or 0 to indicate whether or not the Minimum
-            Bounding Rectangles of the two geometries
+            Returns 1 or 0 to indicate whether the Minimum Bounding
+            Rectangles of the two geometries
             <replaceable>g1</replaceable> and
             <replaceable>g2</replaceable> overlap.
           </para>
@@ -4420,8 +4459,8 @@
           </para>
 
           <para>
-            Returns 1 or 0 to indicate whether or not the Minimum
-            Bounding Rectangles of the two geometries
+            Returns 1 or 0 to indicate whether the Minimum Bounding
+            Rectangles of the two geometries
             <replaceable>g1</replaceable> and
             <replaceable>g2</replaceable> touch.
           </para>
@@ -4443,10 +4482,9 @@
           </para>
 
           <para>
-            Returns 1 or 0 to indicate whether or not the Minimum
-            Bounding Rectangle of <replaceable>g1</replaceable> is
-            within the Minimum Bounding Rectangle of
-            <replaceable>g2</replaceable>.
+            Returns 1 or 0 to indicate whether the Minimum Bounding
+            Rectangle of <replaceable>g1</replaceable> is within the
+            Minimum Bounding Rectangle of <replaceable>g2</replaceable>.
           </para>
 
           <remark role="help-description-end"/>
@@ -4474,10 +4512,15 @@
       <title>&title-functions-that-test-spatial-relationships-between-geometries;</title>
 
       <para>
-        The OpenGIS specification defines the following functions.
-        Currently, MySQL does not implement them according to the
-        specification. Those that are implemented return the same result
-        as the corresponding MBR-based functions. This includes
+        The OpenGIS specification defines the following functions. They
+        test the relationship between two geometry values
+        <literal>g1</literal> and <literal>g2</literal>.
+      </para>
+
+      <para>
+        Currently, MySQL does not implement these functions according to
+        the specification. Those that are implemented return the same
+        result as the corresponding MBR-based functions. This includes
         functions in the following list other than
         <literal>Distance()</literal> and <literal>Related()</literal>.
       </para>
@@ -4493,8 +4536,7 @@
       </para>
 
       <para>
-        The functions operate on two geometry values
-        <literal>g1</literal> and <literal>g2</literal>.
+        The return values 1 and 0 indicate true and false, respectively.
       </para>
 
       <remark role="help-category" condition="Geometry relations@Geographic Features"/>
@@ -4515,7 +4557,7 @@
           </para>
 
           <para>
-            Returns 1 or 0 to indicate whether or not
+            Returns 1 or 0 to indicate whether
             <replaceable>g1</replaceable> completely contains
             <replaceable>g2</replaceable>.
           </para>
@@ -4594,7 +4636,7 @@
           </para>
 
           <para>
-            Returns 1 or 0 to indicate whether or not
+            Returns 1 or 0 to indicate whether
             <replaceable>g1</replaceable> is spatially disjoint from
             (does not intersect) <replaceable>g2</replaceable>.
           </para>
@@ -4636,7 +4678,7 @@
           </para>
 
           <para>
-            Returns 1 or 0 to indicate whether or not
+            Returns 1 or 0 to indicate whether
             <replaceable>g1</replaceable> is spatially equal to
             <replaceable>g2</replaceable>.
           </para>
@@ -4658,7 +4700,7 @@
           </para>
 
           <para>
-            Returns 1 or 0 to indicate whether or not
+            Returns 1 or 0 to indicate whether
             <replaceable>g1</replaceable> spatially intersects
             <replaceable>g2</replaceable>.
           </para>
@@ -4680,7 +4722,7 @@
           </para>
 
           <para>
-            Returns 1 or 0 to indicate whether or not
+            Returns 1 or 0 to indicate whether
             <replaceable>g1</replaceable> spatially overlaps
             <replaceable>g2</replaceable>. The term <emphasis>spatially
             overlaps</emphasis> is used if two geometries intersect and
@@ -4706,14 +4748,13 @@
           </para>
 
           <para>
-            Returns 1 or 0 to indicate whether or not the spatial
-            relationship specified by
-            <replaceable>pattern_matrix</replaceable> exists between
-            <replaceable>g1</replaceable> and
-            <replaceable>g2</replaceable>. Returns &minus;1 if the arguments
-            are <literal>NULL</literal>. The pattern matrix is a string.
-            Its specification will be noted here if this function is
-            implemented.
+            Returns 1 or 0 to indicate whether the spatial relationship
+            specified by <replaceable>pattern_matrix</replaceable>
+            exists between <replaceable>g1</replaceable> and
+            <replaceable>g2</replaceable>. Returns &minus;1 if the
+            arguments are <literal>NULL</literal>. The pattern matrix is
+            a string. Its specification will be noted here if this
+            function is implemented.
           </para>
         </listitem>
 
@@ -4731,7 +4772,7 @@
           </para>
 
           <para>
-            Returns 1 or 0 to indicate whether or not
+            Returns 1 or 0 to indicate whether
             <replaceable>g1</replaceable> spatially touches
             <replaceable>g2</replaceable>. Two geometries
             <emphasis>spatially touch</emphasis> if the interiors of the
@@ -4757,7 +4798,7 @@
           </para>
 
           <para>
-            Returns 1 or 0 to indicate whether or not
+            Returns 1 or 0 to indicate whether
             <replaceable>g1</replaceable> is spatially within
             <replaceable>g2</replaceable>.
           </para>
@@ -4834,10 +4875,10 @@
       <para>
         MySQL can create spatial indexes using syntax similar to that
         for creating regular indexes, but extended with the
-        <literal>SPATIAL</literal> keyword. Spatial columns that are
-        indexed currently must be declared <literal>NOT NULL</literal>.
+        <literal>SPATIAL</literal> keyword. Currently, spatial columns
+        that are indexed must be declared <literal>NOT NULL</literal>.
         The following examples demonstrate how to create spatial
-        indexes.
+        indexes:
       </para>
 
       <itemizedlist>
@@ -4848,7 +4889,7 @@
           </para>
 
 <programlisting>
-mysql&gt; <userinput>CREATE TABLE geom (g GEOMETRY NOT NULL, SPATIAL INDEX(g));</userinput>
+CREATE TABLE geom (g GEOMETRY NOT NULL, SPATIAL INDEX(g));
 </programlisting>
         </listitem>
 
@@ -4858,7 +4899,7 @@
           </para>
 
 <programlisting>
-mysql&gt; <userinput>ALTER TABLE geom ADD SPATIAL INDEX(g);</userinput>
+ALTER TABLE geom ADD SPATIAL INDEX(g);
 </programlisting>
         </listitem>
 
@@ -4868,7 +4909,7 @@
           </para>
 
 <programlisting>
-mysql&gt; <userinput>CREATE SPATIAL INDEX sp_index ON geom (g);</userinput>
+CREATE SPATIAL INDEX sp_index ON geom (g);
 </programlisting>
         </listitem>
 
@@ -4877,7 +4918,7 @@
       <para>
         For <literal>MyISAM</literal> tables, <literal>SPATIAL
         INDEX</literal> creates an R-tree index. For other storage
-        engines that support spatial index, <literal>SPATIAL
+        engines that support spatial indexing, <literal>SPATIAL
         INDEX</literal> creates a B-tree index. A B-tree index on
         spatial values will be useful for exact-value lookups, but not
         for range scans.
@@ -4896,7 +4937,7 @@
           </para>
 
 <programlisting>
-mysql&gt; <userinput>ALTER TABLE geom DROP INDEX g;</userinput>
+ALTER TABLE geom DROP INDEX g;
 </programlisting>
         </listitem>
 
@@ -4906,7 +4947,7 @@
           </para>
 
 <programlisting>
-mysql&gt; <userinput>DROP INDEX sp_index ON geom;</userinput>
+DROP INDEX sp_index ON geom;
 </programlisting>
         </listitem>
 
@@ -4963,13 +5004,15 @@
         be involved in the search for queries that use a function such
         as <literal>MBRContains()</literal> or
         <literal>MBRWithin()</literal> in the <literal>WHERE</literal>
-        clause. For example, let's say we want to find all objects that
-        are in the given rectangle:
+        clause. The following query finds all objects that are in the
+        given rectangle:
       </para>
 
 <programlisting>
+mysql&gt; <userinput>SET @poly =</userinput>
+    -&gt; <userinput>'Polygon((30000 15000,31000 15000,31000 16000,30000 16000,30000 15000))';</userinput>
 mysql&gt; <userinput>SELECT fid,AsText(g) FROM geom WHERE</userinput>
-mysql&gt; <userinput>MBRContains(GeomFromText('Polygon((30000 15000,31000 15000,31000 16000,30000 16000,30000 15000))'),g);</userinput>
+    -&gt; <userinput>MBRContains(GeomFromText(@poly),g);</userinput>
 +-----+-----------------------------------------------------------------------------+
 | fid | AsText(g)                                                                   |
 +-----+-----------------------------------------------------------------------------+
@@ -4998,45 +5041,64 @@
 </programlisting>
 
       <para>
-        Let's use <literal>EXPLAIN</literal> to check the way this query
-        is executed (the <literal>id</literal> column has been removed
-        so the output better fits the page):
+        Use <literal>EXPLAIN</literal> to check the way this query is
+        executed (the <literal>id</literal> column has been removed so
+        the output better fits the page):
       </para>
 
 <programlisting>
+mysql&gt; <userinput>SET @poly =</userinput>
+    -&gt; <userinput>'Polygon((30000 15000,31000 15000,31000 16000,30000 16000,30000 15000))';</userinput>
 mysql&gt; <userinput>EXPLAIN SELECT fid,AsText(g) FROM geom WHERE</userinput>
-mysql&gt; <userinput>MBRContains(GeomFromText('Polygon((30000 15000,31000 15000,31000 16000,30000 16000,30000 15000))'),g);</userinput>
-+-------------+-------+-------+---------------+------+---------+------+------+-------------+
-| select_type | table | type  | possible_keys | key  | key_len | ref  | rows | Extra       |
-+-------------+-------+-------+---------------+------+---------+------+------+-------------+
-| SIMPLE      | geom  | range | g             | g    |      32 | NULL |   50 | Using where |
-+-------------+-------+-------+---------------+------+---------+------+------+-------------+
+    -&gt; <userinput>MBRContains(GeomFromText(@poly),g)\G</userinput>
+*************************** 1. row ***************************
+           id: 1
+  select_type: SIMPLE
+        table: geom
+         type: range
+possible_keys: g
+          key: g
+      key_len: 32
+          ref: NULL
+         rows: 50
+        Extra: Using where
 1 row in set (0.00 sec)
 </programlisting>
 
       <para>
-        Let's check what would happen without a spatial index:
+        Check what would happen without a spatial index:
       </para>
 
 <programlisting>
+mysql&gt; <userinput>SET @poly =</userinput>
+    -&gt; <userinput>'Polygon((30000 15000,31000 15000,31000 16000,30000 16000,30000 15000))';</userinput>
 mysql&gt; <userinput>EXPLAIN SELECT fid,AsText(g) FROM g IGNORE INDEX (g) WHERE</userinput>
-mysql&gt; <userinput>MBRContains(GeomFromText('Polygon((30000 15000,31000 15000,31000 16000,30000 16000,30000 15000))'),g);</userinput>
-+-------------+-------+------+---------------+------+---------+------+-------+-------------+
-| select_type | table | type | possible_keys | key  | key_len | ref  | rows  | Extra       |
-+-------------+-------+------+---------------+------+---------+------+-------+-------------+
-| SIMPLE      | geom  | ALL  | NULL          | NULL |    NULL | NULL | 32376 | Using where |
-+-------------+-------+------+---------------+------+---------+------+-------+-------------+
+    -&gt; <userinput>MBRContains(GeomFromText(@poly),g)\G</userinput>
+*************************** 1. row ***************************
+           id: 1
+  select_type: SIMPLE
+        table: geom
+         type: ALL
+possible_keys: NULL
+          key: NULL
+      key_len: NULL
+          ref: NULL
+         rows: 32376
+        Extra: Using where
 1 row in set (0.00 sec)
 </programlisting>
 
       <para>
-        Let's execute the <literal>SELECT</literal> statement, ignoring
-        the spatial key we have:
+        Executing the <literal>SELECT</literal> statement without the
+        spatial index yields the same result but causes the execution
+        time to rise from 0.00 seconds to 0.46 seconds:
       </para>
 
 <programlisting>
+mysql&gt; <userinput>SET @poly =</userinput>
+    -&gt; <userinput>'Polygon((30000 15000,31000 15000,31000 16000,30000 16000,30000 15000))';</userinput>
 mysql&gt; <userinput>SELECT fid,AsText(g) FROM geom IGNORE INDEX (g) WHERE</userinput>
-mysql&gt; <userinput>MBRContains(GeomFromText('Polygon((30000 15000,31000 15000,31000 16000,30000 16000,30000 15000))'),g);</userinput>
+    -&gt; <userinput>MBRContains(GeomFromText(@poly),g);</userinput>
 +-----+-----------------------------------------------------------------------------+
 | fid | AsText(g)                                                                   |
 +-----+-----------------------------------------------------------------------------+
@@ -5065,11 +5127,6 @@
 </programlisting>
 
       <para>
-        When the index is not used, the execution time for this query
-        rises from 0.00 seconds to 0.46 seconds.
-      </para>
-
-      <para>
         In future releases, spatial indexes may also be used for
         optimizing other functions. See
         <xref linkend="functions-for-testing-spatial-relations-between-geometric-objects"/>.
@@ -5083,72 +5140,65 @@
 
     <title>&title-mysql-gis-conformance-and-compatibility;</title>
 
-    <remark role="todo">
-      Add introductory descriptive sentence.
-    </remark>
+    <para>
+      MySQL does not yet implement the following GIS features:
+    </para>
 
-    <section id="gis-features-that-are-not-yet-implemented">
+    <itemizedlist>
 
-      <title>&title-gis-features-that-are-not-yet-implemented;</title>
+      <listitem>
+        <para>
+          Additional Metadata Views
+        </para>
 
-      <itemizedlist>
+        <para>
+          OpenGIS specifications propose several additional metadata
+          views. For example, a system view named
+          <literal>GEOMETRY_COLUMNS</literal> contains a description of
+          geometry columns, one row for each geometry column in the
+          database.
+        </para>
 
-        <listitem>
-          <para>
-            Additional Metadata Views
-          </para>
+        <remark>
+          @item Functions to add/drop spatial columns OpenGIS assumes
+          that columns can be added or dropped using special
+          @code{AddGeometryColumn()} and @code{DropGeometryColumn()}
+          functions. In MySQL, this is done using the @code{ALTER
+          TABLE}, @code{CREATE INDEX}, and @code{DROP INDEX} statements
+          instead. @item Factors related to Spatial Reference Systems
+          and their IDs (SRIDs): @itemize @bullet @item Functions like
+          @code{Length()} and @code{Area()} assume a planar coordinate
+          system. @item All objects currently are considered to be in
+          the same planar coordinate system. @end itemize
+        </remark>
+      </listitem>
 
-          <para>
-            OpenGIS specifications propose several additional metadata
-            views. For example, a system view named
-            <literal>GEOMETRY_COLUMNS</literal> contains a description
-            of geometry columns, one row for each geometry column in the
-            database.
-          </para>
+      <listitem>
+        <para>
+          The OpenGIS function <literal>Length()</literal> on
+          <literal>LineString</literal> and
+          <literal>MultiLineString</literal> currently should be called
+          in MySQL as <literal>GLength()</literal>
+        </para>
 
-          <remark>
-            @item Functions to add/drop spatial columns OpenGIS assumes
-            that columns can be added or dropped using special
-            @code{AddGeometryColumn()} and @code{DropGeometryColumn()}
-            functions. In MySQL, this is done using the @code{ALTER
-            TABLE}, @code{CREATE INDEX}, and @code{DROP INDEX}
-            statements instead. @item Factors related to Spatial
-            Reference Systems and their IDs (SRIDs): @itemize @bullet
-            @item Functions like @code{Length()} and @code{Area()}
-            assume a planar coordinate system. @item All objects
-            currently are considered to be in the same planar coordinate
-            system. @end itemize
-          </remark>
-        </listitem>
+        <para>
+          The problem is that there is an existing SQL function
+          <literal>Length()</literal> that calculates the length of
+          string values, and sometimes it is not possible to distinguish
+          whether the function is called in a textual or spatial
+          context. We need either to solve this somehow, or decide on
+          another function name.
+        </para>
+      </listitem>
 
-        <listitem>
-          <para>
-            The OpenGIS function <literal>Length()</literal> on
-            <literal>LineString</literal> and
-            <literal>MultiLineString</literal> currently should be
-            called in MySQL as <literal>GLength()</literal>
-          </para>
+    </itemizedlist>
 
-          <para>
-            The problem is that there is an existing SQL function
-            <literal>Length()</literal> which calculates the length of
-            string values, and sometimes it is not possible to
-            distinguish whether the function is called in a textual or
-            spatial context. We need either to solve this somehow, or
-            decide on another function name.
-          </para>
-        </listitem>
+    <remark>
+      @node GIS writing a GIS application @section Writing a GIS
+      Application @node GIS Java GIS Object Model @section Java GIS
+      Object Model
+    </remark>
 
-      </itemizedlist>
-
-      <remark>
-        @node GIS writing a GIS application @section Writing a GIS
-        Application @node GIS Java GIS Object Model @section Java GIS
-        Object Model
-      </remark>
-
-    </section>
-
   </section>
 
 </chapter>

Modified: trunk/refman-common/titles.en.ent
===================================================================
--- trunk/refman-common/titles.en.ent	2006-01-19 15:38:42 UTC (rev 929)
+++ trunk/refman-common/titles.en.ent	2006-01-19 15:38:54 UTC (rev 930)
@@ -379,9 +379,6 @@
 <!ENTITY title-federated-use "How to use <literal>FEDERATED</literal> Tables">
 <!ENTITY title-fetch "Cursor <literal>FETCH</literal> Statement">
 <!ENTITY title-fetching-spatial-data "Fetching Spatial Data">
-<!ENTITY title-fetching-spatial-data-in-internal-format "Fetching Spatial Data in Internal Format">
-<!ENTITY title-fetching-spatial-data-in-wkb-format "Fetching Spatial Data in WKB Format">
-<!ENTITY title-fetching-spatial-data-in-wkt-format "Fetching Spatial Data in WKT Format">
 <!ENTITY title-file-permissions "Problems with File Permissions">
 <!ENTITY title-file-space-management "<literal>InnoDB</literal> File Space Management and Disk I/O">
 <!ENTITY title-flow-control-constructs "Flow Control Constructs">
@@ -425,7 +422,6 @@
 <!ENTITY title-gis-class-point "Class <literal>Point</literal>">
 <!ENTITY title-gis-class-polygon "Class <literal>Polygon</literal>">
 <!ENTITY title-gis-class-surface "Class <literal>Surface</literal>">
-<!ENTITY title-gis-features-that-are-not-yet-implemented "GIS Features That Are Not Yet Implemented">
 <!ENTITY title-gis-geometry-class-hierarchy "The Geometry Class Hierarchy">
 <!ENTITY title-gis-introduction "Introduction to MySQL Spatial Support">
 <!ENTITY title-gis-mysql-specific-functions "Creating Geometry Values Using MySQL-Specific Functions">
@@ -1251,7 +1247,7 @@
 <!ENTITY title-news-5-1-2 "Changes in release 5.1.2 (Not released)">
 <!ENTITY title-news-5-1-3 "Changes in release 5.1.3 (29 November 2005)">
 <!ENTITY title-news-5-1-4 "Changes in release 5.1.4 (21 December 2005)">
-<!ENTITY title-news-5-1-5 "Changes in release 5.1.5 (Not yet released)">
+<!ENTITY title-news-5-1-5 "Changes in release 5.1.5 (10 January 2006)">
 <!ENTITY title-news-5-1-6 "Changes in release 5.1.6 (Not yet released)">
 <!ENTITY title-news-5-1-x "Changes in release 5.1.x (Development)">
 <!ENTITY title-no-matching-rows "Solving Problems with No Matching Rows">

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