From: Tom Lane <tgl@sss.pgh.pa.us>
To: David G. Johnston <david.g.johnston@gmail.com>
Cc: Isaac Morland <isaac.morland@gmail.com>
Cc: PostgreSQL Developers <pgsql-hackers@lists.postgresql.org>
Subject: Re: Poll: are people okay with function/operator table redesign?
Date: Mon, 13 Apr 2020 18:44:36 -0400
Message-ID: <31833.1586817876@sss.pgh.pa.us> (raw)
In-Reply-To: <CAKFQuwbySB9vwjhOLb7LSMznfoJ4_8LS+P1tXoG0pAnYKK5OPA@mail.gmail.com>
References: <8691.1586798003@sss.pgh.pa.us>
<CAMsGm5fobXxwF1_WZqy4rTC-cNWOu4pdL1Maagyrdfkwr7nCJg@mail.gmail.com>
<12135.1586802423@sss.pgh.pa.us>
<CAKFQuwYZLn3+-aBi3HBKywMmjtyiSUZqnwzkJ-aYsZ0ORyS8gA@mail.gmail.com>
<18168.1586810511@sss.pgh.pa.us>
<18929.1586811439@sss.pgh.pa.us>
<CAKFQuwbySB9vwjhOLb7LSMznfoJ4_8LS+P1tXoG0pAnYKK5OPA@mail.gmail.com>
"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
Attachments:table-format-hackery.patch (text/x-diff, 7.7K) downloaddiff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgmlindex 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.xslindex 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.xslindex 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">
HTML-br.png (image/png, 218.5K) downloadview imageHTML-hr.png (image/png, 230.1K) downloadview imagePDF.png (image/png, 136.6K) downloadview image
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-hackers@postgresql.org
Cc: tgl@sss.pgh.pa.us, david.g.johnston@gmail.com, isaac.morland@gmail.com, pgsql-hackers@lists.postgresql.org
Subject: Re: Poll: are people okay with function/operator table redesign?
In-Reply-To: <31833.1586817876@sss.pgh.pa.us>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox