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

On Mon, Apr 13, 2020 at 1:13 PM Tom Lane <tgl@sss.pgh.pa.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 find the new way quite hard to read. I prefer the old way.

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

On 2020-04-13 19:13, Tom Lane 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?

+1

In the pdf it is a big improvement; and the html is better too.

On Mon, 13 Apr 2020 at 13:13, Tom Lane <tgl@sss.pgh.pa.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.

On 2020-Apr-13, Tom Lane 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.

I am torn. On the one side, I think this new format is so much better
than the old one that we should definitely use it for all tables. On
the other side, I also think this format is slightly more complicated to
read, so perhaps it would be sensible to keep using the old format for
the simplest tables.

One argument for the first of those positions is that if this new table
layout is everywhere, it'll take less total time to get used to it.

One improvement (that I don't know is possible in docbook) would be to
have the inter-logical-row line be slightly thicker than the
intra-logical-row one. That'd make each entry visually more obvious.

I think you already mentioned the PDF issue that these multi-row entries
are sometimes split across pages. I cannot believe docbook is so stupid
not to have a solution to that problem, but I don't know what that
solution would be.

--
�lvaro Herrera https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

Isaac Morland <isaac.morland@gmail.com> writes:

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

We tried that in an earlier iteration (see the referenced thread). It
doesn't work very well because you end up having to allocate the max
amount of space for any result type or example result on every line.
Giving up the separate cell for return type is a lot of what makes this
workable.

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

Since so few built-in functions have default parameters, that's going to
waste an awful lot of space in most cases. I actually ended up removing
the explicit "default" clauses from make_interval (which is the only
function with defaults that I dealt with so far) and instead explained
that they all default to zero in the text description, because that took
way less space.

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

Yeah, I've been waffling about that. On the one hand, we regularly get
docs complaints from people who say "I tried this example and I didn't
get the claimed result". On the other hand you could figure that
everybody should understand that current_timestamp won't work like that
... but the first such example in the table is age() for which that
automatic understanding might not apply.

The examples down in 9.9.4 use a specific time, which is looking pretty
long in the tooth right now, and no one has complained --- but that's
in a context where it's absolutely plain that every mentioned function
is going to have a time-varying result.

On the whole I'm kind of leaning to going back to using a specific time.
But that's a detail that's not very relevant to the bigger picture here.
(No, I'm not going to try to make it update every year; too much work
for too little reward.)

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

I don't know any easy way to do that. We do already have the grouping
visible in the first column...

regards, tom lane

Alvaro Herrera <alvherre@2ndquadrant.com> writes:

One improvement (that I don't know is possible in docbook) would be to
have the inter-logical-row line be slightly thicker than the
intra-logical-row one. That'd make each entry visually more obvious.

Yeah, I don't see any way to do that :-(. We could suppress the row
lines entirely between the members of the logical group, but that'd
almost surely look worse.

(I tried to implement this to see, and couldn't get rowsep="0" in
a <spanspec> to render the way I expected, so there may be toolchain
bugs in the way of it anyway.)

We could leave an entirely empty row between logical groups, but
that would be really wasteful of vertical space.

Another possibility, which'd only help in HTML, would be to render
some of the cells with a slightly different background color.
That's beyond my docbook/css skills, but it might be possible.

regards, tom lane

On Mon, Apr 13, 2020 at 2:47 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:

Another possibility, which'd only help in HTML, would be to render
some of the cells with a slightly different background color.
That's beyond my docbook/css skills, but it might be possible.

I think some visual distinction would be really helpful, if we can get it.

I just wonder if there's too much clutter here. Like, line 1:

date - interval → timestamp

OK, gotcha. Line 2:

Subtract an interval from a date

Well, is that really adding anything non-obvious?

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

On 4/13/20 1:13 PM, Tom Lane 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 know that the table headings are a bit weirdly laid out; hopefully
that can be resolved [2].

regards, tom lane

[1] /messages/by-id/9326.1581457869@sss.pgh.pa.us
[2] /messages/by-id/6169.1586794603@sss.pgh.pa.us

Gotta say I'm not a huge fan. I appreciate the effort, and I get the
problem, but I'm not sure we have a net improvement here.

One thing that did occur to me is that the function/operator name is
essentially redundant, as it's in the signature anyway. Not sure if that
helps us any though.

Maybe we're just trying to shoehorn too much information into a single
table.

cheers

andrew

--
Andrew Dunstan https://www.2ndQuadrant.com
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

Robert Haas <robertmhaas@gmail.com> writes:

I just wonder if there's too much clutter here. Like, line 1:

date - interval → timestamp

OK, gotcha. Line 2:

Subtract an interval from a date

Well, is that really adding anything non-obvious?

Yeah, back in the other thread I said

I decided to try converting the date/time operators table too, to
see how well this works for that. It's bulkier than before, but
also (I think) more precise. I realized that this table actually
had three examples already for float8 * interval, but it wasn't
at all obvious that they were the same operator. So that aspect
is a lot nicer here. On the other hand, it seems like the text
descriptions are only marginally useful here. I can imagine that
they would be useful in some other operator tables, such as
geometric operators, but I'm a bit tempted to leave them out
in this particular table. The format would adapt to that easily.

I wouldn't be averse to dropping the text descriptions for operators
in places where they seem obvious ... but who decides what is obvious?

Indeed, we've gotten more than one complaint in the past that some of the
geometric and JSON operators require a longer explanation than they've
got. So one of the points here was to have a format that could adapt to
that. But in this particular table I agree they're marginal.

regards, tom lane

On Mon, Apr 13, 2020 at 11:27 AM Tom Lane <tgl@sss.pgh.pa.us> wrote:

Isaac Morland <isaac.morland@gmail.com> writes:

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

I don't know any easy way to do that. We do already have the grouping
visible in the first column...

Can we lightly background color every other rowgroup (i.e., "greenbar")?

I don't think having a separate Result column helps. The additional
horizontal whitespace distances all relevant context information (at least
on a wide monitor). Having the example rows mirror the Signature row seems
like an easier to consume choice.

e.g.,

enum_first(null::rainbow) → red

date '2001-09-28' + 7 → 2001-10-05

Its also removes the left alignment in a fixed width column which draws
unwanted visual attention.

David J.

Andrew Dunstan <andrew.dunstan@2ndquadrant.com> writes:

One thing that did occur to me is that the function/operator name is
essentially redundant, as it's in the signature anyway. Not sure if that
helps us any though.

Hm, you have a point there. However, if we drop the lefthand column
then there really isn't any visual distinction between the row(s)
associated with one function and those of the next. Unless we can
find another fix for that aspect (as already discussed in this thread)
I doubt it'd be an improvement.

Maybe we're just trying to shoehorn too much information into a single
table.

Yeah, back at the beginning of this exercise, Alvaro wondered aloud
if we should go to something other than tables altogether. I dunno
what that'd look like though.

regards, tom lane

"David G. Johnston" <david.g.johnston@gmail.com> writes:

Can we lightly background color every other rowgroup (i.e., "greenbar")?

If you know how to do that at all, let alone in a maintainable way (ie
one where inserting a new function doesn't require touching the entries
for the ones after), let's see it. I agree it'd be a nice solution,
if we could make it work, but I don't see how. I'd been imagining
instead that we could give a different background color to the first
line of each group; which I don't know how to do but it at least seems
plausible that a style could be attached to a <spanspec>.

I don't think having a separate Result column helps. The additional
horizontal whitespace distances all relevant context information (at least
on a wide monitor). Having the example rows mirror the Signature row seems
like an easier to consume choice.

Interesting idea. I'm afraid that it would not look so great in cases
where the example-plus-result overflows one line, which would inevitably
happen in PDF format. Still, maybe that would be rare enough to not be
a huge problem. In most places it'd be a win to not have to separately
allocate example and result space.

regards, tom lane

I wrote:

"David G. Johnston" <david.g.johnston@gmail.com> writes:

I don't think having a separate Result column helps. The additional
horizontal whitespace distances all relevant context information (at least
on a wide monitor). Having the example rows mirror the Signature row seems
like an easier to consume choice.

Interesting idea. I'm afraid that it would not look so great in cases
where the example-plus-result overflows one line, which would inevitably
happen in PDF format. Still, maybe that would be rare enough to not be
a huge problem. In most places it'd be a win to not have to separately
allocate example and result space.

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.

A quick google search turned up this suggestion about how to force
line breaks in docbook table cells:

http://www.sagehill.net/docbookxsl/LineBreaks.html

which seems pretty hacky but it should work. Anyone know a better
way?

regards, tom lane

On Mon, Apr 13, 2020 at 1:41 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:

"David G. Johnston" <david.g.johnston@gmail.com> writes:

Can we lightly background color every other rowgroup (i.e., "greenbar")?

If you know how to do that at all, let alone in a maintainable way (ie
one where inserting a new function doesn't require touching the entries
for the ones after), let's see it.

The nth-child({odd|even}) CSS Selector should provide the desired
functionality, at least for HTML, but the structure will need to modified
so that there is some single element that represents a single rowgroup. I
tried (not too hard) to key off of the presence of the "rowspan" attribute
but that does not seem possible.

https://www.w3schools.com/cssref/sel_nth-child.asp

David J.

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.

David J.

On 4/13/20 1:13 PM, Tom Lane 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 know that the table headings are a bit weirdly laid out; hopefully
that can be resolved [2].

[2] /messages/by-id/6169.1586794603@sss.pgh.pa.us

When evaluating [2], I will admit at first I was very confused about the
layout and wasn't exactly sure what you were saying was incorrect in
that note. After fixing [2] on my local copy, I started to look at it again.

For positives, I do think it's an improvement for readability on mobile.
Flow/content aside, it was easier to read and follow what was going on
and there was less side scrolling.

I think one thing that was throwing me off was having the function
signature before the description. I would recommend flipping them: have
the function description first, followed by signature, followed be
examples. I think that follows the natural flow more of what one is
doing when they look up the function.

I think that would also benefit larger tables too: instead of having to
scroll up to understand how things are laid out, it'd follow said flow.

There are probably some things we can do with shading on the pgweb side
to make items more distinguishable, I don't think that would be too
terrible to add.

Thinking out loud, it'd also be great if we could add in some anchors as
well, so perhaps in the future on the pgweb side we could add in some
discoverable links that other documentation has -- which in turn people
could click / link to others directly to the function name.

Anyway, change is hard. I'm warming up to it.

Jonathan

Thinking out loud, it'd also be great if we could add in some anchors as
well, so perhaps in the future on the pgweb side we could add in some
discoverable links that other documentation has -- which in turn people
could click / link to others directly to the function name.

+1

"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

Yeah, back at the beginning of this exercise, Alvaro wondered aloud
if we should go to something other than tables altogether. I dunno
what that'd look like though.

It would probably look like our acronyms and glossary pages.

Maybe the return example and return values get replaced with a
programlisting?