Re: make libpq documentation navigable between functions
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.
Re: make libpq documentation navigable between functions
On 2019-07-22 22:56, Fabien COELHO wrote: > Attached script does, hopefully, the expected transformation. It adds ids > to 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
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 elements >> but *don't* put xreflabels on those. > > I understand that you mean turning function usages: > >PQbla > > into: > > > > so that it points to function definitions that would look like: > >PQbla... > > (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 , then use that. If not, then make an id on something else, most likely the element. What you have now puts ids on both the and the , which seems unnecessary and confusing. For some weird reason this setup with link targets in both and enclosed 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 >> >> >> >> 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 From 74509f28778c69bc2168925f0d0ca6fa935c9013 Mon Sep 17 00:00:00 2001 From: Peter Eisentraut Date: Mon, 22 Jul 2019 14:04:48 +0200 Subject: [PATCH] doc: Add support for xref to command and function elements --- doc/src/sgml/stylesheet-common.xsl | 11 +++ 1 file changed, 11 insertions(+) diff --git a/doc/src/sgml/stylesheet-common.xsl b/doc/src/sgml/stylesheet-common.xsl index 6d26e7e5c9..e148c9057f 100644 --- a/doc/src/sgml/stylesheet-common.xsl +++ b/doc/src/sgml/stylesheet-common.xsl @@ -86,4 +86,15 @@ ? + + + + + + + + + + + -- 2.22.0
Re: 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 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 and then we can control the output format of that. -- Peter Eisentraut http://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
