Getting our tables to render better in PDF output

The crummy formatting of our tables of functions and operators has
been an issue for a long time. To my mind, there are several things
that need to be addressed:

* The layout is completely unfriendly to function descriptions that
run to more than a few words.

* It's not very practical to have more than one example per function
(or at least, we seldom do so).

* The results look completely awful in PDF format, because of the
narrow effectively-available space, plus the fact that the toolchain
will prefer to overprint following columns instead of breaking text
where there's no whitespace.

In [1], Alvaro suggested that we might be able to improve matters by
taking advantage of DocBook's features for column and row spanning.
I did some concrete experimentation in that line, and attached are
two alternative patches that show a couple of things we might do.
Both patches change tables 9.31 (Date/Time Functions) and 9.33
(Enum Support Functions), which I chose somewhat at random, but of
course there would be a lot more to be done if we choose to go this way.

The first patch uses only one row for each function example, while
the second patch uses two rows (i.e., example and result in separate
table rows). Otherwise they're the same.

I initially did the enum-support table, and what I tried there included
getting rid of the separate table column for function result type by
writing the functions in the form "func(argtypes) returns resulttype".
(Note that this table failed to specify the result types at all before,
which doesn't seem great.) The layout idea is

function name, args, result description
example example result

where we can repeat the "example / example result" row if we want more
examples per function. Alternatively, in the second patch, it's

function name, args, result description
example
example result

To my eyes, the first alternative is preferable in HTML, unless maybe you
want to read the manual in a *very* narrow browser window. But some of
the examples/results still overrun the available space when looking
at it in PDF A4 format. The second patch fixes that problem, but seems
not very pretty in a normal-width browser window.

When I tried to apply the same idea to the date/time functions table,
it didn't really work well at all, mainly because of a few beasts like
make_interval() --- that caused the left column to be so wide that the
right-hand columns were horrid. (At least with the toolchain version
I'm using, it seems like the colwidth specifications are respected
rigidly in PDF output but just plain ignored in HTML output. What
seems to happen in HTML is that earlier columns get their preferred
width and later ones get squeezed.)

So the layout idea that the patches show for that table is

function name arg types result type
description
example example result

or

function name arg types result type
description
example
example result

(Even with that, I had to savage make_interval's arg-types list a bit
to keep that column from eating too much space...)

I'm not especially wedded to any of these ideas, but I hope to provoke
some discussion about what we might do in this area. DocBook tables
aren't the greatest layout tool in the world, but they do have abilities
we're not exploiting.

Even with these changes, the amount of space available for examples
and results in PDF format is pretty tiny. With examples and results
in the same row, it seems that you can only have a couple of dozen
consecutive non-whitespace characters without running into overwrite
issues, whereas in HTML format the trouble threshold is a good deal
higher. I wonder if we could improve matters by switching to some
narrower font for <literal> text in PDF?

regards, tom lane

[1] https://www.postgresql.org/message-id/20200116184444.GA25792%40alvherre.pgsql