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 >
