Received: from malur.postgresql.org ([217.196.149.56])
	by arkaria.postgresql.org with esmtps
 (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256)
	(Exim 4.92)
	(envelope-from <pgsql-docs-owner+archive@lists.postgresql.org>)
	id 1jNN6e-0001vx-I1
	for pgsql-docs@arkaria.postgresql.org; Sat, 11 Apr 2020 20:52:00 +0000
Received: from localhost ([127.0.0.1] helo=malur.postgresql.org)
	by malur.postgresql.org with esmtp (Exim 4.92)
	(envelope-from <pgsql-docs-owner+archive@lists.postgresql.org>)
	id 1jNN6a-0007ae-Vd
	for pgsql-docs@arkaria.postgresql.org; Sat, 11 Apr 2020 20:51:56 +0000
Received: from makus.postgresql.org ([2001:4800:3e1:1::229])
	by malur.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256)
	(Exim 4.92)
	(envelope-from <tgl@sss.pgh.pa.us>)
	id 1jNN6a-0007aX-Pl
	for pgsql-docs@lists.postgresql.org; Sat, 11 Apr 2020 20:51:56 +0000
Received: from sss.pgh.pa.us ([66.207.139.130])
	by makus.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
	(Exim 4.92)
	(envelope-from <tgl@sss.pgh.pa.us>)
	id 1jNN6T-0008OO-OT
	for pgsql-docs@lists.postgresql.org; Sat, 11 Apr 2020 20:51:55 +0000
Received: from sss1.sss.pgh.pa.us (localhost [127.0.0.1])
	by sss.pgh.pa.us (8.14.4/8.14.4) with ESMTP id 03BKplk1000702;
	Sat, 11 Apr 2020 16:51:47 -0400
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
In-reply-to: <525a6c9e-a4e2-cd8f-54b6-b69f40d70289@gmail.com>
References: <20200212221818.GA15503@alvherre.pgsql>
 <23574.1581555393@sss.pgh.pa.us> <10810.1581883655@sss.pgh.pa.us>
 <5d1f5b72-1b4a-6e15-6730-d94e2252a073@gmail.com>
 <525a6c9e-a4e2-cd8f-54b6-b69f40d70289@gmail.com>
Comments: In-reply-to Alexander Lakhin <exclusion@gmail.com>
	message dated "Wed, 19 Feb 2020 00:00:00 +0300"
MIME-Version: 1.0
Content-Type: text/plain; charset="UTF-8"
Content-ID: <700.1586638307.1@sss.pgh.pa.us>
Content-Transfer-Encoding: quoted-printable
Date: Sat, 11 Apr 2020 16:51:47 -0400
Message-ID: <701.1586638307@sss.pgh.pa.us>
List-Id: <pgsql-docs.lists.postgresql.org>
List-Help: <https://lists.postgresql.org/manage/>
List-Subscribe: <https://lists.postgresql.org/manage/>
List-Post: <mailto:pgsql-docs@lists.postgresql.org>
List-Owner: <mailto:pgsql-docs-owner@lists.postgresql.org>
List-Archive: <https://www.postgresql.org/list/pgsql-docs>
Precedence: bulk

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=3D".75em" font-family=3D"{$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 =E2=86=92 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></menuch=
oice>).

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