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