Corey Huinker <corey.huin...@gmail.com> writes: > On Sat, Apr 11, 2020 at 6:41 PM Tom Lane <t...@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