Corey Huinker <corey.huinker@gmail.com> writes: > If it's ok to work on doc patches during the feature freeze, and if we're > already tweaking function documentation, would it be possible to add in > anchor ids to function definitions so that we could reference specific > functions (or rather the family of functions that share a name like this: > https://www.postgresql.org/docs/devel/functions-datetime.html#FUNCTION-DATE-PART > or similar. I tried it out just now, and the anchoring works, but there's > no obvious place to acquire the anchored link, so presumably we'd > anchor-ize the function name itself.
Don't have a strong opinion about that, but it'd sure be a lot of new anchors.
True, but it'd would be a lot better than pointing a person to a page that has 20+ functions defined on it.
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.
The docbook spec doesn't allow an xref inside a function tag, and no tags at all can be inside an xref.