[knot-resolver-users] [PATCH 0/2] Generate Info manual

These two patches modify Knot Resolver's build process to check for Texinfo utilities during configuration and, if they're found, to build and install documentation in Info format (the standard for GNU distributions such as Guix[0]) as well as HTML. (If the Texinfo utilities aren't found, the build works as before.) The first patch implements these changes and additionally updates the manual to list Texinfo as an optional dependency. The second patch isn't required but genericizes a few references within the manual to documentation in specific formats, in the interest of readability. Note I've left unchanged the "build-html-doc" ref-ID to help ensure external links to the documentation continue to function. [0] https://guix.gnu.org/ ---------- With these patches applied you'll find makeinfo generates a large number of warnings of the form knotresolver.texi:11811: warning: @anchor should not appear in @deffn These warnings are harmless but result from the way Breathe processes C declarations. It generates output with this structure (here for the "kr_request_selected" macro): <desc_signature ids="c.kr_request_selected" is_multiline="True"> <desc_signature_line add_permalink="True" xml:space="preserve"> <target ids="resolve_8h_1a9ba8c6cef807cdf580e3249675a2589c" names="resolve_8h_1a9ba8c6cef807cdf580e3249675a2589c"></target> <desc_name xml:space="preserve">kr_request_selected</desc_name> <desc_parameterlist xml:space="preserve"> <desc_parameter noemph="True" xml:space="preserve"><emphasis>req</emphasis></desc_parameter> </desc_parameterlist> </desc_signature_line> </desc_signature> The issue is the "target" node's being placed within desc_signature_line. I assume this is done for convenience when generating HTML, but it also leads to this Texinfo output: @deffn {Define} @anchor{lib resolve_8h_1a9ba8c6cef807cdf580e3249675a2589c}@anchor{25f}kr_request_selected (req) which is invalid, since (as the warning says) @anchor is not supposed to appear within @deffn. Sphinx's Texinfo writer doesn't account for this, since there's no way (that I can see) for normal ReST input to generate a "target" tag in this position. However it's not clear Breathe is at fault here either, since I can't find anything that defines where target is allowed to appear or which tags desc_signature_line is meant to contain. A straightforward approach to fixing this is implemented by this patch to Sphinx, which causes its Texinfo writer to reorder target nodes embedded within function descriptions: diff --git a/sphinx/writers/texinfo.py b/sphinx/writers/texinfo.py index 5ad2831dd..bd76acdc3 100644 --- a/sphinx/writers/texinfo.py +++ b/sphinx/writers/texinfo.py @@ -1383,6 +1383,11 @@ class TexinfoTranslator(SphinxTranslator): if objtype != 'describe': for id in node.get('ids'): self.add_anchor(id, node) + # embedded anchors need to go in front + for n in node.traverse(nodes.target, include_self=False): + if isinstance(n, nodes.target): + n.walkabout(self) + n.parent.remove(n) # use the full name of the objtype for the category try: domain = self.builder.env.get_domain(node.parent['domain']) However, whether this is the correct approach or if a fix would better be applied to Breathe isn't clear to me. Engaging with the community of either project means signing up for services I'd rather not use, so there's little I can do to carry this forward. Perhaps someone else is interested? --- Simon South simon(a)simonsouth.net Simon South (2): doc: generate Info manual doc: use non-format-specific references to documentation doc/build.rst | 11 +++++++---- doc/meson.build | 7 +++++++ scripts/install-doc-info.sh | 8 ++++++++ scripts/make-doc.sh | 6 ++++++ 4 files changed, 28 insertions(+), 4 deletions(-) create mode 100644 scripts/install-doc-info.sh -- 2.28.0