From: Tom Lane <tgl@sss.pgh.pa.us>
To: Alexander Lakhin <exclusion@gmail.com>
Cc: pgsql-docs@lists.postgresql.org
Subject: Re: Getting our tables to render better in PDF output
Date: Wed, 12 Feb 2020 15:58:12 -0500
Message-ID: <14006.1581541092@sss.pgh.pa.us> (raw)
In-Reply-To: <8a99bdca-85ab-27d6-83b4-9fc7113839f2@gmail.com>
References: <9326.1581457869@sss.pgh.pa.us>
<8a99bdca-85ab-27d6-83b4-9fc7113839f2@gmail.com>
Alexander Lakhin <exclusion@gmail.com> writes:
> Please look at a less invasive approach that we use at Postgres Pro for
> some time (mainly for improving the translated documentation, but it
> works for the original one too). The idea is to add zero-width spaces
> after/before some chars ('(', ',', '[', etc) to let fop split lines
> where desired. It has one disadvantage - it's not search-friendly
> (though maybe that is application-dependent).
> But if it's feasible, I think this approach can at least complement a
> manual tables reformatting. Decreasing a font size in the tables seems
> appropriate to me too.
Hmm, interesting proposal. I experimented and verified that injecting
zero-width space (​) does allow line breaking to occur in both
HTML and PDF output, so this could be a route to improving the situation
for overlength example texts. I do not think I like the idea of
automatically injecting tons of them, though. As you say, it might
hinder searching; and it would allow some silly breaks; and there are
cases where it still wouldn't find a break, such as the examples for
sha256() et al. I'd be happier about manually inserting breaks just
in the places we really need them. To keep the source readable, I'd
want to write something like "&zwsp;" not a numeric entity code,
but it looks like we can define custom entities if we want.
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 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.
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.)
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.
Thoughts?
regards, tom lane
Attachments:
[image/png] table9-33.png (220.6K, ../14006.1581541092@sss.pgh.pa.us/2-table9-33.png)
download | view image
[image/png] table9-31.png (232.5K, ../14006.1581541092@sss.pgh.pa.us/3-table9-31.png)
download | view image
[image/png] table9-31-narrow.png (197.1K, ../14006.1581541092@sss.pgh.pa.us/4-table9-31-narrow.png)
download | view image
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-docs@postgresql.org
Cc: tgl@sss.pgh.pa.us, exclusion@gmail.com, pgsql-docs@lists.postgresql.org
Subject: Re: Getting our tables to render better in PDF output
In-Reply-To: <14006.1581541092@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