Date: Mon, 13 Apr 2020 14:07:58 -0400
From: Alvaro Herrera <alvherre@2ndquadrant.com>
To: Tom Lane <tgl@sss.pgh.pa.us>
Cc: pgsql-hackers@lists.postgresql.org
Subject: Re: Poll: are people okay with function/operator table redesign?
Message-ID: <20200413180758.GA12210@alvherre.pgsql>
MIME-Version: 1.0
Content-Type: text/plain; charset=iso-8859-1
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
In-Reply-To: <8691.1586798003@sss.pgh.pa.us>
User-Agent: Mutt/1.10.1 (2018-07-13)
Precedence: bulk

On 2020-Apr-13, Tom Lane wrote:

> As discussed in the thread at [1], I've been working on redesigning
> the tables we use to present SQL functions and operators.  The
> first installment of that is now up; see tables 9.30 and 9.31 at
> 
> https://www.postgresql.org/docs/devel/functions-datetime.html
> 
> and table 9.33 at
> 
> https://www.postgresql.org/docs/devel/functions-enum.html
> 
> Before I spend more time on this, I want to make sure that people
> are happy with this line of attack.  Comparing these tables to
> the way they look in v12, they clearly take more vertical space;
> but at least to my eye they're less cluttered and more readable.
> They definitely scale a lot better for cases where a long function
> description is needed, or where we'd like to have more than one
> example.

I am torn.  On the one side, I think this new format is so much better
than the old one that we should definitely use it for all tables.  On
the other side, I also think this format is slightly more complicated to
read, so perhaps it would be sensible to keep using the old format for
the simplest tables.

One argument for the first of those positions is that if this new table
layout is everywhere, it'll take less total time to get used to it.


One improvement (that I don't know is possible in docbook) would be to
have the inter-logical-row line be slightly thicker than the
intra-logical-row one.  That'd make each entry visually more obvious.

I think you already mentioned the PDF issue that these multi-row entries
are sometimes split across pages.  I cannot believe docbook is so stupid
not to have a solution to that problem, but I don't know what that
solution would be.

-- 
Álvaro Herrera                https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services