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

On Mon, 13 Apr 2020 at 13:13, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:

> As discussed in the thread at [1], I've been working on redesigning
> the tables we use to present SQL functions and operators. The
> first installment of that is now up; see tables 9.30 and 9.31 at
>
> https://www.postgresql.org/docs/devel/functions-datetime.html
>
> and table 9.33 at
>
> https://www.postgresql.org/docs/devel/functions-enum.html
>
> Before I spend more time on this, I want to make sure that people
> are happy with this line of attack. Comparing these tables to
> the way they look in v12, they clearly take more vertical space;
> but at least to my eye they're less cluttered and more readable.
> They definitely scale a lot better for cases where a long function
> description is needed, or where we'd like to have more than one
> example. Does anyone prefer the old way, or have a better idea?
>

I honestly don’t know. My initial reaction is a combination of “that’s
weird” and “that’s cool”. So a few comments, which shouldn’t be taken as
indicating a definite preference:

- showing the signature like this is interesting. For a moment I was
wondering why it doesn’t say, for example, "interval → interval → interval”
then I remembered this is Postgres, not Haskell. On the one hand, I like
putting the signature like this; on the other, I don’t like that the return
type is in a different place in each one. Could it be split into the same
two columns as the example(s); first column inputs, second column results?

- another possibility for the parameters: list each one on a separate line,
together with default (if applicable). Maybe that would be excessively
tall, but it would sure make completely clear just exactly how many
parameters there are and never wrap (well, maybe on a phone, but we can
only do so much).

- for the various current-time-related functions (age, current_time, etc.),
rather than saying “variable”, could it be the actual result with “now”
being taken to be a specific fixed time within the year in which the
documentation was generated? This would be really helpful for example with
being clear that current_time is only the time of day with no date.

- the specific fixed time should be something like (current year)-06-30
18:45:54. I’ve deliberately chosen all values to be outside of the range of
values with smaller ranges. For example, the hour is >12, the limit of the
month field.

- I think there should be much more distinctive lines between the different
functions. As it is the fact that the table is groups of 3 lines doesn’t
jump out at the eye.