Date: Wed, 12 Feb 2020 18:30:39 -0300
From: Alvaro Herrera <alvherre@2ndquadrant.com>
To: Tom Lane <tgl@sss.pgh.pa.us>
Cc: Alexander Lakhin <exclusion@gmail.com>, pgsql-docs@lists.postgresql.org
Subject: Re: Getting our tables to render better in PDF output
Message-ID: <20200212213039.GA12997@alvherre.pgsql>
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
In-Reply-To: <14006.1581541092@sss.pgh.pa.us>
User-Agent: Mutt/1.10.1 (2018-07-13)
Precedence: bulk

On 2020-Feb-12, Tom Lane wrote:

> For amusement's sake, attached is a screenshot of what Table 9-33
> looks like in A4 format, with my one-row-per-example patch of
> yesterday plus a few manually-added zero-width spaces to break up
> the examples.  This is the first PDF rendering of that table that
> I've seen that I actually like.

I like this.  The trick of mkaing the first cell take up two or three
rows makes this much clearer and sensible than what I had obtained.

> I also attached a screenshot of a segment of Table 9-31, to show
> what that layout proposal looks like.  It's a little busier, but
> it does have the advantage that it's clearer how to apply that
> format to operator tables.  The "returns <type>" notation isn't used
> anywhere in SQL for operators, so I am not in love with the idea of
> writing the operator tables that way.

Yeah, that's a little less obvious.  I just noticed that the operators
tables show the operator names but not the input datatypes except in the
examples.  Perhaps we could use a layout with a cell labelled
"signature" (namest=col2 nameend=col3) instead of input types + return
types and separate them using &rightarrow; which would look like this:
   date + integer → date

> Also worth noting is that in most function tables, and certainly
> in the operator tables, we could make the first column narrower.
> The same table with the first column half as wide as the others
> is depicted in the last screenshot.  (For this particular table,
> doing that would require breaking some of the longer function
> names such as transaction_timestamp.  Not sure whether that's
> a net win, but we do have the option.)

I like making that column narrower.

> One issue that I've found is that the toolchain has no idea that
> the table rows are in groups, so it's happy to split a table
> across pages with a function's description and/or examples on
> a new page.  No idea if there's any way around that.  Fortunately
> it's not an issue in HTML, so maybe we don't have to fix it.

My vote goes to postponing a solution to this problem :-)

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