Peter Eisentraut <peter.eisentr...@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