From: Tom Lane <tgl@sss.pgh.pa.us>
To: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
Cc: Alvaro Herrera <alvherre@2ndquadrant.com>
Cc: Robert Haas <robertmhaas@gmail.com>
Cc: Steven Pousty <steve.pousty@gmail.com>
Cc: Pavel Stehule <pavel.stehule@gmail.com>
Cc: Isaac Morland <isaac.morland@gmail.com>
Cc: Pierre Giraud <pierre.giraud@dalibo.com>
Cc: PostgreSQL Developers <pgsql-hackers@lists.postgresql.org>
Subject: Re: Poll: are people okay with function/operator table redesign?
Date: Sun, 19 Apr 2020 09:23:01 -0400
Message-ID: <26009.1587302581@sss.pgh.pa.us> (raw)
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>
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
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-hackers@postgresql.org
Cc: tgl@sss.pgh.pa.us, peter.eisentraut@2ndquadrant.com, alvherre@2ndquadrant.com, robertmhaas@gmail.com, steve.pousty@gmail.com, pavel.stehule@gmail.com, isaac.morland@gmail.com, pierre.giraud@dalibo.com, pgsql-hackers@lists.postgresql.org
Subject: Re: Poll: are people okay with function/operator table redesign?
In-Reply-To: <26009.1587302581@sss.pgh.pa.us>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox