Re: Getting our tables to render better in PDF output - Mailing list pgsql-docs

I set this idea aside during the final v13 commitfest, but I figure that
it's fine to work on documentation improvements during feature freeze,
so I'm going to try to push it forward over the next few weeks.

Barring objections, I want to commit more or less what I posted at [1],
verify that it looks decent on the website, and then incrementally
convert the rest of our function/operator tables to the new style.
It's too big a job to get done in one commit, but a table or two at
a time seems like a reasonable approach.  After the table format
conversion is finished we can take a look at how much of a
bad-line-breaks issue we still have, and decide what to do about that.

First though, we need to nail down exactly what markup to use.

Alexander Lakhin <exclusion@gmail.com> writes:
> Maybe it's better to use the same formatting as in the docbook xsl
> template (see docbook/stylesheet/docbook-xsl/xhtml-1_1/inline.xsl).
> There "$menuchoice.menu.separator" is enclosed in <fo:inline
> font-size=".75em" font-family="{$symbol.font.family}">...</fo:inline>
> and you can see the effect on page 536 (IPC parameters can be set in the
> System Administration Manager (SAM) under Kernel Configu-
> ration → Configurable Parameters.)

Yeah, I see that that uses a right-arrow and it looks quite decent in
both HTML and PDF renderings.  So we ought to borrow those markup details
rather than solving the problem from scratch.

> Yet another possibility is to use the docbook tags:
> <funcdef><function>func()</function>
> <returnvalue>int</returnvalue></funcdef>.
> Then we can define the desired formatting for such markup (similar to
> <menuchoice><guimenu>...</guimenu><guimenuitem>...</guimenuitem></menuchoice>).

I looked into this.  It appears that <funcdef> is fairly tightly tied
to C function declaration syntax, plus it sounds like it might get
deprecated in future docbook versions.  So I don't want to use that.
But we could use <returnvalue> which seems to be defined independently
of <funcdef>, and isn't being used in our docs at present.  I found
by experimentation that this doesn't work:

  <returnvalue><type>date</type></returnvalue>

(it complains that these two tag types can't be nested); but this does:

  <returnvalue>date</returnvalue>

So if we can get <returnvalue> to both insert a right arrow and switch the
font to match <type>'s choice, this would work more or less decently, and
it's probably cleaner than the bare-entity-reference approach I posted
before.  I don't have the XSL skills to get that to work though.
Anyone want to help out?

            regards, tom lane

[1] https://www.postgresql.org/message-id/23574.1581555393%40sss.pgh.pa.us