Re: Getting our tables to render better in PDF output

On Mon, Apr 13, 2020 at 12:28 PM Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:

> Corey Huinker <corey(dot)huinker(at)gmail(dot)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.