Re: make libpq documentation navigable between functions

Hello Peter,

Thanks for the review. I could use some more input:-)

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

Yep, I noticed. Why not.

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

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

The attached script does the transformation basic, and the patch is the
result of applying the script to libpq.sgml in master. As I'm currently
lost about the required xslt changes, so the html generated sets "???"
everywhere, and there is a warning.

A little more help would be appreciated, eg a pointer to an example to
follow, and which file(s) should be changed?

Thanks in advance,

--
Fabien.