When we build with AsciiDoc, asciidoc.conf ensures that each xml-file we
generate contains some meta-information which `xmlto` can act on, based
on the following template:
<refmeta>
<refentrytitle>{mantitle}</refentrytitle>
<manvolnum>{manvolnum}</manvolnum>
<refmiscinfo class="source">Git</refmiscinfo>
<refmiscinfo class="version">{git_version}</refmiscinfo>
<refmiscinfo class="manual">Git Manual</refmiscinfo>
</refmeta>
When we build with Asciidoctor, it does not honor this configuration file
and we end up with only this (for a hypothetical git-foo.xml):
<refmeta>
<refentrytitle>git-foo</refentrytitle>
<manvolnum>1</manvolnum>
</refmeta>
That is, we miss out on the `<refmiscinfo/>` tags. As a result, the
header of each man page doesn't say "Git Manual", but "git-foo(1)"
instead. Worse, the footers don't give the Git version number and
instead provide 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.
We may consider a few alternatives:
* Provide the `mansource` attribute to Asciidoctor. This attribute
looks promising until one realizes that it can only be given inside
the source file (the .txt file in our case), *not* on the command
line using `-a mansource=foobar`. I toyed with the idea of injecting
this attribute while feeding Asciidoctor the input on stdin, but it
didn't feel like it was worth the complexity in the Makefile.
* Similar to that last idea, we could inject these lines into the
xml-files from the Makefile, e.g., using `sed`. This reduces
repetition, but seems fairly brittle. It feels wrong to impose
another step and another risk on the Asciidoc-processing only to
benefit the Asciidoctor-one.
* Considering the above abandoned ideas, it seems better to put any
complexity inside asciidoctor-extensions.rb. It is after all
supposed to be the "equivalent" of asciidoc.conf. I considered
providing a "tree processor" extension and use it to set, e.g.,
`mansource` mentioned above.
Let's instead try to stay as close as possible to what asciidoc.conf
does. We'll make it fairly obvious that we aim to inject the exact same
three lines of `<refmiscinfo/>` that asciidoc.conf provides. The only
somewhat tricky part is that we inject them *post*-processing so we need
to do the variable expansion ourselves.
Signed-off-by: Martin Ågren <martin.agren@xxxxxxxxx>
---
Cc Todd and Peff who had a brief exchange [1] a while ago. Apparently
Todd saw this "[FIXME: source]" on Fedora but Peff did not on Debian.
I'm on Ubuntu 18.04 and used to see this also on 16.04. I'm not sure
what might make Debian so special here.
[1] https://public-inbox.org/git/20180627164443.GK20217@xxxxxxxxxxxxxxxxxxxx/
I've based this on ma/asciidoctor-fixes, not because it's needed for
the patch itself, but because it provides a15ef383e7
("Documentation/Makefile: add missing dependency on
asciidoctor-extensions", 2019-02-27), which ensures that the
documentation will be rebuilt. I'm hoping this was the right call.
Documentation/asciidoctor-extensions.rb | 16 ++++++++++++++++
1 file changed, 16 insertions(+)
diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
index 0089e0cfb8..059279dee1 100644
--- a/Documentation/asciidoctor-extensions.rb
+++ b/Documentation/asciidoctor-extensions.rb
@@ -20,9 +20,25 @@ module Git
end
end
end
+
+ class DocumentPostProcessor < Asciidoctor::Extensions::Postprocessor
+ def process document, output
+ if document.basebackend? 'docbook'
+ git_version = document.attributes['git_version']
+ replacement = "" \
+ "<refmiscinfo class=\"source\">Git</refmiscinfo>\n" \
+ "<refmiscinfo class=\"version\">#{git_version}</refmiscinfo>\n" \
+ "<refmiscinfo class=\"manual\">Git Manual</refmiscinfo>\n" \
+ "<\/refmeta>"
+ output = output.sub(/<\/refmeta>/, replacement)
+ end
+ output
+ end
+ end
end
end
Asciidoctor::Extensions.register do
inline_macro Git::Documentation::LinkGitProcessor, :linkgit
+ postprocessor Git::Documentation::DocumentPostProcessor
end
--
2.21.0
