Re: Another modest proposal for docs formatting: catalog descriptions

Here's a really quick-n-dirty prototype patch that just converts the
pg_aggregate table to the proposed style, plus a screenshot for those
who don't feel like actually building the docs with the patch.

Looking at the results, it seems like we could really use a bit more
horizontal space between the column names and data types, and perhaps
also between the types and the (references) annotations.  Other than
that it looks decent.  I don't know what's the cleanest way to add
some space there --- I'd rather not have the SGML text do it explicitly.

There's room for complaint that this takes up more vertical space than
the old way, assuming you have a reasonably wide window.  I'm not
terribly bothered by that, but maybe someone else will be?  I'm inclined
to think that that's well worth the benefit that we won't feel compelled
to keep column descriptions short.

BTW, this being just a test hack, I repurposed the "func_table_entry" and
"func_signature" style marker roles.  If we do this for real then of
course we'd want to use different roles, even if they happen to mark up
the same for now.

			regards, tom lane

diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
index ce33df9..efb5e64 100644
--- a/doc/src/sgml/catalogs.sgml
+++ b/doc/src/sgml/catalogs.sgml
@@ -388,178 +388,251 @@
 
   
    <structname>pg_aggregate</structname> Columns
-
-   
+   
     
      
-      Name
-      Type
-      References
-      Description
+      
+       Column Type
+      
+      
+       Description
+      
      
     
+
     
      
-      aggfnoid
-      regproc
-      pg_proc.oid
-      pg_proc OID of the aggregate function
+      
+       aggfnoid
+       regproc
+       (references pg_proc.oid)
+      
+      
+       pg_proc OID of the aggregate function
+      
      
      
-      aggkind
-      char
-      
-      Aggregate kind:
+      
+       aggkind
+       char
+      
+      
+       Aggregate kind:
        n for normal aggregates,
        o for ordered-set aggregates, or
        h for hypothetical-set aggregates
-      
+      
      
      
-      aggnumdirectargs
-      int2
-      
-      Number of direct (non-aggregated) arguments of an ordered-set or
+      
+       aggnumdirectargs
+       int2
+      
+      
+       Number of direct (non-aggregated) arguments of an ordered-set or
        hypothetical-set aggregate, counting a variadic array as one argument.
        If equal to pronargs, the aggregate must be variadic
        and the variadic array describes the aggregated arguments as well as
        the final direct arguments.
-       Always zero for normal aggregates.
+       Always zero for normal aggregates.
+      
      
      
-      aggtransfn
-      regproc
-      pg_proc.oid
-      Transition function
+      
+       aggtransfn
+       regproc
+       (references pg_proc.oid)
+      
+      
+       Transition function
+      
      
      
-      aggfinalfn
-      regproc
-      pg_proc.oid
-      Final function (zero if none)
+      
+       aggfinalfn
+       regproc
+       (references pg_proc.oid)
+      
+      
+       Final function (zero if none)
+      
      
      
-      aggcombinefn
-      regproc
-      pg_proc.oid
-      Combine function (zero if none)
+      
+       aggcombinefn
+       regproc
+       (references pg_proc.oid)
+      
+      
+       Combine function (zero if none)
+      
      
      
-      aggserialfn
-      regproc
-      pg_proc.oid
-      Serialization function (zero if none)
+      
+       aggserialfn
+       regproc
+       (references pg_proc.oid)
+      
+      
+       Serialization function (zero if none)
+      
      
      
-      aggdeserialfn
-      regproc
-      pg_proc.oid
-      Deserialization function (zero if none)
+      
+       aggdeserialfn
+       regproc
+       (references pg_proc.oid)
+      
+      
+       Deserialization function (zero if none)
+      
      
      
-      aggmtransfn
-      regproc
-      pg_proc.oid
-      Forward transition function for moving-aggregate mode (zero if none)
+      
+       aggmtransfn
+       regproc
+       (references pg_proc.oid)
+      
+      
+       Forward transition function for moving-aggregate mode (zero if none)
+      
      
      
-      aggminvtransfn
-      regproc
-      pg_proc.oid
-      Inverse transition function for moving-aggregate mode (zero if none)
+      
+       aggminvtransfn
+       regproc
+       (references pg_proc.oid)
+      
+      
+       Inverse transition function for moving-aggregate mode (zero if none)
+      
      
      
-      aggmfinalfn
-      regproc
-      pg_proc.oid
-      Final function for moving-aggregate mode (zero if none)
+      
+       aggmfinalfn
+       regproc
+       (references pg_proc.oid)
+      
+      
+       Final function for moving-aggregate mode (zero if none)
+      
      
      
-      aggfinalextra
-      bool
-      
-      True to pass extra dummy arguments to aggfinalfn
+      
+       aggfinalextra
+       bool
+      
+      
+       True to pass extra dummy arguments to aggfinalfn
+      
      
      
-      aggmfinalextra
-      bool
-      
-      True to pass extra dummy arguments to aggmfinalfn
+      
+       aggmfinalextra
+       bool
+      
+      
+       True to pass extra dummy arguments to aggmfinalfn
+      
      
      
-      aggfinalmodify
-      char
-      
-      Whether aggfinalfn modifies the
+      
+       aggfinalmodify
+       char
+      
+      
+       Whether aggfinalfn modifies the
        transition state value:
        r if it is read-only,
        s if the aggtransfn
        cannot be applied after the aggfinalfn, or
        w if it writes on the value
-      
+      
      
      
-      aggmfinalmodify
-      char
-      
-      Like aggfinalmodify, but for
+      
+       aggmfinalmodify
+       char
+      
+      
+       Like aggfinalmodify, but for
        the aggmfinalfn
-      
+      
      
      
-      aggsortop
-      oid
-      pg_operator.oid
-      Associated sort operator (zero if none)
+      
+       aggsortop
+       oid
+       (references pg_operator.oid)
+      
+      
+       Associated sort operator (zero if none)
+      
      
      
-      aggtranstype
-      oid
-      pg_type.oid
-      Data type of the aggregate function's internal transition (state) data
+      
+       aggtranstype
+       oid
+       (references pg_type.oid)
+      
+      
+       Data type of the aggregate function's internal transition (state) data
+      
      
      
-      aggtransspace
-      int4
-      
-      Approximate average size (in bytes) of the transition state
-       data, or zero to use a default estimate
+      
+       aggtransspace
+       int4
+      
+      
+       Approximate average size (in bytes) of the transition state
+       data, or zero to use a default estimate
+      
      
      
-      aggmtranstype
-      oid
-      pg_type.oid
-      Data type of the aggregate function's internal transition (state)
-       data for moving-aggregate mode (zero if none)
+      
+       aggmtranstype
+       oid
+       (references pg_type.oid)
+      
+      
+       Data type of the aggregate function's internal transition (state)
+       data for moving-aggregate mode (zero if none)
+      
      
      
-      aggmtransspace
-      int4
-      
-      Approximate average size (in bytes) of the transition state data
-       for moving-aggregate mode, or zero to use a default estimate
+      
+       aggmtransspace
+       int4
+      
+      
+       Approximate average size (in bytes) of the transition state data
+       for moving-aggregate mode, or zero to use a default estimate
+      
      
      
-      agginitval
-      text
-      
-      
+      
+       agginitval
+       text
+      
+      
        The initial value of the transition state.  This is a text
        field containing the initial value in its external string
        representation.  If this field is null, the transition state
        value starts out null.
-      
+      
      
      
-      aggminitval
-      text
-      
-      
+      
+       aggminitval
+       text
+      
+      
        The initial value of the transition state for moving-aggregate mode.
        This is a text field containing the initial value in its external
        string representation.  If this field is null, the transition state
        value starts out null.
-      
+