On Mon, Apr 13, 2020 at 12:28 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:
Corey Huinker <corey.huinker@gmail.com> writes: > I was thinking that there were references that included parameters, but I'm > not finding any with actual parameter values, so at most we'd lose the "()" > of a reference.
We could possibly stick the parens into the indexterm text. Arguably that's an improvement on its own merits, since it'd become clearer which index entries are function names. If you don't want that, another idea is to put xreflabel options that include the parens into the indexterm tags. Or we can just standardize on not having parens, but personally I like them. Without parens, for clarity you really have to write "function <function>foo</function>" which is redundant-looking in the XML and hence easy to get wrong.
That makes sense to me. There may be some hope for the font via the xrefstyle attribute, but I'm not educated well enough on docbook to know for sure.
> Assuming we want to make the anchors visible, we need a way for people to > discover the anchors we've made, and my thought there is that we make the > first definition a non-xref link to the indexterm just above it. Any > thoughts on what the best way to do that is?
I'm not really buying into that as a requirement. For one thing, the anchor name will be 100% predictable.
The anchor name is deterministic (or I intend it to be) but the existence of the link is not predictable. So while having no visible link is fine for internal links which we create, I'm envisioning a not-very-experienced reader wanting to help an even-less-experienced person. If they find the date_part function, and they see that the word "date_part" is itself clickable, they'll probably click it once, see that it's a link, and send the less-experienced person the anchored link instead of the broader page link. They're very unlikely to try to forge their own anchor link in the hopes that it already exists.
One thing that I noticed while playing with this last night is that even though <xref> or <link> links will take you right to the exact table entry, the index entries generated from the indexterms only point to the page. That seems pretty sad, why isn't it better?
As you've described it it does seem very odd, but maybe I'm just misunderstanding.