Thread: make libpq documentation navigable between functions
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.
Attachment
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.
Attachment
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
Attachment
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.
Attachment
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.