Re: make libpq documentation navigable between functions

On 2019-07-10 09:51, Fabien COELHO wrote:
>> 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.
> 
> I understand that you mean turning function usages:
> 
>    <function>PQbla</function>
> 
> into:
> 
>    <xref linkend="libpq-fun-pqbla"/>
> 
> so that it points to function definitions that would look like:
> 
>    <function id="libpq-fun-pqbla">PQbla</function>...
> 
> (note: "libpq-pqbla" ids are already taken).

What I really meant was that you determine the best link target in each
case.  If there already is an id on a <varlistentry>, then use that.  If
not, then make an id on something else, most likely the <function> element.

What you have now puts ids on both the <varlistentry> and the
<function>, which seems unnecessary and confusing.

For some weird reason this setup with link targets in both
<varlistentry> and enclosed <function> breaks the PDF build, but if you
change it the way I suggest then those errors go away.

>> This will currently produce a warning Don't know what gentext to create 
>> for xref to: "function"
> 
> Indeed.
> 
>> but we can write a template
>>
>> <xsl:template match="function" mode="xref-to">
>>
>> and then we can control the output format of that.
> 
> This step is (well) beyond my current XSLT proficiency, which is null 
> beyond knowing that it transforms XML into whatever. Also I'm unsure into 
> which of the 11 xsl file the definition should be included and what should 
> be written precisely.

See attached patch.

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