Re: Poll: are people okay with function/operator table redesign? - Mailing list pgsql-hackers

"David G. Johnston" <david.g.johnston@gmail.com> writes:
> On Mon, Apr 13, 2020 at 1:57 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:
>> Actually ... if we did it like that, then it would be possible to treat
>> the signature + description + example(s) as one big table cell with line
>> breaks rather than row-separator bars.
>> That would help address the
>> inadequate-visual-separation-between-groups issue, but on the other hand
>> maybe we'd end up with too little visual separation between the elements
>> of a function description.

> Speaking in terms of HTML if we use <hr /> instead of <br /> we would get
> the best of both worlds.

Hm.  I quickly hacked up table 9.33 to use this approach.  Attached
are a patch for that, as well as screenshots of HTML and PDF output.
(To get the equivalent of HTML-hr.png, use <hr/> not <br/> in the
stylesheet.)

I don't think I like the <hr/> version better than <br/> --- it adds
quite a bit of vertical space, more than I was expecting really.  The
documentation I could find with Google suggests that <hr/> can be
rendered with quite a bit of variation by different agents, so other
people might get different results.  (This is with Safari.)  It seems
like the font differentiation between the description and the other
parts is almost, but perhaps not quite, enough separation already.

I don't know how to get the equivalent of <hr/> in PDF output, so
that version just does line breaks.  It seems like the vertical
spacing in the examples is a bit wonky, but otherwise it's not awful.

Note that the PDF rendering shows the header and function name
alignment as I intended them; the HTML renderings are wrong due to
website stylesheet issues.

            regards, tom lane

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 7a270eb..497c125 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -8645,103 +8645,89 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple

   <table id="functions-enum-table">
     <title>Enum Support Functions</title>
-    <tgroup cols="3">
-     <colspec colname="col1" colwidth="0.5*"/>
-     <colspec colname="col2" colwidth="1*"/>
-     <colspec colname="col3" colwidth="1*"/>
-     <spanspec spanname="name" namest="col1" nameend="col1" align="left"/>
-     <spanspec spanname="sig" namest="col2" nameend="col3" align="left"/>
-     <spanspec spanname="desc" namest="col2" nameend="col3" align="left"/>
-     <spanspec spanname="example" namest="col2" nameend="col2" align="left"/>
-     <spanspec spanname="exresult" namest="col3" nameend="col3" align="left"/>
+    <tgroup cols="2">
+     <colspec colname="col1" colwidth="0.5*" align="left"/>
+     <colspec colname="col2" colwidth="1*" align="left"/>
      <thead>
       <row>
-       <entry spanname="name" align="center" valign="middle" morerows="2">Function</entry>
-       <entry spanname="sig" align="center">Signature</entry>
-      </row>
-      <row>
-       <entry spanname="desc" align="center">Description</entry>
-      </row>
-      <row>
-       <entry spanname="example" align="center">Example</entry>
-       <entry spanname="exresult" align="center">Example Result</entry>
+       <entry align="center" valign="middle">Function</entry>
+       <entry align="center">Signature<?br?>Description<?br?>Example</entry>
       </row>
      </thead>
      <tbody>
       <row>
-       <entry spanname="name" morerows="2">
+       <entry valign="middle">
         <indexterm>
          <primary>enum_first</primary>
         </indexterm>
         <function>enum_first</function>
        </entry>
-       <entry spanname="sig"><function>enum_first</function>(<type>anyenum</type>)
<returnvalue>anyenum</returnvalue></entry>
-      </row>
-      <row>
-       <entry spanname="desc">Returns the first value of the input enum type</entry>
-      </row>
-      <row>
-       <entry spanname="example"><literal>enum_first(&zwsp;null::rainbow)</literal></entry>
-       <entry spanname="exresult"><literal>red</literal></entry>
+       <entry>
+        <function>enum_first</function>(<type>anyenum</type>)
+        <returnvalue>anyenum</returnvalue>
+        <?br?>
+        Returns the first value of the input enum type
+        <?br?>
+        <literal>enum_first(&zwsp;null::rainbow)</literal>
+        <returnvalue>red</returnvalue>
+       </entry>
       </row>
       <row>
-       <entry spanname="name" morerows="2">
+       <entry valign="middle">
         <indexterm>
          <primary>enum_last</primary>
         </indexterm>
         <function>enum_last</function>
        </entry>
-       <entry spanname="sig"><function>enum_last</function>(<type>anyenum</type>)
<returnvalue>anyenum</returnvalue></entry>
-      </row>
-      <row>
-       <entry spanname="desc">Returns the last value of the input enum type</entry>
-      </row>
-      <row>
-       <entry spanname="example"><literal>enum_last(&zwsp;null::rainbow)</literal></entry>
-       <entry spanname="exresult"><literal>purple</literal></entry>
+       <entry>
+        <function>enum_last</function>(<type>anyenum</type>)
+        <returnvalue>anyenum</returnvalue>
+        <?br?>
+        Returns the last value of the input enum type
+        <?br?>
+        <literal>enum_last(&zwsp;null::rainbow)</literal>
+        <returnvalue>purple</returnvalue>
+       </entry>
       </row>
       <row>
-       <entry spanname="name" morerows="2">
+       <entry valign="middle">
         <indexterm>
          <primary>enum_range</primary>
         </indexterm>
         <function>enum_range</function>
        </entry>
-       <entry spanname="sig"><function>enum_range</function>(<type>anyenum</type>)
<returnvalue>anyarray</returnvalue></entry>
-      </row>
-      <row>
-       <entry spanname="desc">Returns all values of the input enum type in an ordered array</entry>
-      </row>
-      <row>
-       <entry spanname="example"><literal>enum_range(&zwsp;null::rainbow)</literal></entry>
-       <entry spanname="exresult"><literal>{red,orange,yellow,&zwsp;green,blue,purple}</literal></entry>
-      </row>
-      <row>
-       <entry spanname="name" morerows="4"><function>enum_range</function></entry>
-       <entry spanname="sig"><function>enum_range</function>(<type>anyenum</type>, <type>anyenum</type>)
<returnvalue>anyarray</returnvalue></entry>
+       <entry>
+        <function>enum_range</function>(<type>anyenum</type>)
+        <returnvalue>anyarray</returnvalue>
+        <?br?>
+        Returns all values of the input enum type in an ordered array
+        <?br?>
+        <literal>enum_range(&zwsp;null::rainbow)</literal>
+        <returnvalue>{red,orange,yellow,&zwsp;green,blue,purple}</returnvalue>
+       </entry>
       </row>
       <row>
-       <entry spanname="desc">
+       <entry valign="middle"><function>enum_range</function></entry>
+       <entry><function>enum_range</function>(<type>anyenum</type>, <type>anyenum</type>)
+        <returnvalue>anyarray</returnvalue>
+        <?br?>
         Returns the range between the two given enum values, as an ordered
         array. The values must be from the same enum type. If the first
         parameter is null, the result will start with the first value of
         the enum type.
         If the second parameter is null, the result will end with the last
         value of the enum type.
+        <?br?>
+        <literal>enum_range(&zwsp;'orange'::rainbow, 'green'::rainbow)</literal>
+        <returnvalue>{orange,yellow,green}</returnvalue>
+        <?br?>
+        <literal>enum_range(NULL, 'green'::rainbow)</literal>
+        <returnvalue>{red,orange,&zwsp;yellow,green}</returnvalue>
+        <?br?>
+        <literal>enum_range(&zwsp;'orange'::rainbow, NULL)</literal>
+        <returnvalue>{orange,yellow,green,&zwsp;blue,purple}</returnvalue>
        </entry>
       </row>
-      <row>
-       <entry spanname="example"><literal>enum_range(&zwsp;'orange'::rainbow, 'green'::rainbow)</literal></entry>
-       <entry spanname="exresult"><literal>{orange,yellow,green}</literal></entry>
-      </row>
-      <row>
-       <entry spanname="example"><literal>enum_range(NULL, 'green'::rainbow)</literal></entry>
-       <entry spanname="exresult"><literal>{red,orange,yellow,&zwsp;green}</literal></entry>
-      </row>
-      <row>
-       <entry spanname="example"><literal>enum_range(&zwsp;'orange'::rainbow, NULL)</literal></entry>
-       <entry spanname="exresult"><literal>{orange,yellow,green,&zwsp;blue,purple}</literal></entry>
-      </row>
      </tbody>
     </tgroup>
    </table>
diff --git a/doc/src/sgml/stylesheet-common.xsl b/doc/src/sgml/stylesheet-common.xsl
index a13565e..105ed1c 100644
--- a/doc/src/sgml/stylesheet-common.xsl
+++ b/doc/src/sgml/stylesheet-common.xsl
@@ -103,4 +103,11 @@
   <xsl:apply-templates select="." mode="xref"/>
 </xsl:template>

+
+<!-- Support for explicit line breaks <?br?> within table cells -->
+
+<xsl:template match="processing-instruction('br')">
+  <br/>
+</xsl:template>
+
 </xsl:stylesheet>
diff --git a/doc/src/sgml/stylesheet-fo.xsl b/doc/src/sgml/stylesheet-fo.xsl
index 2aaae82..713159d 100644
--- a/doc/src/sgml/stylesheet-fo.xsl
+++ b/doc/src/sgml/stylesheet-fo.xsl
@@ -70,6 +70,11 @@
   <xsl:call-template name="inline.monoseq"/>
 </xsl:template>

+<!-- overrides stylesheet-common.xsl -->
+<xsl:template match="processing-instruction('br')">
+  <fo:block/>
+</xsl:template>
+
 <!-- bug fix from <https://sourceforge.net/p/docbook/bugs/1360/#831b> -->

 <xsl:template match="varlistentry/term" mode="xref-to">