Re: Getting our tables to render better in PDF output

On Sat, Apr 11, 2020 at 6:41 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:

> 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.