Re: Poll: are people okay with function/operator table redesign?

On Mon, Apr 13, 2020 at 4:29 PM Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:
> I wouldn't be averse to dropping the text descriptions for operators
> in places where they seem obvious ... but who decides what is obvious?

Well, we do. We're smart, right? I don't think it's a good idea to add
clutter to table A just because table B needs more details. What
matters is whether table A needs more details.

The v12 version of the "Table 9.30. Date/Time Operators" is not that
wide, and is really quite clear. The new version takes 3 lines per
operator where the old one took one. That's because you've added (1) a
description of the fact that + does addition and - does subtraction,
repeated for each operator, and (2) explicit information about the
input and result types. I don't think either add much, in this case.
The former doesn't really need to be explained, and the latter was
clear enough from the way the examples were presented - everything had
explicit types.

For more complicated cases, one thing we could do is ditch the table
and use a <variablelist> with a separate <varlistentry> for each
operator. So you could have something like:

<varlistentry>
<term><literal>date + date &arrow; timestamp</literal></term>
<listentry>
Lengthy elocution, including an example.
</listentry>
</varlistentry>

But I would only advocate for this style in cases where there is
substantial explaining to be done.

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company