From: Pierre Giraud <pierre.giraud@dalibo.com>
To: Tom Lane <tgl@sss.pgh.pa.us>
To: Robert Haas <robertmhaas@gmail.com>
Cc: Steven Pousty <steve.pousty@gmail.com>
Cc: Pavel Stehule <pavel.stehule@gmail.com>
Cc: Isaac Morland <isaac.morland@gmail.com>
Cc: PostgreSQL Developers <pgsql-hackers@lists.postgresql.org>
Subject: Re: Poll: are people okay with function/operator table redesign?
Date: Thu, 16 Apr 2020 08:26:54 +0200
Message-ID: <f1f6889d-8caf-b2ed-fab5-214ebcfa0a07@dalibo.com> (raw)
In-Reply-To: <29261.1586989134@sss.pgh.pa.us>
References: <8691.1586798003@sss.pgh.pa.us>
<ff4b8688-c941-8bfc-5399-4f0744144773@dalibo.com>
<CAMsGm5dhAAf9YZh3scCcs_SX+2F2k1QyRPWn0hgnOX2xQOPo4Q@mail.gmail.com>
<CAFj8pRB0CL4sNuskp8NQ0g4stiOfy_Rfau35LyncwNvciJarZw@mail.gmail.com>
<CA+TgmobK4iziOm8uMJ4pS+W3VkB+OarEb+vXePxfAVMghynn6g@mail.gmail.com>
<CAKmB1PHtM0rt9Ja5_W7osrWEQsoGbZ-morn9vpzQF8rSDXwp6Q@mail.gmail.com>
<30753.1586971147@sss.pgh.pa.us>
<29261.1586989134@sss.pgh.pa.us>
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
>
Attachments:Capture du 2020-04-16 08-24-19.png (image/png, 89.4K) downloadview image
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-hackers@postgresql.org
Cc: pierre.giraud@dalibo.com, tgl@sss.pgh.pa.us, robertmhaas@gmail.com, steve.pousty@gmail.com, pavel.stehule@gmail.com, isaac.morland@gmail.com, pgsql-hackers@lists.postgresql.org
Subject: Re: Poll: are people okay with function/operator table redesign?
In-Reply-To: <f1f6889d-8caf-b2ed-fab5-214ebcfa0a07@dalibo.com>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox