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

On Sun, 19 Apr 2020 at 09:23, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)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.