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

From: Robert Haas <robertmhaas(at)gmail(dot)com>
To: Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us>
Cc: Alvaro Herrera <alvherre(at)2ndquadrant(dot)com>, PostgreSQL Hackers <pgsql-hackers(at)lists(dot)postgresql(dot)org>
Subject: Re: Poll: are people okay with function/operator table redesign?
Date: 2020-04-14 14:59:53
Message-ID: CA+Tgmoaw7H-88SKXtfKSvv3Bp_LSnFcMLDVCiFFQnnouiDecAg@mail.gmail.com
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-hackers

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

In response to

Responses

Browse pgsql-hackers by date

  From Date Subject
Next Message Stephen Frost 2020-04-14 15:08:25 Re: where should I stick that backup?
Previous Message Tom Lane 2020-04-14 14:52:59 Re: Poll: are people okay with function/operator table redesign?