Thread

Commits

Doc: re-re-revise markup for tables of functions.
- 4ad047a6eac3 13.0 landed
Doc: revise formatting of function/operator tables.
- 737d69ffc3cf 13.0 landed

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

Tom Lane <tgl@sss.pgh.pa.us> — 2020-04-13T17:13:23Z

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] https://www.postgresql.org/message-id/flat/9326.1581457869%40sss.pgh.pa.us
[2] https://www.postgresql.org/message-id/6169.1586794603%40sss.pgh.pa.us

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

Robert Haas <robertmhaas@gmail.com> — 2020-04-13T17:37:30Z

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

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

Erik Rijkers <er@xs4all.nl> — 2020-04-13T17:52:25Z

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.

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

Isaac Morland <isaac.morland@gmail.com> — 2020-04-13T17:57:03Z

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.

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

Alvaro Herrera <alvherre@2ndquadrant.com> — 2020-04-13T18:07:58Z

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

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

Tom Lane <tgl@sss.pgh.pa.us> — 2020-04-13T18:27:03Z

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

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

Tom Lane <tgl@sss.pgh.pa.us> — 2020-04-13T18:47:27Z

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

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

Robert Haas <robertmhaas@gmail.com> — 2020-04-13T20:18:46Z

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

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

Andrew Dunstan <andrew.dunstan@2ndquadrant.com> — 2020-04-13T20:20:38Z

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] https://www.postgresql.org/message-id/flat/9326.1581457869%40sss.pgh.pa.us
> [2] https://www.postgresql.org/message-id/6169.1586794603%40sss.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

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

Tom Lane <tgl@sss.pgh.pa.us> — 2020-04-13T20:29:07Z

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

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

David G. Johnston <david.g.johnston@gmail.com> — 2020-04-13T20:31:51Z

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.

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

Tom Lane <tgl@sss.pgh.pa.us> — 2020-04-13T20:33:52Z

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

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

Tom Lane <tgl@sss.pgh.pa.us> — 2020-04-13T20:41:51Z

"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

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

Tom Lane <tgl@sss.pgh.pa.us> — 2020-04-13T20:57:19Z

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

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

David G. Johnston <david.g.johnston@gmail.com> — 2020-04-13T21:20:40Z

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.

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

David G. Johnston <david.g.johnston@gmail.com> — 2020-04-13T21:26:10Z

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.

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

Jonathan S. Katz <jkatz@postgresql.org> — 2020-04-13T22:33:58Z

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] https://www.postgresql.org/message-id/6169.1586794603%40sss.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

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

Corey Huinker <corey.huinker@gmail.com> — 2020-04-13T22:38:23Z

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

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

Tom Lane <tgl@sss.pgh.pa.us> — 2020-04-13T22:44:36Z

"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

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

Corey Huinker <corey.huinker@gmail.com> — 2020-04-13T22:48:46Z

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

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

Tom Lane <tgl@sss.pgh.pa.us> — 2020-04-13T22:51:33Z

"Jonathan S. Katz" <jkatz@postgresql.org> writes:
> 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.

The trouble with that is it doesn't work very well when we have
multiple similarly-named functions with different signatures.
Consider what the two enum_range() entries in 9.33 will look like,
for example.  I think we need the signature to establish which function
we're talking about.

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

Per David's earlier comment, it seems like alternating backgrounds might
be feasible if we can get it down to one <row> per function, as the
version I just posted has.

			regards, tom lane

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

Jonathan S. Katz <jkatz@postgresql.org> — 2020-04-13T23:02:57Z

On 4/13/20 6:51 PM, Tom Lane wrote:
> "Jonathan S. Katz" <jkatz@postgresql.org> writes:
>> 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.
> 
> The trouble with that is it doesn't work very well when we have
> multiple similarly-named functions with different signatures.
> Consider what the two enum_range() entries in 9.33 will look like,
> for example.  I think we need the signature to establish which function
> we're talking about.

I get that, I just find I'm doing too much thinking looking at it.

Perhaps a counterproposal: We eliminate the content in the leftmost
"function column, but leave that there to allow the function name /
signature to span the full 3 columns. Then the rest of the info goes
below. This will also compress the table height down a bit.

>> 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.
> 
> Per David's earlier comment, it seems like alternating backgrounds might
> be feasible if we can get it down to one <row> per function, as the
> version I just posted has.

or a classname on the "<tr>" when a new function starts or the like.
Easy enough to get the CSS to work off of that :)

Jonathan

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

Jonathan S. Katz <jkatz@postgresql.org> — 2020-04-13T23:38:15Z

On 4/13/20 7:02 PM, Jonathan S. Katz wrote:
> On 4/13/20 6:51 PM, Tom Lane wrote:
>> "Jonathan S. Katz" <jkatz@postgresql.org> writes:
>>> 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.
>>
>> The trouble with that is it doesn't work very well when we have
>> multiple similarly-named functions with different signatures.
>> Consider what the two enum_range() entries in 9.33 will look like,
>> for example.  I think we need the signature to establish which function
>> we're talking about.
> 
> I get that, I just find I'm doing too much thinking looking at it.
> 
> Perhaps a counterproposal: We eliminate the content in the leftmost
> "function column, but leave that there to allow the function name /
> signature to span the full 3 columns. Then the rest of the info goes
> below. This will also compress the table height down a bit.

An attempt at a "POC" of what I'm describing (attached image).

I'm not sure if I 100% like it, but it does reduce the amount of
information we're displaying but conveys all the details (and matches
what we have in the previous version).

The alignment could be adjusted if need be, too.

Jonathan

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

Tom Lane <tgl@sss.pgh.pa.us> — 2020-04-13T23:48:35Z

I wrote:
> 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.

Actually, after staring more at HTML-hr.png, what's *really* bothering
me about that rendering is that the lines made by <hr/> are actually
wider than the inter-table-cell lines.  Surely we want the opposite
relationship.  Presumably that could be fixed with some css-level
adjustments; and maybe the spacing could be tightened up a bit too?
I do like having that visual separation, it just needs to be toned
down compared to the table cell separators.

Reproducing the effect in the PDF build remains an issue, too.

			regards, tom lane

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

Alvaro Herrera <alvherre@2ndquadrant.com> — 2020-04-13T23:50:52Z

On 2020-Apr-13, Jonathan S. Katz wrote:

> On 4/13/20 7:02 PM, Jonathan S. Katz wrote:

> > Perhaps a counterproposal: We eliminate the content in the leftmost
> > "function column, but leave that there to allow the function name /
> > signature to span the full 3 columns. Then the rest of the info goes
> > below. This will also compress the table height down a bit.
> 
> An attempt at a "POC" of what I'm describing (attached image).
> 
> I'm not sure if I 100% like it, but it does reduce the amount of
> information we're displaying but conveys all the details (and matches
> what we have in the previous version).

Ooh, this seems a nice idea -- the indentation seems to be sufficient to
tell apart entries from each other.  Your point about information
reduction refers to the fact that we no longer keep the unadorned name
but only the signature, right?  That seems an improvement to me now that
I look at it.

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

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

Tom Lane <tgl@sss.pgh.pa.us> — 2020-04-13T23:55:00Z

"Jonathan S. Katz" <jkatz@postgresql.org> writes:
> On 4/13/20 7:02 PM, Jonathan S. Katz wrote:
>> Perhaps a counterproposal: We eliminate the content in the leftmost
>> "function column, but leave that there to allow the function name /
>> signature to span the full 3 columns. Then the rest of the info goes
>> below. This will also compress the table height down a bit.

> An attempt at a "POC" of what I'm describing (attached image).

Hmm ... what is determining the width of the left-hand column?
It doesn't seem to have any content, since the function entries
are being spanned across the whole table.

I think the main practical problem though is that it wouldn't
work nicely for operators, since the key "name" you'd be looking
for would not be at the left of the signature line.  I suppose we
don't necessarily have to have the same layout for operators as
for functions, but it feels like it'd be jarringly inconsistent.

			regards, tom lane

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

Fabien COELHO <coelho@cri.ensmp.fr> — 2020-04-14T05:23:37Z

Hello Tom,

> Before I spend more time on this, I want to make sure that people
> are happy with this line of attack.

+1

I like it this way, because the structure is quite readable, which is the 
point.

My 0.02€:

Maybe column heander "Example Result" should be simply "Result", because 
it is already on the same line as "Example" on its left, and "Example | 
Example Result" looks redundant.

Maybe the signature and description lines could be exchanged: I'm more 
interested and the description first, and the signature just above the 
example would make sense.

I'm wondering whether the function/operator name should be vertically 
centered in its cell? I'd left it left justified.

-- 
Fabien.

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

Andrew Dunstan <andrew.dunstan@2ndquadrant.com> — 2020-04-14T13:01:00Z

On 4/13/20 7:55 PM, Tom Lane wrote:
> "Jonathan S. Katz" <jkatz@postgresql.org> writes:
>> On 4/13/20 7:02 PM, Jonathan S. Katz wrote:
>>> Perhaps a counterproposal: We eliminate the content in the leftmost
>>> "function column, but leave that there to allow the function name /
>>> signature to span the full 3 columns. Then the rest of the info goes
>>> below. This will also compress the table height down a bit.
>> An attempt at a "POC" of what I'm describing (attached image).
> Hmm ... what is determining the width of the left-hand column?
> It doesn't seem to have any content, since the function entries
> are being spanned across the whole table.
>
> I think the main practical problem though is that it wouldn't
> work nicely for operators, since the key "name" you'd be looking
> for would not be at the left of the signature line.  I suppose we
> don't necessarily have to have the same layout for operators as
> for functions, but it feels like it'd be jarringly inconsistent.
>
> 			



Maybe highlight the item by bolding or colour?


cheers


andrew

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

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

Andreas Karlsson <andreas@proxel.se> — 2020-04-14T14:16:07Z

On 4/13/20 7: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].

I prefer the old way since I find it very hard to see which fields 
belong to which function in the new way. I think what confuses my eyes 
is how some rows are split in half while others are not, especially for 
those functions where there is only one example output. I do not have 
any issue reading those with many example outputs.

For the old tables I can at least just make the browser window 
ridiculously wide ro read them.

Andreas

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

Tom Lane <tgl@sss.pgh.pa.us> — 2020-04-14T14:29:04Z

Andreas Karlsson <andreas@proxel.se> writes:
> For the old tables I can at least just make the browser window 
> ridiculously wide ro read them.

A large part of the point here is to make the tables usable
when you don't have that option, as for example in PDF output.

Even with a wide window, though, some of our function tables are
monstrously ugly.

			regards, tom lane

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

Andreas Karlsson <andreas@proxel.se> — 2020-04-14T14:39:44Z

On 4/14/20 4:29 PM, Tom Lane wrote:
> Andreas Karlsson <andreas@proxel.se> writes:
>> For the old tables I can at least just make the browser window
>> ridiculously wide ro read them.
> 
> A large part of the point here is to make the tables usable
> when you don't have that option, as for example in PDF output.
> 
> Even with a wide window, though, some of our function tables are
> monstrously ugly.

Sure, but I wager the number of people using the HTML version of our 
documentation on laptops and desktop computers are the biggest group of 
users.

That said, I agree with that quite many of our tables right now are 
ugly, but I prefer ugly to hard to read. For me the mix of having every 
third row split into two fields makes the tables very hard to read. I 
have a hard time seeing which rows belong to which function.

Andreas

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

Tom Lane <tgl@sss.pgh.pa.us> — 2020-04-14T14:52:59Z

Andreas Karlsson <andreas@proxel.se> writes:
> That said, I agree with that quite many of our tables right now are 
> ugly, but I prefer ugly to hard to read. For me the mix of having every 
> third row split into two fields makes the tables very hard to read. I 
> have a hard time seeing which rows belong to which function.

Did you look at the variants without that discussed downthread?

			regards, tom lane

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

Robert Haas <robertmhaas@gmail.com> — 2020-04-14T14:59:53Z

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

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

Tom Lane <tgl@sss.pgh.pa.us> — 2020-04-14T15:26:19Z

Robert Haas <robertmhaas@gmail.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

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

Robert Haas <robertmhaas@gmail.com> — 2020-04-14T15:47:12Z

On Tue, Apr 14, 2020 at 11:26 AM Tom Lane <tgl@sss.pgh.pa.us> wrote:
> 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.

I agree that's not great. I think that could possibly be fixed by
showing all three examples in the same cell, and maybe by revising the
choice of examples.

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

Well, I don't know. Having two or even three formats is not the same
as having infinitely many formats, and may be justified if the needs
are sufficiently different from each other.

At any rate, if the price of more clarity and more examples is that
the tables become three times as long and harder to read, I am
somewhat inclined to think that the cure is worse than the disease. I
can readily see how something like table 9.10 (Other String Functions)
might be a mess on a narrow screen or in PDF format, but it's an
extremely useful table on a normal-size screen in HTML format, and
part of what makes it useful is that it's compact. Almost anything we
do is going to remove some of that compactness to save horizontal
space. Maybe that's OK, but it's sure not great. It's nice to be able
to see more on one screen.

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

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

Tom Lane <tgl@sss.pgh.pa.us> — 2020-04-14T16:03:00Z

Robert Haas <robertmhaas@gmail.com> writes:
> At any rate, if the price of more clarity and more examples is that
> the tables become three times as long and harder to read, I am
> somewhat inclined to think that the cure is worse than the disease. I
> can readily see how something like table 9.10 (Other String Functions)
> might be a mess on a narrow screen or in PDF format, but it's an
> extremely useful table on a normal-size screen in HTML format, and
> part of what makes it useful is that it's compact. Almost anything we
> do is going to remove some of that compactness to save horizontal
> space. Maybe that's OK, but it's sure not great. It's nice to be able
> to see more on one screen.

I dunno, it doesn't look to me like 9.10 is some paragon of efficient
use of screen space, even with a wide window.  (And my goodness it
looks bad if I try a window about half my usual web-browsing width.)
Maybe I should go convert that one to see what it looks like in one of
the other layouts being discussed.

			regards, tom lane

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

David G. Johnston <david.g.johnston@gmail.com> — 2020-04-14T22:28:13Z

On Mon, Apr 13, 2020 at 10:13 AM 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
>
>
As I write this the enum headers are centered horizontally while the
datetime ones are left aligned.  The centering doesn't do it for me.  To
much gap and the data itself is not centered so there is a large
disconnected between the header and the value.

The run-on aspect of the left-aligned setup is of some concern but maybe
just adding some left padding to the second column - and right padding to
the first - can provide the desired negative space without adding so much
as to break usability.

(gonna use embedded images here...)

[image: image.png]

[image: image.png]
David J.

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

Pierre Giraud <pierre.giraud@dalibo.com> — 2020-04-15T15:25:58Z

Hi all,

Sorry I'm very new on this discussion. A colleague of mine told me I
could probably give my opinion on this thread.

I'm sorry in advance if I'm off topic. I just wanted to mention that
from Tom's proposal I played a bit with the generated HTML in order to
try to make things easier to read without thinking about technical
issues for now.

The first big issue (that may have already been mentioned) in my opinion
is that different elements are difficult to distinguish. It's difficult
for example to know what is the return type, what is the description, etc.

I think that if the idea is to get rid of the columns, you need to make
sure that it's easy to know which is which. With a very short amount of
time, the user should be able to find what he's looking for.

The best way to achieve this is to use some styling (font style and color).

Attached you will find two different options I worked on very quickly.

I would be happy to give more hints on how I did this of course and why
I chose some options. Please let me know.

Kind regards,


Le 13/04/2020 à 19:13, Tom Lane a écrit :
> 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] https://www.postgresql.org/message-id/flat/9326.1581457869%40sss.pgh.pa.us
> [2] https://www.postgresql.org/message-id/6169.1586794603%40sss.pgh.pa.us
> 
>

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

Isaac Morland <isaac.morland@gmail.com> — 2020-04-15T15:43:24Z

On Wed, 15 Apr 2020 at 11:26, Pierre Giraud <pierre.giraud@dalibo.com>
wrote:


> The best way to achieve this is to use some styling (font style and color).
>
> Attached you will find two different options I worked on very quickly.
>

I really like the first. Just a couple of suggestions I would make:

- leave a space between the function name and (. Regardless of opinions on
what source code should look like, your documentation has space between
each parameter and the next one, and between the ) and the -> and the ->.
and the return type so it seems crowded not to have space between the
function name and the (.
- At this point it's not really a table any more; I would get rid of the
lines, maybe tweak the spacing, and possibly use <dl> <dt> <dd> (definition
list) rather than table-related HTML elements. See
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dl.

I think the bolding really makes stand out the crucial parts one needs to
find.

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

Pavel Stehule <pavel.stehule@gmail.com> — 2020-04-15T15:53:54Z

st 15. 4. 2020 v 17:43 odesílatel Isaac Morland <isaac.morland@gmail.com>
napsal:

> On Wed, 15 Apr 2020 at 11:26, Pierre Giraud <pierre.giraud@dalibo.com>
> wrote:
>
>
>> The best way to achieve this is to use some styling (font style and
>> color).
>>
>> Attached you will find two different options I worked on very quickly.
>>
>
> I really like the first. Just a couple of suggestions I would make:
>

yes, it is very well readable

Pavel


> - leave a space between the function name and (. Regardless of opinions on
> what source code should look like, your documentation has space between
> each parameter and the next one, and between the ) and the -> and the ->.
> and the return type so it seems crowded not to have space between the
> function name and the (.
> - At this point it's not really a table any more; I would get rid of the
> lines, maybe tweak the spacing, and possibly use <dl> <dt> <dd> (definition
> list) rather than table-related HTML elements. See
> https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dl.
>
> I think the bolding really makes stand out the crucial parts one needs to
> find.
>
>

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

Robert Haas <robertmhaas@gmail.com> — 2020-04-15T16:04:34Z

On Wed, Apr 15, 2020 at 11:54 AM Pavel Stehule <pavel.stehule@gmail.com> wrote:
> st 15. 4. 2020 v 17:43 odesílatel Isaac Morland <isaac.morland@gmail.com> napsal:
>> On Wed, 15 Apr 2020 at 11:26, Pierre Giraud <pierre.giraud@dalibo.com> wrote:
>>> The best way to achieve this is to use some styling (font style and color).
>>>
>>> Attached you will find two different options I worked on very quickly.
>>
>> I really like the first. Just a couple of suggestions I would make:
>
> yes, it is very well readable

+1.

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

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

Steven Pousty <steve.pousty@gmail.com> — 2020-04-15T17:10:59Z

Is there a way to get a heavier line between each function? It would be
helpful to have a clearer demarcation of what belongs to each function.

On Wed, Apr 15, 2020 at 9:04 AM Robert Haas <robertmhaas@gmail.com> wrote:

> On Wed, Apr 15, 2020 at 11:54 AM Pavel Stehule <pavel.stehule@gmail.com>
> wrote:
> > st 15. 4. 2020 v 17:43 odesílatel Isaac Morland <isaac.morland@gmail.com>
> napsal:
> >> On Wed, 15 Apr 2020 at 11:26, Pierre Giraud <pierre.giraud@dalibo.com>
> wrote:
> >>> The best way to achieve this is to use some styling (font style and
> color).
> >>>
> >>> Attached you will find two different options I worked on very quickly.
> >>
> >> I really like the first. Just a couple of suggestions I would make:
> >
> > yes, it is very well readable
>
> +1.
>
> --
> Robert Haas
> EnterpriseDB: http://www.enterprisedb.com
> The Enterprise PostgreSQL Company
>
>
>

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

Tom Lane <tgl@sss.pgh.pa.us> — 2020-04-15T17:19:07Z

Steven Pousty <steve.pousty@gmail.com> writes:
> Is there a way to get a heavier line between each function? It would be
> helpful to have a clearer demarcation of what belongs to each function.

The first alternative I posted at

https://www.postgresql.org/message-id/31833.1586817876%40sss.pgh.pa.us

seems like it would accomplish that pretty well, by having lines
*only* between functions.  The last couple of things that have been
posted seem way more cluttered than that one.

			regards, tom lane

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

David G. Johnston <david.g.johnston@gmail.com> — 2020-04-15T18:56:31Z

On Mon, Apr 13, 2020 at 10:13 AM 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
>
>
The centering of the headers doesn't do it for me.  Too much gap and the
data itself is not centered so there is a large disconnect between the
headers and the values.

The run-on aspect of the left-aligned setup is of some concern but maybe
just adding some left padding to the second column - and right padding to
the first - can provide the desired negative space without adding so much
as to break usability.

David J.

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

Tom Lane <tgl@sss.pgh.pa.us> — 2020-04-15T22:18:54Z

As I threatened to do earlier, I made a pass at converting table 9.10
to a couple of the styles under discussion.  (This is just a
draft-quality patch, so it might have some minor bugs --- the point
is just to see what these styles look like.)

I've concluded after looking around that the ideas involving not having
a <table> at all, but just a <variablelist> or the like, are not very
well-advised.  That would eliminate, or at least greatly degrade, the
visual distinction between the per-function material and the surrounding
commentary.  Which does not seem like a winner to me; for example it
would make it quite hard to skip over the detailed material when you're
just trying to skim the docs.

We did have a number of people suggesting that just reordering things as
"description, signature, examples" might be a good idea, so I gave that
a try; attached is a rendition of a portion of 9.10 in that style (the
"v1" image).  It's not bad, but there's still going to be a lot of
wasted whitespace in tables that include even one long function name.
(9.10's longest is "regexp_split_to_array", so it's showing this problem
significantly.)

I also experimented with Jonathan's idea of dropping the separate
function name and allowing the function signature to span left into
that column -- see "v2" images.  This actually works really well,
and would work even better (IMO) if we could get rid of the inter-row
and inter-column rules within a function entry.  I failed to
accomplish that with rowsep/colsep annotations, but from remarks
upthread I suppose there might be a CSS way to accomplish it.  (But
the rowsep/colsep annotations *do* work in PDF output, so I kept them;
that means we only need a CSS fix and not some kind of flow-object
magic for PDF.)

To allow direct comparison of these 9.10 images against the situation
in HEAD, I've also attached an extract of 9.10 as rendered by my
browser with "STYLE=website".  As you can see this is *not* quite
identical to how it renders on postgresql.org, so there is still some
unexplained differential in font or margins or something.  But if you
look at those three PNGs you can see that either v1 or v2 has a pretty
substantial advantage over HEAD in terms of the amount of space
needed.  v2 would be even further ahead if we could eliminate some of
the vertical space around the intra-function row split, which again
might be doable with CSS magic.

The main disadvantage I can see to the v2 design is that we're back
to having two <rows> per function, which is inevitably going to result
in PDF builds putting page breaks between those rows.  But you can't
have everything ... and maybe we could find a way to discourage such
breaks if we tried.

Another issue is that v2 won't adapt real well to operator tables;
the operator name won't be at the left.  I don't have a lot of faith
in the proposal to fix that with font tricks.  Maybe we could stick
to something close to the layout that table 9.30 has in HEAD (ie
repeating the operator name in column 1), since we won't have long
operator names messing up the format.  Again, CSS'ing our way
out of the internal lines and extra vertical space within a single
logical table cell would make that layout look nicer.

On balance I quite like the v2 layout and would prefer to move forward
with that, assuming we can solve the remaining issues via CSS or style
sheets.

In addition to screenshots, I've attached patches against HEAD that
convert both tables 9.10 and 9.33 into v1 and v2 styles.

			regards, tom lane

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

Kyotaro Horiguchi <horikyota.ntt@gmail.com> — 2020-04-16T05:18:51Z

At Wed, 15 Apr 2020 12:04:34 -0400, Robert Haas <robertmhaas@gmail.com> wrote in 
> On Wed, Apr 15, 2020 at 11:54 AM Pavel Stehule <pavel.stehule@gmail.com> wrote:
> > st 15. 4. 2020 v 17:43 odesílatel Isaac Morland <isaac.morland@gmail.com> napsal:
> >> On Wed, 15 Apr 2020 at 11:26, Pierre Giraud <pierre.giraud@dalibo.com> wrote:
> >>> The best way to achieve this is to use some styling (font style and color).
> >>>
> >>> Attached you will find two different options I worked on very quickly.
> >>
> >> I really like the first. Just a couple of suggestions I would make:
> >
> > yes, it is very well readable
> 
> +1.

+1.

regards.

-- 
Kyotaro Horiguchi
NTT Open Source Software Center

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

Pierre Giraud <pierre.giraud@dalibo.com> — 2020-04-16T06:26:54Z


Le 16/04/2020 à 00:18, Tom Lane a écrit :
> As I threatened to do earlier, I made a pass at converting table 9.10
> to a couple of the styles under discussion.  (This is just a
> draft-quality patch, so it might have some minor bugs --- the point
> is just to see what these styles look like.)
> 
> I've concluded after looking around that the ideas involving not having
> a <table> at all, but just a <variablelist> or the like, are not very
> well-advised.  That would eliminate, or at least greatly degrade, the
> visual distinction between the per-function material and the surrounding
> commentary.  Which does not seem like a winner to me; for example it
> would make it quite hard to skip over the detailed material when you're
> just trying to skim the docs.
> 
> We did have a number of people suggesting that just reordering things as
> "description, signature, examples" might be a good idea, so I gave that
> a try; attached is a rendition of a portion of 9.10 in that style (the
> "v1" image).  It's not bad, but there's still going to be a lot of
> wasted whitespace in tables that include even one long function name.
> (9.10's longest is "regexp_split_to_array", so it's showing this problem
> significantly.)
> 
> I also experimented with Jonathan's idea of dropping the separate
> function name and allowing the function signature to span left into
> that column -- see "v2" images.  This actually works really well,
> and would work even better (IMO) if we could get rid of the inter-row
> and inter-column rules within a function entry.  I failed to
> accomplish that with rowsep/colsep annotations, but from remarks
> upthread I suppose there might be a CSS way to accomplish it.  (But
> the rowsep/colsep annotations *do* work in PDF output, so I kept them;
> that means we only need a CSS fix and not some kind of flow-object
> magic for PDF.)
> 
> To allow direct comparison of these 9.10 images against the situation
> in HEAD, I've also attached an extract of 9.10 as rendered by my
> browser with "STYLE=website".  As you can see this is *not* quite
> identical to how it renders on postgresql.org, so there is still some
> unexplained differential in font or margins or something.  But if you
> look at those three PNGs you can see that either v1 or v2 has a pretty
> substantial advantage over HEAD in terms of the amount of space
> needed.  v2 would be even further ahead if we could eliminate some of
> the vertical space around the intra-function row split, which again
> might be doable with CSS magic.
> 
> The main disadvantage I can see to the v2 design is that we're back
> to having two <rows> per function, which is inevitably going to result
> in PDF builds putting page breaks between those rows.  But you can't
> have everything ... and maybe we could find a way to discourage such
> breaks if we tried.

What about putting everything into one <table row> and use a block with
some left padding/margin for description + example.
This would solve the PDF page break issue as well as the column
separation border one.

The screenshot attached uses a <dl> tag for the descrition/example block.

> 
> Another issue is that v2 won't adapt real well to operator tables;
> the operator name won't be at the left.  I don't have a lot of faith
> in the proposal to fix that with font tricks.  Maybe we could stick
> to something close to the layout that table 9.30 has in HEAD (ie
> repeating the operator name in column 1), since we won't have long
> operator names messing up the format.  Again, CSS'ing our way
> out of the internal lines and extra vertical space within a single
> logical table cell would make that layout look nicer.
> 
> On balance I quite like the v2 layout and would prefer to move forward
> with that, assuming we can solve the remaining issues via CSS or style
> sheets.
> 
> In addition to screenshots, I've attached patches against HEAD that
> convert both tables 9.10 and 9.33 into v1 and v2 styles.
> 
> 			regards, tom lane
>

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

Tom Lane <tgl@sss.pgh.pa.us> — 2020-04-16T14:43:13Z

Pierre Giraud <pierre.giraud@dalibo.com> writes:
> Le 16/04/2020 à 00:18, Tom Lane a écrit :
>> The main disadvantage I can see to the v2 design is that we're back
>> to having two <rows> per function, which is inevitably going to result
>> in PDF builds putting page breaks between those rows.  But you can't
>> have everything ... and maybe we could find a way to discourage such
>> breaks if we tried.

Further experimentation shows that the PDF toolchain is perfectly willing
to put a page break *within* a multi-line <row>; if there is any
preference to break between rows instead, it's pretty weak.  So that
argument is a red herring and we shouldn't waste time chasing it.
However, there'd still be some advantage in not being dependent on CSS
hackery to make it look nice in HTML.

What we're down to wanting, at this point, is basically a para with
hanging indent.

> What about putting everything into one <table row> and use a block with
> some left padding/margin for description + example.
> This would solve the PDF page break issue as well as the column
> separation border one.
> The screenshot attached uses a <dl> tag for the descrition/example block.

That looks about right, perhaps, but could you be a little clearer about
how you accomplished that?

			regards, tom lane

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

Pierre Giraud <pierre.giraud@dalibo.com> — 2020-04-16T15:12:28Z


Le 16/04/2020 à 16:43, Tom Lane a écrit :
> Pierre Giraud <pierre.giraud@dalibo.com> writes:
>> Le 16/04/2020 à 00:18, Tom Lane a écrit :
>>> The main disadvantage I can see to the v2 design is that we're back
>>> to having two <rows> per function, which is inevitably going to result
>>> in PDF builds putting page breaks between those rows.  But you can't
>>> have everything ... and maybe we could find a way to discourage such
>>> breaks if we tried.
> 
> Further experimentation shows that the PDF toolchain is perfectly willing
> to put a page break *within* a multi-line <row>; if there is any
> preference to break between rows instead, it's pretty weak.  So that
> argument is a red herring and we shouldn't waste time chasing it.
> However, there'd still be some advantage in not being dependent on CSS
> hackery to make it look nice in HTML.
> 
> What we're down to wanting, at this point, is basically a para with
> hanging indent.
> 
>> What about putting everything into one <table row> and use a block with
>> some left padding/margin for description + example.
>> This would solve the PDF page break issue as well as the column
>> separation border one.
>> The screenshot attached uses a <dl> tag for the descrition/example block.
> 
> That looks about right, perhaps, but could you be a little clearer about
> how you accomplished that?

Attached you will find the HTML structure with associated styles.
Sorry I haven't tried to do this from the DocBook sources.
I hope this helps though.

Regards

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

Tom Lane <tgl@sss.pgh.pa.us> — 2020-04-16T17:03:36Z

Pierre Giraud <pierre.giraud@dalibo.com> writes:
> Le 16/04/2020 à 16:43, Tom Lane a écrit :
>> Pierre Giraud <pierre.giraud@dalibo.com> writes:
>>> The screenshot attached uses a <dl> tag for the descrition/example block.

>> That looks about right, perhaps, but could you be a little clearer about
>> how you accomplished that?

> Attached you will find the HTML structure with associated styles.
> Sorry I haven't tried to do this from the DocBook sources.
> I hope this helps though.

After a bit of poking at it, I couldn't find another way to do that
than using a <variablelist> structure.  Which is an annoying amount
of markup to be adding to each table cell, but I guess we could live
with it.  A bigger problem is that docbook applies styles to the
<dl> structure that, at least by default, add a LOT of vertical space.
Doesn't seem real workable unless we can undo that.

			regards, tom lane

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

Andreas Karlsson <andreas@proxel.se> — 2020-04-16T22:05:33Z

On 4/14/20 4:52 PM, Tom Lane wrote:
> Andreas Karlsson <andreas@proxel.se> writes:
>> That said, I agree with that quite many of our tables right now are
>> ugly, but I prefer ugly to hard to read. For me the mix of having every
>> third row split into two fields makes the tables very hard to read. I
>> have a hard time seeing which rows belong to which function.
> 
> Did you look at the variants without that discussed downthread?

Yeah, I did some of them are quite readable, for example your latest two 
screenshots of table 9.10.

Andreas

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

Alvaro Herrera <alvherre@2ndquadrant.com> — 2020-04-16T23:03:04Z

v1 is good.

I like your v2 even better.  If it becomes possible to remove or soften
the "inter-row" horizontal line with CSS tricks afterwards, that would
be swell, but even without that, I cast my vote to using this table
format.

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

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

Tom Lane <tgl@sss.pgh.pa.us> — 2020-04-17T00:25:09Z

Alvaro Herrera <alvherre@2ndquadrant.com> writes:
> I like your v2 even better.  If it becomes possible to remove or soften
> the "inter-row" horizontal line with CSS tricks afterwards, that would
> be swell, but even without that, I cast my vote to using this table
> format.

I eventually figured out that the approved way to do per-table-entry
customization is to attach "role" properties to the DocBook elements,
and then key off the role names in applying formatting changes in
the customization layer.  So attached is a v3 that handles the desired
formatting changes by applying a hanging indent to table <entry>
contents if the entry is marked with role="functableentry".  It may
well be possible to do this in a cleaner fashion, but this seems
good enough for discussion.

I changed table 9.30 (Date/Time Operators) to this style, doing it
exactly the same way as functions, just to see what it'd look like.
I'm not sure if this is OK or if we want a separate column with
just the operator name at the left --- it seems a little bit hard
to spot the operator you want, but not impossible.  Thoughts?

Attached are screenshots of the same segment of table 9.10 as before
and of the initial portion of 9.30, the patch against HEAD to produce
these, and a hacky patch on the website's main.css to get it to go
along.  Without the last you just get all the subsidiary stuff
left-justified if you build with STYLE=website, which isn't impossibly
unreadable but it's not the desired presentation.

I didn't include any screenshots of the PDF rendering, but it looks
fine.

			regards, tom lane

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

Robert Haas <robertmhaas@gmail.com> — 2020-04-17T18:26:37Z

On Thu, Apr 16, 2020 at 8:25 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:
> Attached are screenshots of the same segment of table 9.10 as before
> and of the initial portion of 9.30, the patch against HEAD to produce
> these, and a hacky patch on the website's main.css to get it to go
> along.  Without the last you just get all the subsidiary stuff
> left-justified if you build with STYLE=website, which isn't impossibly
> unreadable but it's not the desired presentation.

These seem very nice, and way more readable than the version with
which you started the thread.

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

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

Tom Lane <tgl@sss.pgh.pa.us> — 2020-04-17T18:38:15Z

Robert Haas <robertmhaas@gmail.com> writes:
> On Thu, Apr 16, 2020 at 8:25 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:
>> Attached are screenshots of the same segment of table 9.10 as before
>> and of the initial portion of 9.30, the patch against HEAD to produce
>> these, and a hacky patch on the website's main.css to get it to go
>> along.  Without the last you just get all the subsidiary stuff
>> left-justified if you build with STYLE=website, which isn't impossibly
>> unreadable but it's not the desired presentation.

> These seem very nice, and way more readable than the version with
> which you started the thread.

Glad you like 'em ;-).  Do you have an opinion about what to do
with the operator tables --- ie do we need a column with the operator
name at the left?

			regards, tom lane

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

Robert Haas <robertmhaas@gmail.com> — 2020-04-17T19:16:46Z

On Fri, Apr 17, 2020 at 2:38 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:
> Glad you like 'em ;-).  Do you have an opinion about what to do
> with the operator tables --- ie do we need a column with the operator
> name at the left?

Well, if the first row says date + date -> date, then I don't think we
also need another column to say that we're talking about +

Seems redundant.

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

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

Tom Lane <tgl@sss.pgh.pa.us> — 2020-04-17T19:58:04Z

Robert Haas <robertmhaas@gmail.com> writes:
> On Fri, Apr 17, 2020 at 2:38 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:
>> Glad you like 'em ;-).  Do you have an opinion about what to do
>> with the operator tables --- ie do we need a column with the operator
>> name at the left?

> Well, if the first row says date + date -> date, then I don't think we
> also need another column to say that we're talking about +

> Seems redundant.

Well, sure it's redundant, the same way an index is redundant.
Question is whether it makes it easier to find what you're after.

Comparing this to what is in table 9.30 as of HEAD [1], it does
seem like the operator column in the latter is a bit busy/redundant.
Perhaps it'd be less so if we used the morerows trick to have only
one occurrence of each operator name in the first column.  But that
would be a little bit of a pain to maintain, so I'm not sure it's
worth the trouble.

Another advantage of handling functions and operators in exactly
the same format is that we won't need to do something weird for
tables 9.9 and 9.11, which include both.

For the moment I'll press on without including that column; we can
add it later without a huge amount of pain if we decide we want it.

On the other point of dispute about the operator tables: for the
moment I'm leaning towards keeping the text descriptions.  Surveying
the existing tables, the *only* two that lack text descriptions now
are this one and the as-yet-unnumbered table in 9.1 for AND/OR/NOT.
(Actually, that one calls itself a truth table not an operator
definition table, so maybe we should leave it alone.)  While there
is a reasonable argument that 9.1 Comparison Operators' descriptions
are all obvious, it's hard to make that argument for any other tables.
So I think the fact that 9.30 lacked such up to now is an aberration
not a good principle to follow.  Even in 9.30, the fact that, say,
date + integer interprets the integer as so-many-days isn't really
so blindingly obvious that it doesn't need documented.  In another
universe we might've made that count as seconds and had the result
type be timestamp, the way it works for date + interval.

			regards, tom lane

[1] https://www.postgresql.org/docs/devel/functions-datetime.html

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

Robert Haas <robertmhaas@gmail.com> — 2020-04-17T20:14:04Z

On Fri, Apr 17, 2020 at 3:58 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:
> On the other point of dispute about the operator tables: for the
> moment I'm leaning towards keeping the text descriptions.

I mostly suggested nuking them just to try to make the table more
readable. But since you've found another (and better) solution to that
problem, I withdraw that suggestion.

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

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

Tom Lane <tgl@sss.pgh.pa.us> — 2020-04-17T20:22:26Z

Robert Haas <robertmhaas@gmail.com> writes:
> On Fri, Apr 17, 2020 at 3:58 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:
>> On the other point of dispute about the operator tables: for the
>> moment I'm leaning towards keeping the text descriptions.

> I mostly suggested nuking them just to try to make the table more
> readable. But since you've found another (and better) solution to that
> problem, I withdraw that suggestion.

Cool, then we're all on the same page.  I shall press forward.

			regards, tom lane

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

David G. Johnston <david.g.johnston@gmail.com> — 2020-04-17T22:30:33Z

On Fri, Apr 17, 2020 at 11:38 AM Tom Lane <tgl@sss.pgh.pa.us> wrote:

> Robert Haas <robertmhaas@gmail.com> writes:
> > On Thu, Apr 16, 2020 at 8:25 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:
> >> Attached are screenshots of the same segment of table 9.10 as before
> >> and of the initial portion of 9.30, the patch against HEAD to produce
> >> these, and a hacky patch on the website's main.css to get it to go
> >> along.  Without the last you just get all the subsidiary stuff
> >> left-justified if you build with STYLE=website, which isn't impossibly
> >> unreadable but it's not the desired presentation.
>
> > These seem very nice, and way more readable than the version with
> > which you started the thread.
>
>
I too like the layout result.

> Glad you like 'em ;-).  Do you have an opinion about what to do
> with the operator tables --- ie do we need a column with the operator
> name at the left?
>
>
I feel like writing them as:

+ (date, integer) -> date

makes more sense as they are mainly sorted on the operator symbol as
opposed to the left operand.

I think the description line is beneficial, and easy enough to skim over
for the trained eye just looking for a refresher on the example syntax.

David J.

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

Tom Lane <tgl@sss.pgh.pa.us> — 2020-04-17T23:04:51Z

"David G. Johnston" <david.g.johnston@gmail.com> writes:
> I feel like writing them as:
> + (date, integer) -> date
> makes more sense as they are mainly sorted on the operator symbol as
> opposed to the left operand.

Hmm ... we do use that syntax in some fairly-obscure places like
ALTER OPERATOR, but I'm afraid that novice users would just be
completely befuddled.  Maybe the examples would be enough to clarify,
but I'm not convinced.  Especially not for unary operators, where
ALTER OPERATOR would have us write "- (NONE, integer)".

			regards, tom lane

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

David G. Johnston <david.g.johnston@gmail.com> — 2020-04-17T23:08:19Z

On Fri, Apr 17, 2020 at 4:04 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:

> Especially not for unary operators, where
> ALTER OPERATOR would have us write "- (NONE, integer)".
>

I'd drop the parens for unary and just write "- integer"

It is a bit geeky but then again SQL writers are not typically computer
language novices so operators should be comfortable for them and this isn't
that off-the-wall.  But I agree with the concern.

David J.

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

Tom Lane <tgl@sss.pgh.pa.us> — 2020-04-17T23:16:59Z

"David G. Johnston" <david.g.johnston@gmail.com> writes:
> On Fri, Apr 17, 2020 at 4:04 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:
>> Especially not for unary operators, where
>> ALTER OPERATOR would have us write "- (NONE, integer)".

> I'd drop the parens for unary and just write "- integer"

We do have some postfix operators still ... although it looks like
there's only one in core.  In any case, the signature line is *the*
thing that is supposed to specify what the syntax is, so I'm not
too pleased with using an ambiguous notation for it.

			regards, tom lane

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

David G. Johnston <david.g.johnston@gmail.com> — 2020-04-17T23:40:25Z

On Fri, Apr 17, 2020 at 4:17 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:

> "David G. Johnston" <david.g.johnston@gmail.com> writes:
> > On Fri, Apr 17, 2020 at 4:04 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:
> >> Especially not for unary operators, where
> >> ALTER OPERATOR would have us write "- (NONE, integer)".
>
> > I'd drop the parens for unary and just write "- integer"
>
> We do have some postfix operators still ... although it looks like
> there's only one in core.  In any case, the signature line is *the*
> thing that is supposed to specify what the syntax is, so I'm not
> too pleased with using an ambiguous notation for it.
>

Neither:

- (NONE, integer)

nor

! (integer, NONE)

seem bad, and do make very obvious how they are different.

The left margin scanning ability for the symbol (hey, I have an expression
here that uses @>, what does that do?) seems worth the bit of novelty
required.

David J.

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

Tom Lane <tgl@sss.pgh.pa.us> — 2020-04-18T00:27:25Z

"David G. Johnston" <david.g.johnston@gmail.com> writes:
> On Fri, Apr 17, 2020 at 4:17 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:
>> We do have some postfix operators still ... although it looks like
>> there's only one in core.  In any case, the signature line is *the*
>> thing that is supposed to specify what the syntax is, so I'm not
>> too pleased with using an ambiguous notation for it.

> Neither:
> - (NONE, integer)
> nor
> ! (integer, NONE)
> seem bad, and do make very obvious how they are different.

> The left margin scanning ability for the symbol (hey, I have an expression
> here that uses @>, what does that do?) seems worth the bit of novelty
> required.

Meh.  If we're worried about that, personally I'd much rather put
back the separate left-hand column with just the operator name.

We could also experiment with bold-facing the operator names,
as somebody suggested upthread.

			regards, tom lane

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

Robert Haas <robertmhaas@gmail.com> — 2020-04-18T12:27:12Z

On Fri, Apr 17, 2020 at 6:30 PM David G. Johnston
<david.g.johnston@gmail.com> wrote:
> I feel like writing them as:
>
> + (date, integer) -> date
>
> makes more sense as they are mainly sorted on the operator symbol as opposed to the left operand.

I thought about that, too, but I think the way Tom did it is better.
It's much more natural to see it using the syntax with which it will
actually be invoked.

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

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

Tom Lane <tgl@sss.pgh.pa.us> — 2020-04-18T20:36:17Z

Robert Haas <robertmhaas@gmail.com> writes:
> On Fri, Apr 17, 2020 at 6:30 PM David G. Johnston
> <david.g.johnston@gmail.com> wrote:
>> I feel like writing them as:
>> + (date, integer) -> date
>> makes more sense as they are mainly sorted on the operator symbol as opposed to the left operand.

> I thought about that, too, but I think the way Tom did it is better.
> It's much more natural to see it using the syntax with which it will
> actually be invoked.

Just for the record, I experimented with putting back an "operator name"
column, as attached.  I think it could be argued either way whether this
is an improvement or not.

Some notes:

* The column seems annoyingly wide, but the only way to make it narrower
is to narrow or eliminate the column title, which could be confusing.
Also, if there's not a fair amount of whitespace, it looks as if the
initial name is part of the signature, which is *really* confusing,
cf second screenshot.  (I'm not sure why the vertical rule is rendered
so much more weakly in this case, but it is.)

* I also tried it with valign="middle" to center the operator name among
its entries.  This was *not* an improvement, it largely breaks the
ability to see which entries belong to the name.

			regards, tom lane

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

Pavel Stehule <pavel.stehule@gmail.com> — 2020-04-19T03:40:01Z

so 18. 4. 2020 v 22:36 odesílatel Tom Lane <tgl@sss.pgh.pa.us> napsal:

> Robert Haas <robertmhaas@gmail.com> writes:
> > On Fri, Apr 17, 2020 at 6:30 PM David G. Johnston
> > <david.g.johnston@gmail.com> wrote:
> >> I feel like writing them as:
> >> + (date, integer) -> date
> >> makes more sense as they are mainly sorted on the operator symbol as
> opposed to the left operand.
>
> > I thought about that, too, but I think the way Tom did it is better.
> > It's much more natural to see it using the syntax with which it will
> > actually be invoked.
>
> Just for the record, I experimented with putting back an "operator name"
> column, as attached.  I think it could be argued either way whether this
> is an improvement or not.
>
> Some notes:
>
> * The column seems annoyingly wide, but the only way to make it narrower
> is to narrow or eliminate the column title, which could be confusing.
> Also, if there's not a fair amount of whitespace, it looks as if the
> initial name is part of the signature, which is *really* confusing,
> cf second screenshot.  (I'm not sure why the vertical rule is rendered
> so much more weakly in this case, but it is.)
>
> * I also tried it with valign="middle" to center the operator name among
> its entries.  This was *not* an improvement, it largely breaks the
> ability to see which entries belong to the name.
>

first variant looks better, because column with operator is wider.

Maybe it can look better if a content will be places to mid point. In left
upper corner it is less readable.

Regards

Pavel


>                         regards, tom lane
>
>

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

Peter Eisentraut <peter.eisentraut@2ndquadrant.com> — 2020-04-19T10:29:30Z

On 2020-04-13 22:33, Tom Lane wrote:
>> 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.

Yeah, after reading all this, my conclusion is also, probably tables are 
not the right solution.

A variablelist/definition list would be the next thing to try in my mind.

-- 
Peter Eisentraut              http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

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

Peter Eisentraut <peter.eisentraut@2ndquadrant.com> — 2020-04-19T10:36:17Z

On 2020-04-16 08:26, Pierre Giraud wrote:
> The screenshot attached uses a <dl> tag for the descrition/example block.

I like this better, but then you don't really need the table because you 
can just make the whole thing a definition list.

-- 
Peter Eisentraut              http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

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

Peter Eisentraut <peter.eisentraut@2ndquadrant.com> — 2020-04-19T10:46:32Z

On 2020-04-17 02:25, Tom Lane wrote:
> I eventually figured out that the approved way to do per-table-entry
> customization is to attach "role" properties to the DocBook elements,
> and then key off the role names in applying formatting changes in
> the customization layer.  So attached is a v3 that handles the desired
> formatting changes by applying a hanging indent to table <entry>
> contents if the entry is marked with role="functableentry".  It may
> well be possible to do this in a cleaner fashion, but this seems
> good enough for discussion.

This scares me in terms of maintainability of both the toolchain and the 
markup.  Table formatting is already incredibly fragile, and here we 
just keep poking it until it looks a certain way instead of thinking 
about semantic markup.

A good old definition list of the kind

synopsis

     explanation

     example or two

would be much easier to maintain on all fronts.  And we could for 
example link directly to a function, which is currently not really possible.

If we want to draw a box around this and change the spacing, we can do 
that with CSS.

-- 
Peter Eisentraut              http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

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

Tom Lane <tgl@sss.pgh.pa.us> — 2020-04-19T13:23:01Z

Peter Eisentraut <peter.eisentraut@2ndquadrant.com> writes:
> This scares me in terms of maintainability of both the toolchain and the 
> markup.  Table formatting is already incredibly fragile, and here we 
> just keep poking it until it looks a certain way instead of thinking 
> about semantic markup.

That's a fair criticism, but ...

> A good old definition list of the kind
> synopsis
>      explanation
>      example or two
> would be much easier to maintain on all fronts.  And we could for 
> example link directly to a function, which is currently not really possible.
> If we want to draw a box around this and change the spacing, we can do 
> that with CSS.

... "we can fix it with CSS" is just as much reliance on toolchain.

In any case, I reject the idea that we should just drop the table
markup altogether and use inline variablelists.  In most of these
sections there is a very clear separation between the table contents
(with per-function or per-operator details) and the surrounding
commentary, which deals with more general concerns.  That's a useful
separation for both readers and authors, so we need to preserve it
in some form, but the standard rendering of variablelists won't.
(Our existing major use of variablelists, in the GUC chapter, works
around this basically by not having any "surrounding commentary"
... but that solution doesn't work here.)

There is also value in being able to say things like "see Table m.n
for the available operators for type foo".

If somebody's got an idea how to obtain this painfully-agreed-to
visual appearance from more robust markup, I'm all ears.  This
stuff is a bit outside my skill set, so I don't claim to have
found the best possible implementation.

			regards, tom lane

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

Isaac Morland <isaac.morland@gmail.com> — 2020-04-19T16:39:37Z

On Sun, 19 Apr 2020 at 09:23, Tom Lane <tgl@sss.pgh.pa.us> wrote:

> In any case, I reject the idea that we should just drop the table
> markup altogether and use inline variablelists.  In most of these
> sections there is a very clear separation between the table contents
> (with per-function or per-operator details) and the surrounding
> commentary, which deals with more general concerns.  That's a useful
> separation for both readers and authors, so we need to preserve it
> in some form, but the standard rendering of variablelists won't.
> (Our existing major use of variablelists, in the GUC chapter, works
> around this basically by not having any "surrounding commentary"
> ... but that solution doesn't work here.)
>
> There is also value in being able to say things like "see Table m.n
> for the available operators for type foo".
>

The HTML definition list under discussion looks like this:

<dl>
    <dt> term 1 </dt>
    <dd> description 1 </dd>
    <dt> term 2 </dt>
    <dd> description 2a </dd>
    <dd> description 2b </dd>
</dl>

So the enclosing <dl> element has the same role in the overall document as
the <table>, and could be styled to set it apart from the main text and
make it clear that it is a single unit (and at least in principle could be
included in the "table" numbering). In the function/operator listing use
case, there would be one <dd> for the description and a <dd> for each
example. See:

https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dl

If we were only concerned with HTML output then based on the desired
semantics and appearance I would recommend <dl> without hesitation. Because
of the need to produce PDF as well and my lack of knowledge of the Postgres
documentation build process, I can't be so certain but I still suspect <dl>
to be the best approach.

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

Tom Lane <tgl@sss.pgh.pa.us> — 2020-04-19T16:59:52Z

Isaac Morland <isaac.morland@gmail.com> writes:
> If we were only concerned with HTML output then based on the desired
> semantics and appearance I would recommend <dl> without hesitation. Because
> of the need to produce PDF as well and my lack of knowledge of the Postgres
> documentation build process, I can't be so certain but I still suspect <dl>
> to be the best approach.

Yeah ... so a part of this problem is to persuade DocBook to generate
that.

As I mentioned upthread, I did experiment with putting a single-item
<variablelist> in each table cell.  That works out to an annoying amount
of markup overhead, since variablelist is a rather overengineered
construct, but I imagine we could live with it.  The real problem was
the amount of whitespace it wanted to add.  We could probably hack our
way out of that with CSS for HTML output, but it was quite unclear whether
the PDF toolchain could be made to render it reasonably.

A desirable solution, perhaps, would be a <variablelist> corresponding to
the entire table with rendering customization that produces table-like
dividing lines around <varlistentry>s.  I'm not volunteering to figure
out how to do that though, especially not for PDF.

In the meantime I plan to push forward with the markup approach we've
got.  The editorial content should still work if we find a better
markup answer, and I'm willing to do the work of replacing the markup
as long as somebody else figures out what it should be.

			regards, tom lane

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

Victor Yegorov <vyegorov@gmail.com> — 2020-04-20T10:38:46Z

вс, 19 апр. 2020 г. в 20:00, Tom Lane <tgl@sss.pgh.pa.us>:

> In the meantime I plan to push forward with the markup approach we've
> got.  The editorial content should still work if we find a better
> markup answer, and I'm willing to do the work of replacing the markup
> as long as somebody else figures out what it should be.
>

I am following this thread as a frequent documentation user.

While table 9.5 with functions looks quite nice, I quite dislike 9.4 with
operators.
Previously, I could lookup operator in the leftmost column and read on.
Right now I have to look through the whole table (well, not really, but
still) to find the operator.

-- 
Victor Yegorov

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

Tom Lane <tgl@sss.pgh.pa.us> — 2020-04-20T14:21:14Z

Victor Yegorov <vyegorov@gmail.com> writes:
> While table 9.5 with functions looks quite nice, I quite dislike 9.4 with
> operators.
> Previously, I could lookup operator in the leftmost column and read on.
> Right now I have to look through the whole table (well, not really, but
> still) to find the operator.

Aside from the alternatives already discussed, the only other idea
that's come to my mind is to write operator entries in a style like

	|| as in: text || text → text
		Concatenates the two strings.
		'Post' || 'greSQL' → PostgreSQL

Not sure that that's any better, but it is another alternative.

			regards, tom lane

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

Tom Lane <tgl@sss.pgh.pa.us> — 2020-04-20T16:49:20Z

Victor Yegorov <vyegorov@gmail.com> writes:
> While table 9.5 with functions looks quite nice, I quite dislike 9.4 with
> operators.

BTW, I think a big part of the problem with table 9.4 as it's being
rendered in the web style right now is that the type placeholders
(numeric_type etc) are being rendered in a ridiculously overemphasized
fashion, causing them to overwhelm all else.  Do we really want
<replaceable> to be rendered that way?  I'd think plain italic,
comparable to the rendering of <parameter>, would be more appropriate.

I could make this page use <parameter> for that purpose of course,
but it seems like semantically the wrong thing.

			regards, tom lane

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

Alvaro Herrera <alvherre@2ndquadrant.com> — 2020-04-20T21:31:41Z

On 2020-Apr-20, Tom Lane wrote:

> Victor Yegorov <vyegorov@gmail.com> writes:
> > While table 9.5 with functions looks quite nice, I quite dislike 9.4 with
> > operators.
> > Previously, I could lookup operator in the leftmost column and read on.
> > Right now I have to look through the whole table (well, not really, but
> > still) to find the operator.
> 
> Aside from the alternatives already discussed,

There's one with a separate column for the operator, without types, at
the left (the "with names" example at
https://postgr.es/m/14380.1587242177@sss.pgh.pa.us ).  That seemed
pretty promising -- not sure why it was discarded.

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

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

Tom Lane <tgl@sss.pgh.pa.us> — 2020-04-20T21:50:19Z

Alvaro Herrera <alvherre@2ndquadrant.com> writes:
> There's one with a separate column for the operator, without types, at
> the left (the "with names" example at
> https://postgr.es/m/14380.1587242177@sss.pgh.pa.us ).  That seemed
> pretty promising -- not sure why it was discarded.

Well, I wouldn't say it was discarded --- but there sure wasn't
a groundswell of support.

Looking at it again, I'd be inclined not to bother with the
morerows trick but just to have an operator name entry in each row.
This table is a bit of an outlier anyway, I'm finding --- very few
of the operator tables have multiple entries per operator name.

			regards, tom lane

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

Alvaro Herrera <alvherre@2ndquadrant.com> — 2020-04-20T22:14:33Z

On 2020-Apr-20, Tom Lane wrote:

> Alvaro Herrera <alvherre@2ndquadrant.com> writes:
> > There's one with a separate column for the operator, without types, at
> > the left (the "with names" example at
> > https://postgr.es/m/14380.1587242177@sss.pgh.pa.us ).  That seemed
> > pretty promising -- not sure why it was discarded.
> 
> Well, I wouldn't say it was discarded --- but there sure wasn't
> a groundswell of support.

Ah.

> Looking at it again, I'd be inclined not to bother with the
> morerows trick but just to have an operator name entry in each row.
> This table is a bit of an outlier anyway, I'm finding --- very few
> of the operator tables have multiple entries per operator name.

No disagreement here.  'morerows' attribs are always a messy business.

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

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

Peter Eisentraut <peter.eisentraut@2ndquadrant.com> — 2020-04-23T10:02:55Z

On 2020-04-19 15:23, Tom Lane wrote:
> If somebody's got an idea how to obtain this painfully-agreed-to
> visual appearance from more robust markup, I'm all ears.  This
> stuff is a bit outside my skill set, so I don't claim to have
> found the best possible implementation.

I've played with this a bit, and there are certainly a lot of 
interesting things that you can do with CSS nowadays that would preserve 
some semblance of semantic markup on both the DocBook side and the HTML 
side.  We haven't even considered what this new markup would do to 
non-visual consumers.

But my conclusion is that this new direction is bad and the old way was 
much better.  My vote is to keep what we had in PG12.

-- 
Peter Eisentraut              http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

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

Tom Lane <tgl@sss.pgh.pa.us> — 2020-04-23T16:04:01Z

Peter Eisentraut <peter.eisentraut@2ndquadrant.com> writes:
> I've played with this a bit, and there are certainly a lot of 
> interesting things that you can do with CSS nowadays that would preserve 
> some semblance of semantic markup on both the DocBook side and the HTML 
> side.

As I said, I'm happy to do the legwork of improving the markup if someone
will point me in the right direction.  But I know next to zip about CSS,
so it would not be productive for me to do the basic design there ---
it would take too long and there would probably still be lots to criticize
in whatever I came up with.

(I note ruefully that my original design in e894c6183 *was* pretty decent
semantic markup, especially if you're willing to accept spanspec
identifiers as semantic annotation.  But people didn't like the visual
result, so now we have better visuals and uglier markup.)

> But my conclusion is that this new direction is bad and the old way was 
> much better.  My vote is to keep what we had in PG12.

I'm not willing to accept that conclusion.  Why are we even bothering
to support PDF output, if lots of critical information is going to be
illegible?  (And even if you figure PDFs should go the way of the dodo,
almost any narrow-window presentation has got problems with these tables.)
Also, as I've been going through this, I've realized that there are many
places in chapter 9 where the documentation is well south of adequate, if
not flat-out wrong.  Some of it is just that nobody's gone through this
material in decades, and some of it is that the existing table layout is
so unfriendly to writing more than a couple words of explanation per item.
But I'm not willing to abandon the work I've done so far and just hope
that in another twenty years somebody will be brave or foolish enough to
try again.

			regards, tom lane

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

Bruce Momjian <bruce@momjian.us> — 2020-04-23T16:23:02Z

On Thu, Apr 23, 2020 at 12:04:01PM -0400, Tom Lane wrote:
> Peter Eisentraut <peter.eisentraut@2ndquadrant.com> writes:
> > I've played with this a bit, and there are certainly a lot of 
> > interesting things that you can do with CSS nowadays that would preserve 
> > some semblance of semantic markup on both the DocBook side and the HTML 
> > side.
> 
> As I said, I'm happy to do the legwork of improving the markup if someone
> will point me in the right direction.  But I know next to zip about CSS,
> so it would not be productive for me to do the basic design there ---
> it would take too long and there would probably still be lots to criticize
> in whatever I came up with.

I can do the CSS if you tell me what you want.

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EnterpriseDB                             https://enterprisedb.com

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +

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

Tom Lane <tgl@sss.pgh.pa.us> — 2020-04-23T16:43:27Z

Bruce Momjian <bruce@momjian.us> writes:
> On Thu, Apr 23, 2020 at 12:04:01PM -0400, Tom Lane wrote:
>> As I said, I'm happy to do the legwork of improving the markup if someone
>> will point me in the right direction.  But I know next to zip about CSS,
>> so it would not be productive for me to do the basic design there ---
>> it would take too long and there would probably still be lots to criticize
>> in whatever I came up with.

> I can do the CSS if you tell me what you want.

I think the existing visual appearance is more or less agreed to, so
what we want is to reproduce that as closely as possible from some
saner markup.  The first problem is to agree on what "saner markup"
is exactly.

We could possibly use margin and vertical-space CSS adjustments starting
from just using several <para>s within each table cell (one <para> for
signature, one for description, one for each example).  I'm not sure
whether that meets Peter's desire for "semantic" markup though.  It's not
any worse than the old way with otherwise-unlabeled <entry>s, but it's not
better either.  Do we want, say, to distinguish descriptions from examples
in the markup?  If so, will paras with a role attribute do, or does it
need to be something else?

I'm also not sure whether or not Peter is objecting to the way I used
<returnvalue>.  That seems reasonably semantically-based to me, but since
he hasn't stated what his criteria are, I don't know if he thinks so.
(I'll admit that it's a bit of an abuse to use that for both function
return types and example results.)  If that's out then we need some other
design for getting the right arrows into place.

			regards, tom lane

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

Alvaro Herrera <alvherre@2ndquadrant.com> — 2020-04-23T17:43:43Z

If we're doing nicer markup+CSS for this, then it might make sense to
find a better solution for this kind of entry with multiple signatures
(which was already an issue in the previous version):

text || anynonarray or anynonarray || text → text
	Converts the non-string input to text, then concatenates the two
	strings. (The non-string input cannot be of an array type, because that
	would create ambiguity with the array || operators. If you want to
	concatenate an array's text equivalent, cast it to text explicitly.)
	'Value: ' || 42 → Value: 42

I think it would make sense to split the first line to put each of the
two signatures on their own line.  So it would look like this:

text || anynonarray
anynonarray || text → text
	Converts the non-string input to text, then concatenates the two
	strings. (The non-string input cannot be of an array type, because that
	would create ambiguity with the array || operators. If you want to
	concatenate an array's text equivalent, cast it to text explicitly.)
	'Value: ' || 42 → Value: 42


Another example:

to_ascii ( string text [, encoding name or integer ] ) → text

should be (I think):

to_ascii ( string text [, encoding name ] ) → text
to_ascii ( string text [, integer ] ) → text


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

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

Tom Lane <tgl@sss.pgh.pa.us> — 2020-04-23T18:10:07Z

Alvaro Herrera <alvherre@2ndquadrant.com> writes:
> If we're doing nicer markup+CSS for this, then it might make sense to
> find a better solution for this kind of entry with multiple signatures
> (which was already an issue in the previous version):

Yeah, agreed.  I would like to be able to have multiple signature blocks
in one table cell, which the current hack can't handle.  There aren't
quite enough cases to make this mandatory, but it would be nicer.

It seems do-able if we explicitly mark signature blocks with their
own role, say

       <entry role="functableentry">
        <para role="funcsignature">
         text || anynonarray → text
        </para>
        <para role="funcsignature">
         anynonarray || text → text
        </para>
        <para>
          description ...

Then the CSS can key off of the role to decide what indentation to apply
to the para.  While I mostly see how that would work, I'm not very sure
about whether we can make it work in the PDF chain too.

Not sure whether it'd be worth inventing additional roles to apply to
description and example paras, or whether that's just inducing carpal
tunnel syndrome to no purpose.  We'd want to keep the role label on the
<entry>s anyway I think, and that context should be enough as long as
we don't need different formatting for descriptions and examples.
But maybe Peter's notion of "semantic markup" requires it anyway.

			regards, tom lane

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

Tom Lane <tgl@sss.pgh.pa.us> — 2020-04-26T17:40:54Z

I wrote:
> Alvaro Herrera <alvherre@2ndquadrant.com> writes:
>> If we're doing nicer markup+CSS for this, then it might make sense to
>> find a better solution for this kind of entry with multiple signatures
>> (which was already an issue in the previous version):

> Yeah, agreed.  I would like to be able to have multiple signature blocks
> in one table cell, which the current hack can't handle.  There aren't
> quite enough cases to make this mandatory, but it would be nicer.
> It seems do-able if we explicitly mark signature blocks with their
> own role, say ...

Hearing no comments, I went ahead and experimented with that.
Attached is a POC patch that changes just the header and first few
entries in table 9.9, just to see what it'd look like.  This does
nicely reproduce the existing visual appearance.  (With the margin
parameters I used, there is a teensy bit more vertical space, but
I think it looks better this way.  That could be adjusted either
way of course.)

There is a small problem with getting this to work in the webstyle
HTML: somebody decided it would be a great idea to have a global
override on paragraph margin-bottom settings.  For the purposes of
this test I just deleted that from main.css, but I suppose we want
some more-nuanced solution in reality.

<digression>

One thing I couldn't help noticing while fooling with this is what
seems to be a bug in the PDF toolchain: any place you try to put
an <indexterm>, you get extra whitespace.  Not a lot, but once you
see it, you can't un-see it.  It's particularly obvious if one of
two adjacent lines has the extra indentation and the other doesn't.
In the attached, I added an <indexterm> to one of the signature
entries for "text || anynonarray", and you can see what I'm unhappy
about in the PDF screenshot.  The problem already exists in our
previous markup, at least in places where people put indexterms
inside function-table entries, but it'll be more obvious anyplace
we choose to have two signature entries in one table cell.

I tried putting the <indexterm>s outside the <para> elements, but
that makes it worse not better: instead of a little bit of extra
horizontal whitespace, you get a lot of extra vertical whitespace.

The only "fix" I've found is to place the <indexterm> at the end
of the signature <para> instead of the beginning.  That's not included
in the attached but it does hide the existence of the extra space
quite effectively.  I'm not sure though whether it might result in
odd behavior of cross-reference links to the function entry.
In any case it feels like a hack.

</digression>

It seems to me that this way is better than the markup I've been
using --- one thing I've observed is that Emacs' sgml mode is a
bit confused by the <?br?> hacks, and it's happier with this.
But it's not clear to me whether this is sufficient to resolve
Peter's unhappiness.

			regards, tom lane

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

Jonathan S. Katz <jkatz@postgresql.org> — 2020-04-26T19:21:38Z

On 4/26/20 1:40 PM, Tom Lane wrote:
> I wrote:
>> Alvaro Herrera <alvherre@2ndquadrant.com> writes:

> There is a small problem with getting this to work in the webstyle
> HTML: somebody decided it would be a great idea to have a global
> override on paragraph margin-bottom settings.  For the purposes of
> this test I just deleted that from main.css, but I suppose we want
> some more-nuanced solution in reality.

I have to see why that is. I traced it back to the original "bring doc
styles up to modern website" patch (66798351) and there is missing
context. Anyway, I'd like to test it before a wholesale removal (there
is often a strong correlation between "!important" and "hack", so I'll
want to further dive into it).

I'll have some time to play around with the CSS tonight.

Jonathan

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

Jonathan S. Katz <jkatz@postgresql.org> — 2020-04-27T01:23:54Z

On 4/26/20 3:21 PM, Jonathan S. Katz wrote:
> On 4/26/20 1:40 PM, Tom Lane wrote:
>> I wrote:
>>> Alvaro Herrera <alvherre@2ndquadrant.com> writes:
> 
>> There is a small problem with getting this to work in the webstyle
>> HTML: somebody decided it would be a great idea to have a global
>> override on paragraph margin-bottom settings.  For the purposes of
>> this test I just deleted that from main.css, but I suppose we want
>> some more-nuanced solution in reality.
> 
> I have to see why that is. I traced it back to the original "bring doc
> styles up to modern website" patch (66798351) and there is missing
> context. Anyway, I'd like to test it before a wholesale removal (there
> is often a strong correlation between "!important" and "hack", so I'll
> want to further dive into it).
> 
> I'll have some time to play around with the CSS tonight.

Can you try

 #docContent p {
-  margin-bottom: 1rem !important;
+  margin-bottom: 1rem;
 }

and see how it looks?

Jonathan

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

Tom Lane <tgl@sss.pgh.pa.us> — 2020-04-27T01:44:02Z

"Jonathan S. Katz" <jkatz@postgresql.org> writes:
> Can you try

>  #docContent p {
> -  margin-bottom: 1rem !important;
> +  margin-bottom: 1rem;
>  }

> and see how it looks?

In some desultory looking around, I couldn't find anyplace in the
existing text that that changes at all.  And it does make the
revised table markup render the way I want ... so +1.

			regards, tom lane

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

Jonathan S. Katz <jkatz@postgresql.org> — 2020-04-27T12:34:20Z

On 4/26/20 9:44 PM, Tom Lane wrote:
> "Jonathan S. Katz" <jkatz@postgresql.org> writes:
>> Can you try
> 
>>  #docContent p {
>> -  margin-bottom: 1rem !important;
>> +  margin-bottom: 1rem;
>>  }
> 
>> and see how it looks?
> 
> In some desultory looking around, I couldn't find anyplace in the
> existing text that that changes at all.  And it does make the
> revised table markup render the way I want ... so +1.

Great. I do want to do a bit more desultory testing in the older
versions of the docs, but it can be committed whenever the -docs side is
ready.

Thanks,

Jonathan

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

Tom Lane <tgl@sss.pgh.pa.us> — 2020-04-27T12:49:41Z

"Jonathan S. Katz" <jkatz@postgresql.org> writes:
> Great. I do want to do a bit more desultory testing in the older
> versions of the docs, but it can be committed whenever the -docs side is
> ready.

Other than that point, the main.css patch as I presented it just adds
some rules that aren't used yet, so it could be pushed as soon as you're
satisfied about the !important change.  It'd probably make sense to
push it in advance of making the markup changes, so we don't have an
interval of near-unreadable devel docs.

Still waiting to hear whether this markup approach satisfies
Peter's concerns, though.

			regards, tom lane

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

Jonathan S. Katz <jkatz@postgresql.org> — 2020-04-27T13:17:23Z

On 4/27/20 8:49 AM, Tom Lane wrote:
> "Jonathan S. Katz" <jkatz@postgresql.org> writes:
>> Great. I do want to do a bit more desultory testing in the older
>> versions of the docs, but it can be committed whenever the -docs side is
>> ready.
> 
> Other than that point, the main.css patch as I presented it just adds
> some rules that aren't used yet, so it could be pushed as soon as you're
> satisfied about the !important change.  It'd probably make sense to
> push it in advance of making the markup changes, so we don't have an
> interval of near-unreadable devel docs.

*nods* I'll ensure to test again and hopefully commit later today.

I forget what I was looking at, but I did see a similar pattern in some
other modern software docs, so it seems like this is trending in the
right direction. Looking forward to the rollout!

Jonathan

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

Tom Lane <tgl@sss.pgh.pa.us> — 2020-04-28T15:19:30Z

"Jonathan S. Katz" <jkatz@postgresql.org> writes:
> On 4/27/20 8:49 AM, Tom Lane wrote:
>> Other than that point, the main.css patch as I presented it just adds
>> some rules that aren't used yet, so it could be pushed as soon as you're
>> satisfied about the !important change.  It'd probably make sense to
>> push it in advance of making the markup changes, so we don't have an
>> interval of near-unreadable devel docs.

> *nods* I'll ensure to test again and hopefully commit later today.

After looking at the JSON function tables, I've concluded that the
ability to have more than one function signature per table cell is
really rather essential not optional.  So I'm going to go ahead and
convert all the existing markup to the <para>-based style I proposed
on Sunday.  Please push the main.css change when you can.

			regards, tom lane

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

Tom Lane <tgl@sss.pgh.pa.us> — 2020-04-28T20:34:36Z

I wrote:
> One thing I couldn't help noticing while fooling with this is what
> seems to be a bug in the PDF toolchain: any place you try to put
> an <indexterm>, you get extra whitespace.  Not a lot, but once you
> see it, you can't un-see it.  It's particularly obvious if one of
> two adjacent lines has the extra indentation and the other doesn't.
> ...
> The only "fix" I've found is to place the <indexterm> at the end
> of the signature <para> instead of the beginning.

I spent some more time experimenting with this today, and determined
that there's no way to fix it by messing with FO layout attributes.
The basic problem seems to be that if you write

       <entry role="func_table_entry"><para role="func_signature">
        <indexterm>
         <primary>ceiling</primary>
        </indexterm>
        <function>ceiling</function> ( <type>numeric</type> )

then what you get in the .fo file is

        <fo:table-cell padding-start="2pt" padding-end="2pt" padding-top="2pt" padding-bottom="2pt" border-bottom-width="0.5pt" border-bottom-style="solid" border-bottom-color="black"><fo:block><fo:block margin-left="4em" text-align="left" text-indent="-3.5em">
        <fo:wrapper id="id-1.5.8.9.6.2.2.4.1.1.1"><!--ceiling--></fo:wrapper>
        <fo:inline font-family="monospace">ceiling</fo:inline> ( <fo:inline font-family="monospace">numeric</fo:inline> )

where the <fo:wrapper> apparently is used as a cross-reference anchor.
The trouble with this is that the rules for collapsing adjacent whitespace
don't work across the <fo:wrapper>, so no matter what you do you will end
up with two spaces not one before the visible text "ceiling".  The only
way to hide the effects of that with layout attributes is to set
whitespace to be ignored altogether within the block, which is quite
undesirable.

The fix I'm currently considering is to eliminate the extra whitespace
run(s) by formatting <indexterm>s within tables this way:

      <row>
       <entry role="func_table_entry"><para role="func_signature"><indexterm>
         <primary>char_length</primary>
        </indexterm><indexterm>
         <primary>character string</primary>
         <secondary>length</secondary>
        </indexterm><indexterm>
         <primary>length</primary>
         <secondary sortas="character string">of a character string</secondary>
         <see>character string, length</see>
        </indexterm>
        <function>char_length</function> ( <type>text</type> )
        <returnvalue>integer</returnvalue>
       </para>

Perhaps it's only worth being anal about this in table cells with multiple
function signatures and/or multiple <indexterm>s; in other places the
whitespace variation just isn't that noticeable.  On the other hand,
there's something to be said for having uniform layout of the XML source,
which'd suggest having a uniform rule "no whitespace before an <indexterm>
within a table cell".

Or we could put the <indexterm>s at the end.  Or just ignore it, reasoning
that the PDF output is never going to look all that great anyway.

Thoughts?

			regards, tom lane

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

Tom Lane <tgl@sss.pgh.pa.us> — 2020-04-29T23:29:43Z

After further fooling with this issue, I've determined that

(1) I need to be able to use <programlisting> environments within the
func_table_entry cells and have them render more-or-less normally.
There doesn't seem to be any other good way to render multiline
example results for set-returning functions ... but marking such
environments up to the extent that the website style normally does
is very distracting.

(2) I found that adding !important to the func_table_entry rules
is enough to override less-general !important rules.  So it'd be
possible to leave all the existing CSS rules alone, if that makes
you feel more comfortable.

The attached updated patch reflects both of these conclusions.
We could take out some of the !important annotations here if
you're willing to delete !important annotations in more-global
rules for <p> and/or <pre>, but maybe that's something to fool
with later.  I'd like to get this done sooner ...

			regards, tom lane

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

Jonathan S. Katz <jkatz@postgresql.org> — 2020-04-29T23:40:25Z

On 4/29/20 7:29 PM, Tom Lane wrote:
> After further fooling with this issue, I've determined that
> 
> (1) I need to be able to use <programlisting> environments within the
> func_table_entry cells and have them render more-or-less normally.
> There doesn't seem to be any other good way to render multiline
> example results for set-returning functions ... but marking such
> environments up to the extent that the website style normally does
> is very distracting.
> 
> (2) I found that adding !important to the func_table_entry rules
> is enough to override less-general !important rules.  So it'd be
> possible to leave all the existing CSS rules alone, if that makes
> you feel more comfortable.
> 
> The attached updated patch reflects both of these conclusions.
> We could take out some of the !important annotations here if
> you're willing to delete !important annotations in more-global
> rules for <p> and/or <pre>, but maybe that's something to fool
> with later.  I'd like to get this done sooner ...

My preference would be to figure out the CSS rules that are causing you
to rely on !important at the table level and just fix that up, rather
than hacking in too many !important.

I'll compromise on the temporary importants, but first I want to see
what's causing the need for it. Do you have a suggestion on a page to test?

Jonathan

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

Jonathan S. Katz <jkatz@postgresql.org> — 2020-04-29T23:55:16Z

On 4/29/20 7:40 PM, Jonathan S. Katz wrote:
> On 4/29/20 7:29 PM, Tom Lane wrote:
>> After further fooling with this issue, I've determined that
>>
>> (1) I need to be able to use <programlisting> environments within the
>> func_table_entry cells and have them render more-or-less normally.
>> There doesn't seem to be any other good way to render multiline
>> example results for set-returning functions ... but marking such
>> environments up to the extent that the website style normally does
>> is very distracting.
>>
>> (2) I found that adding !important to the func_table_entry rules
>> is enough to override less-general !important rules.  So it'd be
>> possible to leave all the existing CSS rules alone, if that makes
>> you feel more comfortable.
>>
>> The attached updated patch reflects both of these conclusions.
>> We could take out some of the !important annotations here if
>> you're willing to delete !important annotations in more-global
>> rules for <p> and/or <pre>, but maybe that's something to fool
>> with later.  I'd like to get this done sooner ...
> 
> My preference would be to figure out the CSS rules that are causing you
> to rely on !important at the table level and just fix that up, rather
> than hacking in too many !important.
> 
> I'll compromise on the temporary importants, but first I want to see
> what's causing the need for it. Do you have a suggestion on a page to test?

From real quick I got it to here. With the latest copy of the doc builds
it appears to still work as expected, but I need a section with the new
"pre" block to test.

I think the "background-color: inherit !important" is a bit odd, and
would like to trace that one down a bit more, but I did not see anything
obvious on my glance through it.

How does it look on your end?

Jonathan

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

Tom Lane <tgl@sss.pgh.pa.us> — 2020-04-30T00:15:27Z

"Jonathan S. Katz" <jkatz@postgresql.org> writes:
> On 4/29/20 7:40 PM, Jonathan S. Katz wrote:
>> I'll compromise on the temporary importants, but first I want to see
>> what's causing the need for it. Do you have a suggestion on a page to test?

I haven't yet pushed anything dependent on the new markup, but
attached is a draft revision for the JSON section; if you look at
the SRFs such as json_array_elements you'll see the issue.

> From real quick I got it to here. With the latest copy of the doc builds
> it appears to still work as expected, but I need a section with the new
> "pre" block to test.

Yeah, I see you found the same <p> and <pre> settings I did.

> I think the "background-color: inherit !important" is a bit odd, and
> would like to trace that one down a bit more, but I did not see anything
> obvious on my glance through it.

I think it's coming from this bit at about main.css:660:

pre,
code,
#docContent kbd,
#docContent tt.LITERAL,
#docContent tt.REPLACEABLE {
  font-size: 0.9rem !important;
  color: inherit !important;
  background-color: #f8f9fa !important;
  border-radius: .25rem;
  margin: .6rem 0;
  font-weight: 300;
}

I had to override most of that.

			regards, tom lane

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

Jonathan S. Katz <jkatz@postgresql.org> — 2020-04-30T01:22:36Z

On 4/29/20 8:15 PM, Tom Lane wrote:
> "Jonathan S. Katz" <jkatz@postgresql.org> writes:
>> On 4/29/20 7:40 PM, Jonathan S. Katz wrote:
>>> I'll compromise on the temporary importants, but first I want to see
>>> what's causing the need for it. Do you have a suggestion on a page to test?
> 
> I haven't yet pushed anything dependent on the new markup, but
> attached is a draft revision for the JSON section; if you look at
> the SRFs such as json_array_elements you'll see the issue.
> 
>> From real quick I got it to here. With the latest copy of the doc builds
>> it appears to still work as expected, but I need a section with the new
>> "pre" block to test.
> 
> Yeah, I see you found the same <p> and <pre> settings I did.
> 
>> I think the "background-color: inherit !important" is a bit odd, and
>> would like to trace that one down a bit more, but I did not see anything
>> obvious on my glance through it.
> 
> I think it's coming from this bit at about main.css:660:
> 
> pre,
> code,
> #docContent kbd,
> #docContent tt.LITERAL,
> #docContent tt.REPLACEABLE {
>   font-size: 0.9rem !important;
>   color: inherit !important;
>   background-color: #f8f9fa !important;
>   border-radius: .25rem;
>   margin: .6rem 0;
>   font-weight: 300;
> }
> 
> I had to override most of that.

Yeah, I had started toying with that and saw no differences, but I would
need to test against anything in particular. I'm pretty confident we can
remove those importants, based on my desultory testing.

I'll try and get the patch built + docs loaded, and see if we can safely
remove those.

Jonathan

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

Jonathan S. Katz <jkatz@postgresql.org> — 2020-04-30T02:04:39Z

On 4/29/20 9:22 PM, Jonathan S. Katz wrote:
> On 4/29/20 8:15 PM, Tom Lane wrote:
>> "Jonathan S. Katz" <jkatz@postgresql.org> writes:
>>> On 4/29/20 7:40 PM, Jonathan S. Katz wrote:
>>>> I'll compromise on the temporary importants, but first I want to see
>>>> what's causing the need for it. Do you have a suggestion on a page to test?
>>
>> I haven't yet pushed anything dependent on the new markup, but
>> attached is a draft revision for the JSON section; if you look at
>> the SRFs such as json_array_elements you'll see the issue.

^ This was super helpful. Built locally, and made it really easy to
test. Thanks!

>>> From real quick I got it to here. With the latest copy of the doc builds
>>> it appears to still work as expected, but I need a section with the new
>>> "pre" block to test.
>>
>> Yeah, I see you found the same <p> and <pre> settings I did.
>>
>>> I think the "background-color: inherit !important" is a bit odd, and
>>> would like to trace that one down a bit more, but I did not see anything
>>> obvious on my glance through it.
>>
>> I think it's coming from this bit at about main.css:660:
>>
>> pre,
>> code,
>> #docContent kbd,
>> #docContent tt.LITERAL,
>> #docContent tt.REPLACEABLE {
>>   font-size: 0.9rem !important;
>>   color: inherit !important;
>>   background-color: #f8f9fa !important;
>>   border-radius: .25rem;
>>   margin: .6rem 0;
>>   font-weight: 300;
>> }
>>
>> I had to override most of that.
> 
> Yeah, I had started toying with that and saw no differences, but I would
> need to test against anything in particular. I'm pretty confident we can
> remove those importants, based on my desultory testing.
> 
> I'll try and get the patch built + docs loaded, and see if we can safely
> remove those.

Please see latest attached. I've eliminated the !important, condensed
the CSS, and the desultory (yes, my word of the week) testing did not
find issues in devel or earlier versions.

Please let me know if this works for you. If it does, I'll push it up to
pgweb.

Jonathan

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

Tom Lane <tgl@sss.pgh.pa.us> — 2020-04-30T02:38:19Z

"Jonathan S. Katz" <jkatz@postgresql.org> writes:
> Please see latest attached. I've eliminated the !important, condensed
> the CSS, and the desultory (yes, my word of the week) testing did not
> find issues in devel or earlier versions.

> Please let me know if this works for you. If it does, I'll push it up to
> pgweb.

NAK ... that does *not* work for me.

It looks to me like you are expecting that "margin" with four parameters
will override an outer-level setting of margin-bottom, but that is not
how my browser is responding.  ISTM you need to explicitly set the very
same parameters in the more-specific rule as in the less-specific rule
that you want to override.

I get reasonable results with these settings, but not with
anything more abbreviated:

#docContent table.table th.func_table_entry p,
#docContent table.table td.func_table_entry p {
  margin-top: 0.1em;
  margin-bottom: 0.1em;
  padding-left: 4em;
  text-align: left;
}

#docContent table.table p.func_signature {
  text-indent: -3.5em;
}

#docContent table.table td.func_table_entry pre.programlisting {
  background-color: inherit;
  border: 0;
  margin-top: 0.1em;
  margin-bottom: 0.1em;
  padding: 0;
  padding-left: 4em;
}

In particular, it might look like the multiple padding settings
in the pre.programlisting rule are redundant ... but they are not, at
least not with Safari.

			regards, tom lane

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

Jonathan S. Katz <jkatz@postgresql.org> — 2020-04-30T02:45:16Z

On 4/29/20 10:38 PM, Tom Lane wrote:
> "Jonathan S. Katz" <jkatz@postgresql.org> writes:
>> Please see latest attached. I've eliminated the !important, condensed
>> the CSS, and the desultory (yes, my word of the week) testing did not
>> find issues in devel or earlier versions.
> 
>> Please let me know if this works for you. If it does, I'll push it up to
>> pgweb.
> 
> NAK ... that does *not* work for me.

Learned a new acronym...

> It looks to me like you are expecting that "margin" with four parameters
> will override an outer-level setting of margin-bottom, but that is not
> how my browser is responding.  ISTM you need to explicitly set the very
> same parameters in the more-specific rule as in the less-specific rule
> that you want to override.
> 
> I get reasonable results with these settings, but not with
> anything more abbreviated:

> In particular, it might look like the multiple padding settings
> in the pre.programlisting rule are redundant ... but they are not, at
> least not with Safari.

Clearly I was caught doing a single browser test (Chrome).

Reverted back to the verbose way sans !important, attached, which
appears to be the consensus. If you can ACK this, I'll commit.

Thanks,

Jonathan

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

Tom Lane <tgl@sss.pgh.pa.us> — 2020-04-30T03:26:20Z

"Jonathan S. Katz" <jkatz@postgresql.org> writes:
> Clearly I was caught doing a single browser test (Chrome).

Well, I've not tested anything but Safari, either ...

> Reverted back to the verbose way sans !important, attached, which
> appears to be the consensus. If you can ACK this, I'll commit.

This one works for me.

			regards, tom lane

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

Jonathan S. Katz <jkatz@postgresql.org> — 2020-04-30T04:12:48Z

On 4/29/20 11:26 PM, Tom Lane wrote:
> "Jonathan S. Katz" <jkatz@postgresql.org> writes:
>> Clearly I was caught doing a single browser test (Chrome).
> 
> Well, I've not tested anything but Safari, either ...
> 
>> Reverted back to the verbose way sans !important, attached, which
>> appears to be the consensus. If you can ACK this, I'll commit.
> 
> This one works for me.

Pushed. Thanks!

Jonathan

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

Tom Lane <tgl@sss.pgh.pa.us> — 2020-05-04T21:22:01Z

I've now completed updating chapter 9 for the new layout,
and the results are visible at 
https://www.postgresql.org/docs/devel/functions.html
There is more to do --- for instance, various contrib modules
have function/operator tables that should be synced with this
design.  But this seemed like a good place to pause and reflect.

After working through the whole chapter, the only aspect of the
new markup that really doesn't seem to work so well is the use
of <returnvalue> for function result types and example results.
While I don't think that that's broken in concept, DocBook has
restrictions on the contents of <returnvalue> that are problematic:

* It won't let you put any verbatim-layout environment, such
as <programlisting>, inside <returnvalue>.  This is an issue for
examples for set-returning functions in particular.  I've done
those like this:

       <para>
        <literal>regexp_matches('foobarbequebaz', 'ba.', 'g')</literal>
        <returnvalue></returnvalue>
<programlisting>
 {bar}
 {baz}
</programlisting>
        (2 rows in result)
       </para>

where the empty <returnvalue> environment is just serving to generate a
right arrow.  It looks all right, but it's hardly semantically-based
markup.

* <returnvalue> is also quite sticky about inserting other sorts
of font-changing environments inside it.  As an example, it'll let
you include <replaceable> but not <type>, which seems pretty weird
to me.  This is problematic in some places where it's desirable to
have text rather than just a type name, for example

        <function>stddev</function> ( <replaceable>numeric_type</replaceable> )
        <returnvalue></returnvalue> <type>double precision</type>
        for <type>real</type> or <type>double precision</type>,
        otherwise <type>numeric</type>

Now I could have done this example by spelling out all six varieties of
stddev() separately, and maybe I should've, but it seemed overly bulky
that way.  So again <returnvalue> is just generating the right arrow.

* After experimenting with a few different ways to handle functions with
multiple OUT parameters, I settled on doing it like this:

        <function>pg_partition_tree</function> ( <type>regclass</type> )
        <returnvalue>setof record</returnvalue>
        ( <parameter>relid</parameter> <type>regclass</type>,
        <parameter>parentrelid</parameter> <type>regclass</type>,
        <parameter>isleaf</parameter> <type>boolean</type>,
        <parameter>level</parameter> <type>integer</type> )

This looks nice and I think it's much more intelligible than other
things I tried --- in particular, including the OUT parameters in
the function signature seems to me to be mostly confusing.  But,
once again, it's abusing the concept that <returnvalue> contains
the result type.  Ideally the output-column list would be inside
the <returnvalue> environment, but DocBook won't allow that
because of the <type> tags.

So at this point I'm tempted to abandon <returnvalue> and go back
to using a custom entity to generate the right arrow, so that
the markup would just look like, say,

        <function>stddev</function> ( <replaceable>numeric_type</replaceable> )
        &returns; <type>double precision</type>
        for <type>real</type> or <type>double precision</type>,
        otherwise <type>numeric</type>

Does anyone have a preference on that, or a better alternative?

			regards, tom lane

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

Jonathan S. Katz <jkatz@postgresql.org> — 2020-05-04T21:38:55Z

On 5/4/20 5:22 PM, Tom Lane wrote:
> I've now completed updating chapter 9 for the new layout,
> and the results are visible at 
> https://www.postgresql.org/docs/devel/functions.html
> There is more to do --- for instance, various contrib modules
> have function/operator tables that should be synced with this
> design.  But this seemed like a good place to pause and reflect.

This is already much better. I've skimmed through a few of the pages, I
can say that the aggregates page[1] is WAY easier to read. Yay!

> 
> After working through the whole chapter, the only aspect of the
> new markup that really doesn't seem to work so well is the use
> of <returnvalue> for function result types and example results.
> While I don't think that that's broken in concept, DocBook has
> restrictions on the contents of <returnvalue> that are problematic:
> 
> * It won't let you put any verbatim-layout environment, such
> as <programlisting>, inside <returnvalue>.  This is an issue for
> examples for set-returning functions in particular.  I've done
> those like this:
> 
>        <para>
>         <literal>regexp_matches('foobarbequebaz', 'ba.', 'g')</literal>
>         <returnvalue></returnvalue>
> <programlisting>
>  {bar}
>  {baz}
> </programlisting>
>         (2 rows in result)
>        </para>
> 
> where the empty <returnvalue> environment is just serving to generate a
> right arrow.  It looks all right, but it's hardly semantically-based
> markup.

We could apply some CSS on the pgweb front perhaps to help distinguish
at least the results? For the above example, it would be great to
capture the program listing + "2 rows in result" output and format them
similarly, though it appears the "(2 rows in result)" is in its own block.

Anyway, likely not that hard to apply some CSS and make it appear a bit
more distinguished, if that's the general idea.

> * <returnvalue> is also quite sticky about inserting other sorts
> of font-changing environments inside it.  As an example, it'll let
> you include <replaceable> but not <type>, which seems pretty weird
> to me.  This is problematic in some places where it's desirable to
> have text rather than just a type name, for example
> 
>         <function>stddev</function> ( <replaceable>numeric_type</replaceable> )
>         <returnvalue></returnvalue> <type>double precision</type>
>         for <type>real</type> or <type>double precision</type>,
>         otherwise <type>numeric</type>
> 
> Now I could have done this example by spelling out all six varieties of
> stddev() separately, and maybe I should've, but it seemed overly bulky
> that way.  So again <returnvalue> is just generating the right arrow.
> 
> * After experimenting with a few different ways to handle functions with
> multiple OUT parameters, I settled on doing it like this:
> 
>         <function>pg_partition_tree</function> ( <type>regclass</type> )
>         <returnvalue>setof record</returnvalue>
>         ( <parameter>relid</parameter> <type>regclass</type>,
>         <parameter>parentrelid</parameter> <type>regclass</type>,
>         <parameter>isleaf</parameter> <type>boolean</type>,
>         <parameter>level</parameter> <type>integer</type> )
> 
> This looks nice and I think it's much more intelligible than other
> things I tried --- in particular, including the OUT parameters in
> the function signature seems to me to be mostly confusing.  But,
> once again, it's abusing the concept that <returnvalue> contains
> the result type.  Ideally the output-column list would be inside
> the <returnvalue> environment, but DocBook won't allow that
> because of the <type> tags.

It does look better, but things look a bit smushed together on the pgweb
front. It seems like there's enough structure where one can make some
not-too-zany CSS rules to put a bit more space between elements, but
perhaps wait to hear the decision on the rest of the structural questions.

> So at this point I'm tempted to abandon <returnvalue> and go back
> to using a custom entity to generate the right arrow, so that
> the markup would just look like, say,
> 
>         <function>stddev</function> ( <replaceable>numeric_type</replaceable> )
>         &returns; <type>double precision</type>
>         for <type>real</type> or <type>double precision</type>,
>         otherwise <type>numeric</type>
> 
> Does anyone have a preference on that, or a better alternative?

As long as we can properly style without zany CSS rules, I'm +0 :)

Jonathan

[1] https://www.postgresql.org/docs/devel/functions-aggregate.html

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

Tom Lane <tgl@sss.pgh.pa.us> — 2020-05-04T22:39:30Z

"Jonathan S. Katz" <jkatz@postgresql.org> writes:
> On 5/4/20 5:22 PM, Tom Lane wrote:
>> I've now completed updating chapter 9 for the new layout,
>> and the results are visible at 
>> https://www.postgresql.org/docs/devel/functions.html

> This is already much better. I've skimmed through a few of the pages, I
> can say that the aggregates page[1] is WAY easier to read. Yay!

Thanks!

>> * After experimenting with a few different ways to handle functions with
>> multiple OUT parameters, I settled on doing it like this:
>> <function>pg_partition_tree</function> ( <type>regclass</type> )
>> <returnvalue>setof record</returnvalue>
>> ( <parameter>relid</parameter> <type>regclass</type>,
>> <parameter>parentrelid</parameter> <type>regclass</type>,
>> <parameter>isleaf</parameter> <type>boolean</type>,
>> <parameter>level</parameter> <type>integer</type> )
>> 
>> This looks nice and I think it's much more intelligible than other
>> things I tried --- in particular, including the OUT parameters in
>> the function signature seems to me to be mostly confusing.  But,
>> once again, it's abusing the concept that <returnvalue> contains
>> the result type.  Ideally the output-column list would be inside
>> the <returnvalue> environment, but DocBook won't allow that
>> because of the <type> tags.

> It does look better, but things look a bit smushed together on the pgweb
> front.

Yeah.  There's less smushing of function signatures when building the
docs without STYLE=website, so there's something specific to the
website style.  I think you'd mentioned that we were intentionally
crimping the space and/or font size within tables?  Maybe that could
get un-done now.  I hadn't bothered to worry about such details until
we had a reasonable sample of cases to look at, but now would be a
good time.

Another rendering oddity that I'd not bothered to chase down is
the appearance of <itemizedlist> environments within table cells.
We have a few of those now as a result of migration of material
that had been out-of-line into the table cells; one example is
in json_populate_record, about halfway down this page:

https://www.postgresql.org/docs/devel/functions-json.html

The text of the list items seems to be getting indented to the
same extent as a not-in-a-table <itemizedlist> list does ---
but the bullets aren't indented nearly as much, making for
weird spacing.  (There's a short <itemizedlist> at the top of
the same page that you can compare to.)

The same weird spacing is visible in a non STYLE=website build,
so I think this might be less a CSS issue and more a DocBook
issue.  On the other hand, it looks fine in the PDF build.
So I'm not sure where to look for the cause.

			regards, tom lane

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

Jonathan S. Katz <jkatz@postgresql.org> — 2020-05-05T02:18:03Z

On 5/4/20 6:39 PM, Tom Lane wrote:
> "Jonathan S. Katz" <jkatz@postgresql.org> writes:
>> On 5/4/20 5:22 PM, Tom Lane wrote:

>> It does look better, but things look a bit smushed together on the pgweb
>> front.
> 
> Yeah.  There's less smushing of function signatures when building the
> docs without STYLE=website, so there's something specific to the
> website style.  I think you'd mentioned that we were intentionally
> crimping the space and/or font size within tables?  Maybe that could
> get un-done now.  I hadn't bothered to worry about such details until
> we had a reasonable sample of cases to look at, but now would be a
> good time.

IIRC this was the monospace issue[1], but there are some other things
I'm seeing (e.g. the italics) that may be pushing things closer together
htan not. Now that round 1 of commits are in, I can take a whack at
tightening it up this week.

> Another rendering oddity that I'd not bothered to chase down is
> the appearance of <itemizedlist> environments within table cells.
> We have a few of those now as a result of migration of material
> that had been out-of-line into the table cells; one example is
> in json_populate_record, about halfway down this page:
> 
> https://www.postgresql.org/docs/devel/functions-json.html
> 
> The text of the list items seems to be getting indented to the
> same extent as a not-in-a-table <itemizedlist> list does ---
> but the bullets aren't indented nearly as much, making for
> weird spacing.  (There's a short <itemizedlist> at the top of
> the same page that you can compare to.)

Looking at the code, I believe this is a pretty straightforward
adjustment. I can include it with the aforementioned changes.

Jonathan

[1]
https://www.postgresql.org/message-id/3f8560a6-9044-bdb8-6b3b-68842570db18@postgresql.org

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

Dean Rasheed <dean.a.rasheed@gmail.com> — 2020-05-05T09:33:55Z

On Mon, 4 May 2020 at 22:22, Tom Lane <tgl@sss.pgh.pa.us> wrote:
>
> * <returnvalue> is also quite sticky about inserting other sorts
> of font-changing environments inside it.  As an example, it'll let
> you include <replaceable> but not <type>, which seems pretty weird
> to me.  This is problematic in some places where it's desirable to
> have text rather than just a type name, for example
>
>         <function>stddev</function> ( <replaceable>numeric_type</replaceable> )
>         <returnvalue></returnvalue> <type>double precision</type>
>         for <type>real</type> or <type>double precision</type>,
>         otherwise <type>numeric</type>
>
> Now I could have done this example by spelling out all six varieties of
> stddev() separately, and maybe I should've, but it seemed overly bulky
> that way.

FWIW, I prefer having each variety spelled out separately. For
example, I really like the new way that aggregates like sum() and
avg() are displayed. To me, having all the types listed like that is
much more readable than having to read and interpret a piece of free
text.

Similarly, for other functions like gcd(), lcm() and mod(). I think it
would be better to get rid of numeric_type, and just list all the
variants of each function.

Regards,
Dean

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

Oleksandr Shulgin <oleksandr.shulgin@zalando.de> — 2020-05-05T11:39:46Z

On Mon, May 4, 2020 at 11:22 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:

> I've now completed updating chapter 9 for the new layout,
> and the results are visible at
> https://www.postgresql.org/docs/devel/functions.html
> There is more to do --- for instance, various contrib modules
> have function/operator tables that should be synced with this
> design.  But this seemed like a good place to pause and reflect.
>

Would it be premature to complain about the not-that-great look of Table
9.1 now?

Compare the two attached images: the screenshot from
https://www.postgresql.org/docs/devel/functions-comparison.html
vs the GIMP-assisted pipe dream of mine to align it to the right edge of
the table cell.

I don't have the faintest idea how to achieve that using SGML at the
moment, but it just looks so much nicer to me. ;-)

Regards,
--
Alex

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

Tom Lane <tgl@sss.pgh.pa.us> — 2020-05-05T14:07:03Z

Dean Rasheed <dean.a.rasheed@gmail.com> writes:
> On Mon, 4 May 2020 at 22:22, Tom Lane <tgl@sss.pgh.pa.us> wrote:
>> Now I could have done this example by spelling out all six varieties of
>> stddev() separately, and maybe I should've, but it seemed overly bulky
>> that way.

> FWIW, I prefer having each variety spelled out separately. For
> example, I really like the new way that aggregates like sum() and
> avg() are displayed. To me, having all the types listed like that is
> much more readable than having to read and interpret a piece of free
> text.

> Similarly, for other functions like gcd(), lcm() and mod(). I think it
> would be better to get rid of numeric_type, and just list all the
> variants of each function.

I had had the same idea to start with, but it didn't survive first contact
with table 9.4 (Mathematical Operators).  It's not really reasonable to
spell out all the variants of + ... especially not if you want to be
precise, because then you'd have to list the cross-type variants too.
If I counted correctly, there are fourteen variants of binary + that
would have to be listed in that table, never mind the other common
operators.

max() and min() have a similar sort of problem --- the list of variants
is just dauntingly long, and it's not that interesting either.
I wrote out sum() and avg() the way I did because they have a somewhat
irregular mapping from input to output types, so it seemed better to
just list the alternatives explicitly.

I don't object too much to spelling out the variants of stddev()
and variance(), if there's a consensus for that.  But getting rid
of "numeric_type" entirely seems impractical.

			regards, tom lane

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

Tom Lane <tgl@sss.pgh.pa.us> — 2020-05-05T15:17:24Z

Oleksandr Shulgin <oleksandr.shulgin@zalando.de> writes:
> Would it be premature to complain about the not-that-great look of Table
> 9.1 now?
> Compare the two attached images: the screenshot from
> https://www.postgresql.org/docs/devel/functions-comparison.html
> vs the GIMP-assisted pipe dream of mine to align it to the right edge of
> the table cell.

Hmph.  I experimented with the attached patch, but at least in my browser
it only reduces the spacing inconsistency, it doesn't eliminate it.
And from a semantic standpoint, this is not nice markup.

Doing better would require substantial foolery with sub-columns and I'm
not even sure that it's possible to fix that way.  (We don't have huge
control over inter-column spacing, I don't think.)

On the whole, if this is our worst table problem, I'm happy ;-)

			regards, tom lane