Minor hacking on contrib/cube documentation.

Improve markup, particularly of the table of functions; add or improve
examples for some of the functions; wordsmith some of the function
descriptions.

diff --git a/doc/src/sgml/cube.sgml b/doc/src/sgml/cube.sgml
index 4a093706e4a6d8eb7cdbd1d13f6575ef8bb9297d..1ffc40f1a5b229335e3f5e3a51a58e9b11ef8b7d 100644 (file)
--- a/doc/src/sgml/cube.sgml
+++ b/doc/src/sgml/cube.sgml
@@ -25,6 +25,13 @@
   <table id="cube-repr-table">
    <title>Cube External Representations</title>
    <tgroup cols="2">
+    <thead>
+     <row>
+      <entry>External Syntax</entry>
+      <entry>Meaning</entry>
+     </row>
+    </thead>
+
     <tbody>
      <row>
       <entry><literal><replaceable>x</></literal></entry>
@@ -80,7 +87,8 @@
   </para>
 
   <para>
-   White space is ignored, so <literal>[(<replaceable>x</>),(<replaceable>y</>)]</literal> is the same as
+   White space is ignored on input, so
+   <literal>[(<replaceable>x</>),(<replaceable>y</>)]</literal> is the same as
    <literal>[ ( <replaceable>x</> ), ( <replaceable>y</> ) ]</literal>.
   </para>
  </sect2>
@@ -98,11 +106,11 @@
   <title>Usage</title>
 
   <para>
-   <xref linkend="cube-operators"> shows the operators provided for type
-   <type>cube</>.
+   <xref linkend="cube-operators-table"> shows the operators provided for
+   type <type>cube</>.
   </para>
 
-  <table id="cube-operators">
+  <table id="cube-operators-table">
    <title>Cube Operators</title>
    <tgroup cols="3">
     <thead>
@@ -240,9 +248,7 @@
    For example, the nearest neighbor of the 3-D point (0.5, 0.5, 0.5)
    could be found efficiently with:
 <programlisting>
-SELECT c FROM test
-ORDER BY cube(array[0.5,0.5,0.5]) <-> c
-LIMIT 1;
+SELECT c FROM test ORDER BY c &lt;-&gt; cube(array[0.5,0.5,0.5]) LIMIT 1;
 </programlisting>
   </para>
 
@@ -252,12 +258,12 @@ LIMIT 1;
    For example, to get the first few cubes ordered by the first coordinate
    (lower left corner) ascending one could use the following query:
 <programlisting>
-SELECT c FROM test ORDER BY c ~> 1 LIMIT 5;
+SELECT c FROM test ORDER BY c ~&gt; 1 LIMIT 5;
 </programlisting>
    And to get 2-D cubes ordered by the first coordinate of the upper right
    corner descending:
 <programlisting>
-SELECT c FROM test ORDER BY c ~> 3 DESC LIMIT 5;
+SELECT c FROM test ORDER BY c ~&gt; 3 DESC LIMIT 5;
 </programlisting>
   </para>
 
@@ -267,128 +273,191 @@ SELECT c FROM test ORDER BY c ~> 3 DESC LIMIT 5;
 
   <table id="cube-functions-table">
    <title>Cube Functions</title>
-   <tgroup cols="2">
+   <tgroup cols="4">
+    <thead>
+     <row>
+      <entry>Function</entry>
+      <entry>Result</entry>
+      <entry>Description</entry>
+      <entry>Example</entry>
+     </row>
+    </thead>
+
     <tbody>
      <row>
-      <entry><literal>cube(float8) returns cube</literal></entry>
+      <entry><literal>cube(float8)</literal></entry>
+      <entry><type>cube</type></entry>
       <entry>Makes a one dimensional cube with both coordinates the same.
+      </entry>
+      <entry>
        <literal>cube(1) == '(1)'</literal>
       </entry>
      </row>
 
      <row>
-      <entry><literal>cube(float8, float8) returns cube</literal></entry>
+      <entry><literal>cube(float8, float8)</literal></entry>
+      <entry><type>cube</type></entry>
       <entry>Makes a one dimensional cube.
+      </entry>
+      <entry>
        <literal>cube(1,2) == '(1),(2)'</literal>
       </entry>
      </row>
 
      <row>
-      <entry><literal>cube(float8[]) returns cube</literal></entry>
+      <entry><literal>cube(float8[])</literal></entry>
+      <entry><type>cube</type></entry>
       <entry>Makes a zero-volume cube using the coordinates
        defined by the array.
+      </entry>
+      <entry>
        <literal>cube(ARRAY[1,2]) == '(1,2)'</literal>
       </entry>
      </row>
 
      <row>
-      <entry><literal>cube(float8[], float8[]) returns cube</literal></entry>
+      <entry><literal>cube(float8[], float8[])</literal></entry>
+      <entry><type>cube</type></entry>
       <entry>Makes a cube with upper right and lower left
        coordinates as defined by the two arrays, which must be of the
        same length.
-       <literal>cube('{1,2}'::float[], '{3,4}'::float[]) == '(1,2),(3,4)'
+      </entry>
+      <entry>
+       <literal>cube(ARRAY[1,2], ARRAY[3,4]) == '(1,2),(3,4)'
        </literal>
       </entry>
      </row>
 
      <row>
-      <entry><literal>cube(cube, float8) returns cube</literal></entry>
-      <entry>Makes a new cube by adding a dimension on to an
-       existing cube with the same values for both parts of the new coordinate.
-       This is useful for building cubes piece by piece from calculated values.
-       <literal>cube('(1)',2) == '(1,2),(1,2)'</literal>
+      <entry><literal>cube(cube, float8)</literal></entry>
+      <entry><type>cube</type></entry>
+      <entry>Makes a new cube by adding a dimension on to an existing cube,
+       with the same values for both endpoints of the new coordinate.  This
+       is useful for building cubes piece by piece from calculated values.
+      </entry>
+      <entry>
+       <literal>cube('(1,2),(3,4)'::cube, 5) == '(1,2,5),(3,4,5)'</literal>
       </entry>
      </row>
 
      <row>
-      <entry><literal>cube(cube, float8, float8) returns cube</literal></entry>
-      <entry>Makes a new cube by adding a dimension on to an
-       existing cube. This is useful for building cubes piece by piece from
-       calculated values. <literal>cube('(1,2)',3,4) == '(1,3),(2,4)'</literal>
+      <entry><literal>cube(cube, float8, float8)</literal></entry>
+      <entry><type>cube</type></entry>
+      <entry>Makes a new cube by adding a dimension on to an existing
+       cube. This is useful for building cubes piece by piece from calculated
+       values.
+      </entry>
+      <entry>
+       <literal>cube('(1,2),(3,4)'::cube, 5, 6) == '(1,2,5),(3,4,6)'</literal>
       </entry>
      </row>
 
      <row>
-      <entry><literal>cube_dim(cube) returns int</literal></entry>
-      <entry>Returns the number of dimensions of the cube
+      <entry><literal>cube_dim(cube)</literal></entry>
+      <entry><type>integer</type></entry>
+      <entry>Returns the number of dimensions of the cube.
+      </entry>
+      <entry>
+       <literal>cube_dim('(1,2),(3,4)') == '2'</literal>
       </entry>
      </row>
 
      <row>
-      <entry><literal>cube_ll_coord(cube, int) returns double </literal></entry>
-      <entry>Returns the n'th coordinate value for the lower left
-       corner of a cube
+      <entry><literal>cube_ll_coord(cube, integer)</literal></entry>
+      <entry><type>float8</type></entry>
+      <entry>Returns the <replaceable>n</>-th coordinate value for the lower
+       left corner of the cube.
+      </entry>
+      <entry>
+       <literal>cube_ll_coord('(1,2),(3,4)', 2) == '2'</literal>
       </entry>
      </row>
 
     <row>
-      <entry><literal>cube_ur_coord(cube, int) returns double
-      </literal></entry>
-      <entry>Returns the n'th coordinate value for the
-       upper right corner of a cube
+      <entry><literal>cube_ur_coord(cube, integer)</literal></entry>
+      <entry><type>float8</type></entry>
+      <entry>Returns the <replaceable>n</>-th coordinate value for the
+       upper right corner of the cube.
+      </entry>
+      <entry>
+       <literal>cube_ur_coord('(1,2),(3,4)', 2) == '4'</literal>
       </entry>
      </row>
 
      <row>
-      <entry><literal>cube_is_point(cube) returns bool</literal></entry>
-      <entry>Returns true if a cube is a point, that is,
+      <entry><literal>cube_is_point(cube)</literal></entry>
+      <entry><type>boolean</type></entry>
+      <entry>Returns true if the cube is a point, that is,
        the two defining corners are the same.</entry>
+      <entry>
+      </entry>
      </row>
 
      <row>
-      <entry><literal>cube_distance(cube, cube) returns double</literal></entry>
+      <entry><literal>cube_distance(cube, cube)</literal></entry>
+      <entry><type>float8</type></entry>
       <entry>Returns the distance between two cubes. If both
        cubes are points, this is the normal distance function.
       </entry>
+      <entry>
+      </entry>
      </row>
 
      <row>
-      <entry><literal>cube_subset(cube, int[]) returns cube
-      </literal></entry>
+      <entry><literal>cube_subset(cube, integer[])</literal></entry>
+      <entry><type>cube</type></entry>
       <entry>Makes a new cube from an existing cube, using a list of
-       dimension indexes from an array. Can be used to find both the LL and UR
-       coordinates of a single dimension, e.g.
-       <literal>cube_subset(cube('(1,3,5),(6,7,8)'), ARRAY[2]) = '(3),(7)'</>.
-       Or can be used to drop dimensions, or reorder them as desired, e.g.
-       <literal>cube_subset(cube('(1,3,5),(6,7,8)'), ARRAY[3,2,1,1]) = '(5, 3,
-       1, 1),(8, 7, 6, 6)'</>.
+       dimension indexes from an array. Can be used to extract the endpoints
+       of a single dimension, or to drop dimensions, or to reorder them as
+       desired.
+      </entry>
+      <entry>
+       <literal>cube_subset(cube('(1,3,5),(6,7,8)'), ARRAY[2]) == '(3),(7)'</>
+       <literal>cube_subset(cube('(1,3,5),(6,7,8)'), ARRAY[3,2,1,1]) ==
+        '(5,3,1,1),(8,7,6,6)'</>
       </entry>
      </row>
 
      <row>
-      <entry><literal>cube_union(cube, cube) returns cube</literal></entry>
-      <entry>Produces the union of two cubes
+      <entry><literal>cube_union(cube, cube)</literal></entry>
+      <entry><type>cube</type></entry>
+      <entry>Produces the union of two cubes.
+      </entry>
+      <entry>
       </entry>
      </row>
 
      <row>
-      <entry><literal>cube_inter(cube, cube) returns cube</literal></entry>
-      <entry>Produces the intersection of two cubes
+      <entry><literal>cube_inter(cube, cube)</literal></entry>
+      <entry><type>cube</type></entry>
+      <entry>Produces the intersection of two cubes.
+      </entry>
+      <entry>
       </entry>
      </row>
 
      <row>
-      <entry><literal>cube_enlarge(cube c, double r, int n) returns cube</literal></entry>
-      <entry>Increases the size of a cube by a specified radius in at least
-       n dimensions. If the radius is negative the cube is shrunk instead. This
-       is useful for creating bounding boxes around a point for searching for
-       nearby points. All defined dimensions are changed by the radius r.
-       LL coordinates are decreased by r and UR coordinates are increased by r.
-       If a LL coordinate is increased to larger than the corresponding UR
-       coordinate (this can only happen when r &lt; 0) than both coordinates
-       are set to their average.  If n is greater than the number of defined
-       dimensions and the cube is being increased (r &gt;= 0) then 0 is used
-       as the base for the extra coordinates.
+      <entry><literal>cube_enlarge(c cube, r double, n integer)</literal></entry>
+      <entry><type>cube</type></entry>
+      <entry>Increases the size of the cube by the specified
+       radius <replaceable>r</> in at least <replaceable>n</> dimensions.
+       If the radius is negative the cube is shrunk instead.
+       All defined dimensions are changed by the radius <replaceable>r</>.
+       Lower-left coordinates are decreased by <replaceable>r</> and
+       upper-right coordinates are increased by <replaceable>r</>.  If a
+       lower-left coordinate is increased to more than the corresponding
+       upper-right coordinate (this can only happen when <replaceable>r</>
+       &lt; 0) than both coordinates are set to their average.
+       If <replaceable>n</> is greater than the number of defined dimensions
+       and the cube is being enlarged (<replaceable>r</> &gt; 0), then extra
+       dimensions are added to make <replaceable>n</> altogether;
+       0 is used as the initial value for the extra coordinates.
+       This function is useful for creating bounding boxes around a point for
+       searching for nearby points.
+      </entry>
+      <entry>
+       <literal>cube_enlarge('(1,2),(3,4)', 0.5, 3) ==
+        '(0.5,1.5,-0.5),(3.5,4.5,0.5)'</>
       </entry>
      </row>
     </tbody>