Improve documentation for \crosstabview.

Fix misleading syntax summary (there cannot be a space between colH and
scolH).  Provide a link from the existing crosstab() function's
documentation to \crosstabview.  Copy-edit the command's description.

Christoph Berg and Tom Lane

diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index 1f07956d42856c19ba283f177837f33600c7b755..b2b2adc3b621c8cb993ffc997dd95e58596aac0d 100644 (file)
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/doc/src/sgml/ref/psql-ref.sgml
@@ -989,106 +989,78 @@ testdb=>
         
       
 
-      
+
+      
         \crosstabview [
             colV
-            colH
-            [:scolH]
+            colH[:scolH]
             [colD]
             ] 
         
         
-        Execute the current query buffer (like \g) and shows
-        the results inside a crosstab grid.
+        Executes the current query buffer (like \g) and
+        shows the results in a crosstab grid.
         The query must return at least three columns.
-        The output column colV>
-        becomes a vertical header
-        and the output column colH
+        The output column identified by colV>
+        becomes a vertical header and the output column identified by
+        colH
         becomes a horizontal header, optionally sorted by ranking data obtained
-        from scolH.
-        colD
-        is the output column to project into the grid.  If this is not
+        from column scolH.
+        colD identifies
+        the output column to display within the grid.
+        If colD is not
         specified and there are exactly three columns in the result set,
-        the column that isn't
+        the column that is neither
         colV nor
         colH
-        is displayed; if there are more columns, an error is thrown.
+        is displayed; if there are more columns, an error is reported.
         
 
         
-        All columns can be refered to by their position (starting at 1), or by
-        their name. Normal case folding and quoting rules apply on column
-        names. By default,
-        colV corresponds to column 1
-        and colH to column 2.
-        A query having only one output column cannot be viewed in crosstab, and
+        Each column specification can be a column number (starting at 1) or
+        a column name.  The usual SQL case folding and quoting rules apply to
+        column names.  If omitted,
+        colV is taken as column 1
+        and colH as column 2.
         colH must differ from
         colV.
         
 
         
-        The vertical header, displayed as the leftmost column,
-        contains the deduplicated values found in
-        column colV, in the same
-        order as in the query results.
+        The vertical header, displayed as the leftmost column, contains the
+        values found in column colV, in the
+        same order as in the query results, but with duplicates removed.
         
 
         
-        The horizontal header, displayed as the first row,
-        contains the deduplicated values found in
-        column colH, in
-        the order of appearance in the query results.
-        If specified, the optional scolH
-        argument refers to a column whose values should be integer numbers
-        by which colH will be sorted
-        to be positioned in the horizontal header.
+        The horizontal header, displayed as the first row, contains the values
+        found in column colH,
+        with duplicates removed.  By default, these appear in the same order
+        as in the query results.  But if the
+        optional scolH argument is given, it
+        identifies a column whose values must be integer numbers, and the
+        values from colH will
+        appear in the horizontal header sorted according to the
+        corresponding scolH values.
         
 
         
-        Inside the crosstab grid,
-        given a query output with N columns
-        (including colV and
-        colH),
-        for each distinct value x of
-        colH
-        and each distinct value y of
-        colV,
-        the contents of a cell located at the intersection
-        (x,y) is determined by these rules:
-        
-        
-        
-         if there is no corresponding row in the query results such that the
-         value for colH
-         is x and the value
-         for colV
-         is y, the cell is empty.
-        
-        
-
-        
-        
-         if there is exactly one row such that the value
-         for colH
-         is x and the value
-         for colV
-         is y, then the colD column
-         is displayed.
+        Inside the crosstab grid, for each distinct value x
+        of colH and each distinct
+        value y
+        of colV, the cell located
+        at the intersection (x,y) contains the value of
+        the colD column in the query result row for which
+        the value of colH
+        is x and the value
+        of colV
+        is y.  If there is no such row, the cell is empty.  If
+        there are multiple such rows, an error is reported.
         
         
-
-        
-        
-         if there are several such rows, an error is thrown.
-        
-        
-
-        
-        
-
-        
       
 
+
       
         \d[S+] [ pattern ]
 

diff --git a/doc/src/sgml/tablefunc.sgml b/doc/src/sgml/tablefunc.sgml
index 1d8423d5ae784707294d14773cd2e44bf25e4256..90f6df9545bf3edc7369ba69e3ae9b9aa5715e82 100644 (file)
--- a/doc/src/sgml/tablefunc.sgml
+++ b/doc/src/sgml/tablefunc.sgml
@@ -293,6 +293,14 @@ AS ct(row_name text, category_1 text, category_2 text, category_3 text);
     required FROM clause in a view definition.
    
 
+   
+    
+     See also the \crosstabview
+     command in psql, which provides functionality similar
+     to crosstab().
+    
+   
+