On Sun, 19 Apr 2020 at 09:23, Tom Lane <t...@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.