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 1jNn7V-0005fL-JL
	for pgsql-docs@arkaria.postgresql.org; Mon, 13 Apr 2020 00:38:37 +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 1jNn7U-0007bh-0k
	for pgsql-docs@arkaria.postgresql.org; Mon, 13 Apr 2020 00:38:36 +0000
Received: from magus.postgresql.org ([2a02:c0:301:0:ffff::29])
	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 1jNn7T-0007au-R5
	for pgsql-docs@lists.postgresql.org; Mon, 13 Apr 2020 00:38:35 +0000
Received: from sss.pgh.pa.us ([66.207.139.130])
	by magus.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
	(Exim 4.92)
	(envelope-from <tgl@sss.pgh.pa.us>)
	id 1jNn7M-0007I6-3y
	for pgsql-docs@lists.postgresql.org; Mon, 13 Apr 2020 00:38:34 +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 03D0cOeZ032160;
	Sun, 12 Apr 2020 20:38:24 -0400
From: Tom Lane <tgl@sss.pgh.pa.us>
To: Corey Huinker <corey.huinker@gmail.com>
cc: Alexander Lakhin <exclusion@gmail.com>, pgsql-docs@lists.postgresql.org
Subject: Re: Getting our tables to render better in PDF output
In-reply-to: 
 <CADkLM=dAL86DTUEZY4rigdnB5-zTa0rQvz-fdSUmXqDV3zTQuQ@mail.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>
 <701.1586638307@sss.pgh.pa.us>
 <CADkLM=dtbn6kyt6Qoqy+mj5YOgcGK+rQ6WpkQm-cggdR2WJceQ@mail.gmail.com>
 <6162.1586644916@sss.pgh.pa.us>
 <CADkLM=dAL86DTUEZY4rigdnB5-zTa0rQvz-fdSUmXqDV3zTQuQ@mail.gmail.com>
Comments: In-reply-to Corey Huinker <corey.huinker@gmail.com>
	message dated "Sun, 12 Apr 2020 01:31:22 -0400"
MIME-Version: 1.0
Content-Type: text/plain; charset="us-ascii"
Content-ID: <32158.1586738304.1@sss.pgh.pa.us>
Date: Sun, 12 Apr 2020 20:38:24 -0400
Message-ID: <32159.1586738304@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

Corey Huinker <corey.huinker@gmail.com> writes:
> On Sat, Apr 11, 2020 at 6:41 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:
>> Is that going to be a problem for the docs toolchain?  If
>> the anchors are attached to individual function names rather than
>> sections or paragraphs, do they actually work well as link references?
>> (I'm particularly wondering how an <xref> would render.)

> So I can't speak to any scalability issues for adding a bunch of refs, but
> I did try this out for justify_days() (diff attached) and here's what I
> found:
> * <link linkend="function-justify-days">justify_days</link>
>    This made a link, in the same font as any other link ref.
> * <xref linkend="function-justify-days"/>
>    This made a link that looks exactly like the previous one, with the text
> "justify_days", so if we're fine with the font change, we could use that
> * <link
> linkend="function-justify-days"><function>justify_days</function></link>
>    This made the link we want in the function font.

Hm.  Attaching the link ID to an <indexterm> is an interesting hack.
It makes me nervous, because it's not immediately obvious that that
won't cause links to lead to someplace in the index.  Still, it does
seem to work the way we want in both HTML and PDF output, so maybe
we can get away with it.  We've previously found that attaching an
ID to a <row> does *not* work, at least not in PDF --- see the
existing attempts for function-encode and function-decode, which
give rise to PDF build warnings and no functioning links.  I checked
just now and attaching the ID to the <entry> acts the same, so it
seems it's <indexterm> or nothing.

My inclination is to standardize on using <xref> for references and
just accept the lack of a special font.  It's not worth the notational
pain to use both <link> and <function>, especially not in HTML output
where links will probably get rendered specially anyway.  We
previously made the same tradeoff with respect to GUC variables,
and I've not seen many complaints.  (I experimented with putting
<function> into the indexterm text, but that did not help.)

I'd be a bit inclined to shorten the ID prefix to "func-", just
in the interests of carpal tunnel avoidance.

			regards, tom lane