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

Robert Haas <robertmhaas(at)gmail(dot)com> writes:
> The v12 version of the "Table 9.30. Date/Time Operators" is not that
> wide, and is really quite clear.

Well, no it isn't. The main nit I would pick in that claim is that
it's far from obvious that the three examples of float8 * interval
are all talking about the same operator; in fact, a reader would
be very likely to draw the false conclusion that there is an
integer * interval operator.

This is an aspect of the general problem that we don't have a nice
way to deal with multiple examples in the tables. Somebody kluged
their way around it here in this particular way, but I'd really like
a clearer way, because we need more examples.

I would also point out that this table is quite out of step with
the rest of the docs in its practice of showing the results as
though they were typed literals. Most places that show results
just show what you'd expect to see in a psql output column, making
it necessary to show the result data type somewhere else.

> 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.

As I already said, I agree about the text descriptions being of marginal
value in this case. I disagree about the explicit datatypes, because the
float8 * interval cases already show a hole in that argument, and surely
we don't want to require every example to use explicitly-typed literals
and nothing but. Besides, what will you do for operators that take
anyarray or the like?

> 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:
> ...
> But I would only advocate for this style in cases where there is
> substantial explaining to be done.

I'd like to have more consistency, not less. I do not think it helps
readers to have each page in Chapter 9 have its own idiosyncratic way of
presenting operators/functions. The operator tables are actually almost
that bad, right now --- compare section 9.1 (hasn't even bothered with
a formal <table>) with tables 9.1, 9.4, 9.9, 9.12, 9.14, 9.30, 9.34,
9.37, 9.41, 9.44. The variation in level of detail and precision is
striking, and not in a good way.

regards, tom lane