Horton

Thread

Commits

  1. doc: Make libpq documentation navigable between functions

  2. doc: Add support for xref to command and function elements

  1. make libpq documentation navigable between functions

    Fabien COELHO <coelho@cri.ensmp.fr> — 2019-05-12T09:02:16Z

    Hello dev,

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.

While doing this, I noticed that two functions are not documented: 
PQregisterThreadLock and PQsetResultInstanceData.

-- 
Fabien.

  2. Re: make libpq documentation navigable between functions

    Peter Eisentraut <peter.eisentraut@2ndquadrant.com> — 2019-07-05T07:48:47Z

    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

  3. Re: make libpq documentation navigable between functions

    Fabien COELHO <coelho@cri.ensmp.fr> — 2019-07-10T07:51:49Z

    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.

  4. Re: make libpq documentation navigable between functions

    Peter Eisentraut <peter.eisentraut@2ndquadrant.com> — 2019-07-22T12:10:22Z

    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

  5. Re: make libpq documentation navigable between functions

    Fabien COELHO <coelho@cri.ensmp.fr> — 2019-07-22T20:56:15Z

    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.

  6. Re: make libpq documentation navigable between functions

    Peter Eisentraut <peter.eisentraut@2ndquadrant.com> — 2019-07-26T09:49:52Z

    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

  7. Re: make libpq documentation navigable between functions

    Fabien COELHO <coelho@cri.ensmp.fr> — 2019-07-26T10:28:45Z

    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.