Re: Another modest proposal for docs formatting: catalog descriptions

Here's a more fully fleshed out draft for this, with stylesheet
markup to get extra space around the column type names.

I realized that I can probably automate this conversion, unlike the
function-table conversion: I'm not feeling any need to editorialize
on the column descriptions, so I can probably just extract the data
from the SGML programmatically and rebuild it as I want.  Seems like
it should be a fairly quick process.  So, if this seems good from
your standpoint, please push up the patch on main.css and then I'll
see about doing the edit.

(BTW, said patch also removes some no-longer-used detritus from the
earlier markup attempt.)

            regards, tom lane

diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
index ce33df9..e3513ad 100644
--- a/doc/src/sgml/catalogs.sgml
+++ b/doc/src/sgml/catalogs.sgml
@@ -388,178 +388,251 @@

   <table>
    <title><structname>pg_aggregate</structname> Columns</title>
-
-   <tgroup cols="4">
+   <tgroup cols="1">
     <thead>
      <row>
-      <entry>Name</entry>
-      <entry>Type</entry>
-      <entry>References</entry>
-      <entry>Description</entry>
+      <entry role="catalog_table_entry"><para role="column_definition">
+       Column Type
+      </para>
+      <para>
+       Description
+      </para></entry>
      </row>
     </thead>
+
     <tbody>
      <row>
-      <entry><structfield>aggfnoid</structfield></entry>
-      <entry><type>regproc</type></entry>
-      <entry><literal><link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.oid</literal></entry>
-      <entry><structname>pg_proc</structname> OID of the aggregate function</entry>
+      <entry role="catalog_table_entry"><para role="column_definition">
+       <structfield>aggfnoid</structfield>
+       <type>regproc</type>
+       (references <link
linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.<structfield>oid</structfield>)
+      </para>
+      <para>
+       <structname>pg_proc</structname> OID of the aggregate function
+      </para></entry>
      </row>
      <row>
-      <entry><structfield>aggkind</structfield></entry>
-      <entry><type>char</type></entry>
-      <entry></entry>
-      <entry>Aggregate kind:
+      <entry role="catalog_table_entry"><para role="column_definition">
+       <structfield>aggkind</structfield>
+       <type>char</type>
+      </para>
+      <para>
+       Aggregate kind:
        <literal>n</literal> for <quote>normal</quote> aggregates,
        <literal>o</literal> for <quote>ordered-set</quote> aggregates, or
        <literal>h</literal> for <quote>hypothetical-set</quote> aggregates
-      </entry>
+      </para></entry>
      </row>
      <row>
-      <entry><structfield>aggnumdirectargs</structfield></entry>
-      <entry><type>int2</type></entry>
-      <entry></entry>
-      <entry>Number of direct (non-aggregated) arguments of an ordered-set or
+      <entry role="catalog_table_entry"><para role="column_definition">
+       <structfield>aggnumdirectargs</structfield>
+       <type>int2</type>
+      </para>
+      <para>
+       Number of direct (non-aggregated) arguments of an ordered-set or
        hypothetical-set aggregate, counting a variadic array as one argument.
        If equal to <structfield>pronargs</structfield>, 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.</entry>
+       Always zero for normal aggregates.
+      </para></entry>
      </row>
      <row>
-      <entry><structfield>aggtransfn</structfield></entry>
-      <entry><type>regproc</type></entry>
-      <entry><literal><link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.oid</literal></entry>
-      <entry>Transition function</entry>
+      <entry role="catalog_table_entry"><para role="column_definition">
+       <structfield>aggtransfn</structfield>
+       <type>regproc</type>
+       (references <link
linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.<structfield>oid</structfield>)
+      </para>
+      <para>
+       Transition function
+      </para></entry>
      </row>
      <row>
-      <entry><structfield>aggfinalfn</structfield></entry>
-      <entry><type>regproc</type></entry>
-      <entry><literal><link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.oid</literal></entry>
-      <entry>Final function (zero if none)</entry>
+      <entry role="catalog_table_entry"><para role="column_definition">
+       <structfield>aggfinalfn</structfield>
+       <type>regproc</type>
+       (references <link
linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.<structfield>oid</structfield>)
+      </para>
+      <para>
+       Final function (zero if none)
+      </para></entry>
      </row>
      <row>
-      <entry><structfield>aggcombinefn</structfield></entry>
-      <entry><type>regproc</type></entry>
-      <entry><literal><link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.oid</literal></entry>
-      <entry>Combine function (zero if none)</entry>
+      <entry role="catalog_table_entry"><para role="column_definition">
+       <structfield>aggcombinefn</structfield>
+       <type>regproc</type>
+       (references <link
linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.<structfield>oid</structfield>)
+      </para>
+      <para>
+       Combine function (zero if none)
+      </para></entry>
      </row>
      <row>
-      <entry><structfield>aggserialfn</structfield></entry>
-      <entry><type>regproc</type></entry>
-      <entry><literal><link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.oid</literal></entry>
-      <entry>Serialization function (zero if none)</entry>
+      <entry role="catalog_table_entry"><para role="column_definition">
+       <structfield>aggserialfn</structfield>
+       <type>regproc</type>
+       (references <link
linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.<structfield>oid</structfield>)
+      </para>
+      <para>
+       Serialization function (zero if none)
+      </para></entry>
      </row>
      <row>
-      <entry><structfield>aggdeserialfn</structfield></entry>
-      <entry><type>regproc</type></entry>
-      <entry><literal><link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.oid</literal></entry>
-      <entry>Deserialization function (zero if none)</entry>
+      <entry role="catalog_table_entry"><para role="column_definition">
+       <structfield>aggdeserialfn</structfield>
+       <type>regproc</type>
+       (references <link
linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.<structfield>oid</structfield>)
+      </para>
+      <para>
+       Deserialization function (zero if none)
+      </para></entry>
      </row>
      <row>
-      <entry><structfield>aggmtransfn</structfield></entry>
-      <entry><type>regproc</type></entry>
-      <entry><literal><link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.oid</literal></entry>
-      <entry>Forward transition function for moving-aggregate mode (zero if none)</entry>
+      <entry role="catalog_table_entry"><para role="column_definition">
+       <structfield>aggmtransfn</structfield>
+       <type>regproc</type>
+       (references <link
linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.<structfield>oid</structfield>)
+      </para>
+      <para>
+       Forward transition function for moving-aggregate mode (zero if none)
+      </para></entry>
      </row>
      <row>
-      <entry><structfield>aggminvtransfn</structfield></entry>
-      <entry><type>regproc</type></entry>
-      <entry><literal><link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.oid</literal></entry>
-      <entry>Inverse transition function for moving-aggregate mode (zero if none)</entry>
+      <entry role="catalog_table_entry"><para role="column_definition">
+       <structfield>aggminvtransfn</structfield>
+       <type>regproc</type>
+       (references <link
linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.<structfield>oid</structfield>)
+      </para>
+      <para>
+       Inverse transition function for moving-aggregate mode (zero if none)
+      </para></entry>
      </row>
      <row>
-      <entry><structfield>aggmfinalfn</structfield></entry>
-      <entry><type>regproc</type></entry>
-      <entry><literal><link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.oid</literal></entry>
-      <entry>Final function for moving-aggregate mode (zero if none)</entry>
+      <entry role="catalog_table_entry"><para role="column_definition">
+       <structfield>aggmfinalfn</structfield>
+       <type>regproc</type>
+       (references <link
linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.<structfield>oid</structfield>)
+      </para>
+      <para>
+       Final function for moving-aggregate mode (zero if none)
+      </para></entry>
      </row>
      <row>
-      <entry><structfield>aggfinalextra</structfield></entry>
-      <entry><type>bool</type></entry>
-      <entry></entry>
-      <entry>True to pass extra dummy arguments to <structfield>aggfinalfn</structfield></entry>
+      <entry role="catalog_table_entry"><para role="column_definition">
+       <structfield>aggfinalextra</structfield>
+       <type>bool</type>
+      </para>
+      <para>
+       True to pass extra dummy arguments to <structfield>aggfinalfn</structfield>
+      </para></entry>
      </row>
      <row>
-      <entry><structfield>aggmfinalextra</structfield></entry>
-      <entry><type>bool</type></entry>
-      <entry></entry>
-      <entry>True to pass extra dummy arguments to <structfield>aggmfinalfn</structfield></entry>
+      <entry role="catalog_table_entry"><para role="column_definition">
+       <structfield>aggmfinalextra</structfield>
+       <type>bool</type>
+      </para>
+      <para>
+       True to pass extra dummy arguments to <structfield>aggmfinalfn</structfield>
+      </para></entry>
      </row>
      <row>
-      <entry><structfield>aggfinalmodify</structfield></entry>
-      <entry><type>char</type></entry>
-      <entry></entry>
-      <entry>Whether <structfield>aggfinalfn</structfield> modifies the
+      <entry role="catalog_table_entry"><para role="column_definition">
+       <structfield>aggfinalmodify</structfield>
+       <type>char</type>
+      </para>
+      <para>
+       Whether <structfield>aggfinalfn</structfield> modifies the
        transition state value:
        <literal>r</literal> if it is read-only,
        <literal>s</literal> if the <structfield>aggtransfn</structfield>
        cannot be applied after the <structfield>aggfinalfn</structfield>, or
        <literal>w</literal> if it writes on the value
-      </entry>
+      </para></entry>
      </row>
      <row>
-      <entry><structfield>aggmfinalmodify</structfield></entry>
-      <entry><type>char</type></entry>
-      <entry></entry>
-      <entry>Like <structfield>aggfinalmodify</structfield>, but for
+      <entry role="catalog_table_entry"><para role="column_definition">
+       <structfield>aggmfinalmodify</structfield>
+       <type>char</type>
+      </para>
+      <para>
+       Like <structfield>aggfinalmodify</structfield>, but for
        the <structfield>aggmfinalfn</structfield>
-      </entry>
+      </para></entry>
      </row>
      <row>
-      <entry><structfield>aggsortop</structfield></entry>
-      <entry><type>oid</type></entry>
-      <entry><literal><link
linkend="catalog-pg-operator"><structname>pg_operator</structname></link>.oid</literal></entry>
-      <entry>Associated sort operator (zero if none)</entry>
+      <entry role="catalog_table_entry"><para role="column_definition">
+       <structfield>aggsortop</structfield>
+       <type>oid</type>
+       (references <link
linkend="catalog-pg-operator"><structname>pg_operator</structname></link>.<structfield>oid</structfield>)
+      </para>
+      <para>
+       Associated sort operator (zero if none)
+      </para></entry>
      </row>
      <row>
-      <entry><structfield>aggtranstype</structfield></entry>
-      <entry><type>oid</type></entry>
-      <entry><literal><link linkend="catalog-pg-type"><structname>pg_type</structname></link>.oid</literal></entry>
-      <entry>Data type of the aggregate function's internal transition (state) data</entry>
+      <entry role="catalog_table_entry"><para role="column_definition">
+       <structfield>aggtranstype</structfield>
+       <type>oid</type>
+       (references <link
linkend="catalog-pg-type"><structname>pg_type</structname></link>.<structfield>oid</structfield>)
+      </para>
+      <para>
+       Data type of the aggregate function's internal transition (state) data
+      </para></entry>
      </row>
      <row>
-      <entry><structfield>aggtransspace</structfield></entry>
-      <entry><type>int4</type></entry>
-      <entry></entry>
-      <entry>Approximate average size (in bytes) of the transition state
-       data, or zero to use a default estimate</entry>
+      <entry role="catalog_table_entry"><para role="column_definition">
+       <structfield>aggtransspace</structfield>
+       <type>int4</type>
+      </para>
+      <para>
+       Approximate average size (in bytes) of the transition state
+       data, or zero to use a default estimate
+      </para></entry>
      </row>
      <row>
-      <entry><structfield>aggmtranstype</structfield></entry>
-      <entry><type>oid</type></entry>
-      <entry><literal><link linkend="catalog-pg-type"><structname>pg_type</structname></link>.oid</literal></entry>
-      <entry>Data type of the aggregate function's internal transition (state)
-       data for moving-aggregate mode (zero if none)</entry>
+      <entry role="catalog_table_entry"><para role="column_definition">
+       <structfield>aggmtranstype</structfield>
+       <type>oid</type>
+       (references <link
linkend="catalog-pg-type"><structname>pg_type</structname></link>.<structfield>oid</structfield>)
+      </para>
+      <para>
+       Data type of the aggregate function's internal transition (state)
+       data for moving-aggregate mode (zero if none)
+      </para></entry>
      </row>
      <row>
-      <entry><structfield>aggmtransspace</structfield></entry>
-      <entry><type>int4</type></entry>
-      <entry></entry>
-      <entry>Approximate average size (in bytes) of the transition state data
-       for moving-aggregate mode, or zero to use a default estimate</entry>
+      <entry role="catalog_table_entry"><para role="column_definition">
+       <structfield>aggmtransspace</structfield>
+       <type>int4</type>
+      </para>
+      <para>
+       Approximate average size (in bytes) of the transition state data
+       for moving-aggregate mode, or zero to use a default estimate
+      </para></entry>
      </row>
      <row>
-      <entry><structfield>agginitval</structfield></entry>
-      <entry><type>text</type></entry>
-      <entry></entry>
-      <entry>
+      <entry role="catalog_table_entry"><para role="column_definition">
+       <structfield>agginitval</structfield>
+       <type>text</type>
+      </para>
+      <para>
        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.
-      </entry>
+      </para></entry>
      </row>
      <row>
-      <entry><structfield>aggminitval</structfield></entry>
-      <entry><type>text</type></entry>
-      <entry></entry>
-      <entry>
+      <entry role="catalog_table_entry"><para role="column_definition">
+       <structfield>aggminitval</structfield>
+       <type>text</type>
+      </para>
+      <para>
        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.
-      </entry>
+      </para></entry>
      </row>
     </tbody>
    </tgroup>
diff --git a/doc/src/sgml/stylesheet-fo.xsl b/doc/src/sgml/stylesheet-fo.xsl
index 5a27346..861e7ed 100644
--- a/doc/src/sgml/stylesheet-fo.xsl
+++ b/doc/src/sgml/stylesheet-fo.xsl
@@ -78,6 +78,16 @@
   </fo:block>
 </xsl:template>

+<!-- formatting for entries in tables of catalog/view columns -->
+<xsl:template match="entry[@role='catalog_table_entry']/para">
+  <fo:block margin-left="4em" text-align="left">
+    <xsl:if test="self::para[@role='column_definition']">
+      <xsl:attribute name="text-indent">-3.5em</xsl:attribute>
+    </xsl:if>
+    <xsl:apply-templates/>
+  </fo:block>
+</xsl:template>
+
 <!-- overrides stylesheet-common.xsl -->
 <!-- FOP needs us to be explicit about the font to use for right arrow -->
 <xsl:template match="returnvalue">
diff --git a/doc/src/sgml/stylesheet.css b/doc/src/sgml/stylesheet.css
index 11f88cc..b9317c5 100644
--- a/doc/src/sgml/stylesheet.css
+++ b/doc/src/sgml/stylesheet.css
@@ -96,6 +96,36 @@ td.func_table_entry pre.programlisting {
     padding-left: 4em;
 }

+/* formatting for entries in tables of catalog/view columns */
+
+th.catalog_table_entry p,
+td.catalog_table_entry p {
+    margin-top: 0.1em;
+    margin-bottom: 0.1em;
+    padding-left: 4em;
+    text-align: left;
+}
+
+th.catalog_table_entry p.column_definition {
+    text-indent: -3.5em;
+    word-spacing: 1em;
+}
+
+td.catalog_table_entry p.column_definition {
+    text-indent: -3.5em;
+}
+
+p.column_definition code.type {
+    padding-left: 1em;
+    padding-right: 1em;
+}
+
+td.catalog_table_entry pre.programlisting {
+    margin-top: 0.1em;
+    margin-bottom: 0.1em;
+    padding-left: 4em;
+}
+
 /* Put these here instead of inside the HTML (see unsetting of
    admon.style in XSL) so that the web site stylesheet can set its own
    style. */
--- main.css.orig    2020-05-08 18:19:11.711175113 -0400
+++ main.css    2020-05-08 18:32:04.235265137 -0400
@@ -792,13 +792,6 @@
 }

 /** Formatting for entries in tables of functions: indent all but first line **/
-#docContent table.table th.functableentry,
-#docContent table.table td.functableentry {
-    padding-left: 4em;
-    text-indent: -3.5em;
-    text-align: left;
-}
-
 #docContent table.table th.func_table_entry p,
 #docContent table.table td.func_table_entry p {
   margin-top: 0.1em;
@@ -820,6 +813,38 @@
   padding-left: 4em;
 }

+/** Formatting for entries in tables of catalog/view columns **/
+#docContent table.table th.catalog_table_entry p,
+#docContent table.table td.catalog_table_entry p {
+  margin-top: 0.1em;
+  margin-bottom: 0.1em;
+  padding-left: 4em;
+  text-align: left;
+}
+
+#docContent table.table th.catalog_table_entry p.column_definition {
+  text-indent: -3.5em;
+  word-spacing: 1em;
+}
+
+#docContent table.table td.catalog_table_entry p.column_definition {
+  text-indent: -3.5em;
+}
+
+#docContent table.table p.column_definition code.type {
+  padding-left: 1em;
+  padding-right: 1em;
+}
+
+#docContent table.table td.catalog_table_entry pre.programlisting {
+  background-color: inherit;
+  border: 0;
+  margin-bottom: 0.1em;
+  margin-top: 0.1em;
+  padding: 0;
+  padding-left: 4em;
+}
+
 /**
  * Titles, Navigation
  */