From: Tom Lane <tgl@sss.pgh.pa.us>
To: Corey Huinker <corey.huinker@gmail.com>
Cc: Alexander Lakhin <exclusion@gmail.com>
Cc: pgsql-docs@lists.postgresql.org
Subject: Re: Getting our tables to render better in PDF output
Date: Sun, 12 Apr 2020 20:38:24 -0400
Message-ID: <32159.1586738304@sss.pgh.pa.us> (raw)
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>
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
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, corey.huinker@gmail.com, exclusion@gmail.com, pgsql-docs@lists.postgresql.org
Subject: Re: Getting our tables to render better in PDF output
In-Reply-To: <32159.1586738304@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