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

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