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

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.

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

Hello Peter,

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.

Ok, sorry I misunderstood.

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.

Thanks!

Attached script does, hopefully, the expected transformation. It adds ids
to <function> occurrences when the id is not defined elsewhere.

Attached v3 is the result of applying your kindly provided xslt patch plus
the script on "libpq.sgml".

Three functions are ignored because no documentation is found:
PQerrorField (does not exist anywhere in the sources),
PQsetResultInstanceData (idem) and PQregisterThreadLock (it exists).

Doc build works for me and looks ok.

--
Fabien.

On 2019-07-22 22:56, Fabien COELHO wrote:

Attached script does, hopefully, the expected transformation. It adds ids
to <function> occurrences when the id is not defined elsewhere.

Attached v3 is the result of applying your kindly provided xslt patch plus
the script on "libpq.sgml".

Three functions are ignored because no documentation is found:
PQerrorField (does not exist anywhere in the sources),
PQsetResultInstanceData (idem) and PQregisterThreadLock (it exists).

Doc build works for me and looks ok.

I have committed this with some additions.

I have changed all the function-related id attributes in libpq.sgml to
be mixed case, for easier readability. So if you run your script again,
you can omit the lc() call.

I also needed to make some changes to the markup in some places to
remove extra whitespace that would have appeared in the generated link.
(This was already happening in some places, but your patch would have
repeated it in many places.)

Also, due to some mysterious problems with the PDF toolchain I had to
remove some links. Your script would find those, so I won't list them
here. If you put those back in, the PDF build breaks. If you want to
work out why, feel free to submit more patches. Otherwise I'm happy to
leave it as is now; it's very useful.

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

Hello Peter,

I have committed this with some additions.

Thanks for the push. It was really a pain to write a small libpq app
without navigation.

Also, due to some mysterious problems with the PDF toolchain I had to
remove some links. Your script would find those, so I won't list them
here. If you put those back in, the PDF build breaks. If you want to
work out why, feel free to submit more patches. Otherwise I'm happy to
leave it as is now; it's very useful.

Ok fine with me for now as well. I'm not keen to invest more time on the
documentation tool chain.

--
Fabien.