From: Tom Lane <tgl@sss.pgh.pa.us>
To: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
cc: Alvaro Herrera <alvherre@2ndquadrant.com>,
        Robert Haas <robertmhaas@gmail.com>,
        Steven Pousty <steve.pousty@gmail.com>,
        Pavel Stehule <pavel.stehule@gmail.com>,
        Isaac Morland <isaac.morland@gmail.com>,
        Pierre Giraud <pierre.giraud@dalibo.com>,
        PostgreSQL Developers <pgsql-hackers@lists.postgresql.org>
Subject: Re: Poll: are people okay with function/operator table redesign?
In-reply-to: <f17a1d71-e8bf-3571-bcda-081289eccb31@2ndquadrant.com>
References: <20200416230304.GA28390@alvherre.pgsql>
 <17560.1587083109@sss.pgh.pa.us>
 <f17a1d71-e8bf-3571-bcda-081289eccb31@2ndquadrant.com>
Comments: In-reply-to Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
	message dated "Sun, 19 Apr 2020 12:46:32 +0200"
MIME-Version: 1.0
Content-Type: text/plain; charset="us-ascii"
Content-ID: <26008.1587302581.1@sss.pgh.pa.us>
Date: Sun, 19 Apr 2020 09:23:01 -0400
Message-ID: <26009.1587302581@sss.pgh.pa.us>
Precedence: bulk

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