Subject: Re: Poll: are people okay with function/operator table redesign?
To: Tom Lane <tgl@sss.pgh.pa.us>, Alvaro Herrera <alvherre@2ndquadrant.com>
References: <20200416230304.GA28390@alvherre.pgsql>
 <17560.1587083109@sss.pgh.pa.us>
Cc: 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>
From: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
Organization: 2ndQuadrant
Message-ID: <f17a1d71-e8bf-3571-bcda-081289eccb31@2ndquadrant.com>
Date: Sun, 19 Apr 2020 12:46:32 +0200
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.14; rv:52.0)
 Gecko/20100101 Thunderbird/52.9.1
MIME-Version: 1.0
In-Reply-To: <17560.1587083109@sss.pgh.pa.us>
Content-Type: text/plain; charset=windows-1252; format=flowed
Content-Language: en-US
Content-Transfer-Encoding: 7bit
Precedence: bulk

On 2020-04-17 02:25, Tom Lane wrote:
> I eventually figured out that the approved way to do per-table-entry
> customization is to attach "role" properties to the DocBook elements,
> and then key off the role names in applying formatting changes in
> the customization layer.  So attached is a v3 that handles the desired
> formatting changes by applying a hanging indent to table <entry>
> contents if the entry is marked with role="functableentry".  It may
> well be possible to do this in a cleaner fashion, but this seems
> good enough for discussion.

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.

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.

-- 
Peter Eisentraut              http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services