[PATCH v3 2/3] asciidoctor-extensions: provide `<refmiscinfo/>`

As can be seen from the previous commit, there are three attributes that we provide to AsciiDoc through asciidoc.conf. Asciidoctor ignores that file. After that patch, newer versions of Asciidoctor pick up the `manmanual` and `mansource` attributes as we invoke `asciidoctor`, but they don't pick up `manversion`. ([1] says: "Not used by Asciidoctor.") Older versions (<1.5.7) don't handle these attributes at all. As a result, we are missing one or three `<refmiscinfo/>` tags in each xml-file produced when we build with Asciidoctor.

Because of this, xmlto doesn't include the Git version number in the rendered manpages. And in particular, with versions <1.5.7, the manpage footers instead contain the fairly ugly "[FIXME: source]".

That Asciidoctor ignores asciidoc.conf is nothing new. This is why we implement the `linkgit:` macro in asciidoc.conf *and* in asciidoctor-extensions.rb. Follow suit and provide these tags in asciidoctor-extensions.rb, using a "postprocessor" extension where we just search and replace in the XML, treated as text.

We may consider a few alternatives:

  * Inject these lines into the xml-files from the *Makefile*, e.g.,
    using `sed`. That would reduce repetition, but it feels wrong to
    impose another step and another risk on the AsciiDoc-processing only
    to benefit the Asciidoctor-one.

  * I tried providing a "docinfo processor" to inject these tags, but
    could not figure out how to "merge" the two <refmeta/> sections that
    resulted. To avoid xmlto barfing on the result, I needed to use
    `xmlto --skip-validation ...`, which seems unfortunate.

Let's instead inject the missing tags using a postprocessor. We'll make it fairly obvious that we aim to inject the exact same three lines of `<refmiscinfo/>` that asciidoc.conf provides. We inject them in *post*-processing so we need to do the variable expansion ourselves. We do introduce the bug that asciidoc.conf already has in that we won't do any escaping, e.g., of funky versions like "some v <2.25, >2.20".

The postprocessor we add here works on the XML as raw text and doesn't really use the full potential of XML to do a more structured injection. This is actually precisely what the Asciidoctor User Manual does in its postprocessor example [2]. I looked into two other approaches:

  1. The nokogiri library is apparently the "modern" way of doing XML
     in ruby. I got it working fairly easily:
        require 'nokogiri'
        doc = Nokogiri::XML(output)
        doc.search("refmeta").each { |n| n.add_child(new_tags) }
        output = doc.to_xml
     However, this adds another dependency (e.g., the "ruby-nokogiri"
     package on Ubuntu). Using Asciidoctor is not our default, but it
     will probably need to become so soon. Let's avoid adding a
     dependency just so that we can say "search...add_child" rather than
     "sub(regex...)".

  2. The older REXML is apparently always(?) bundled with ruby, but I
     couldn't even parse the original document:
        require 'rexml/document'
        doc = REXML::Document.new(output)
        ...
     The error was "no implicit conversion of nil into String" and I
     stopped there.

I don't think it's unlikely that doing a plain old search-and-replace will work just as fine or better compared to parsing XML and worrying about libraries and library versions.

[1] https://asciidoctor.org/docs/user-manual/#builtin-attributes

[2] https://asciidoctor.org/docs/user-manual/#postprocessor-example

Signed-off-by: Martin Ågren <martin.agren@gmail.com>
---
 Documentation/asciidoctor-extensions.rb | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)