Re: make libpq documentation navigable between functions

On 2019-05-12 11:02, Fabien COELHO wrote:
> While writing some libpq code, I found it quite irritating that the
> documentation is not navigable, so when a function appears in a
> description of another function and you are interested, there is no direct
> way to find it, you have to go to the index or to guess in which section
> it is going to appear.
>
> Attached:
> - a first patch to add a few missing "id"
> - a script which adds the references
> - a second patch which is the result of applying the script
> on top of the first patch, so that all PQ* functions are
> replaced by links to their documentation.

I think this is a good idea.

The rendering ends up a bit inconsistent depending on the context of the
link target. Sometimes it's monospaced, sometimes it's not, sometimes
in the same sentence. I think we should improve that a bit. One
approach for making the currently non-monospaced ones into monospace
would be to make the xref targets point to <function> elements but
*don't* put xreflabels on those. This will currently produce a warning

Don't know what gentext to create for xref to: "function"

but we can write a template

<xsl:template match="function" mode="xref-to">

and then we can control the output format of that.

--
Peter Eisentraut http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services