New subject: [PATCH 1/2] doc: generate Info manual

10 Říj 2020

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

[PATCH 0/2] Generate Info manual