Re: [PATCH] asciidoctor-extensions: provide `<refmiscinfo/>`

[Todd Zullinger <tmz@pobox.com>]

Hi Martin,

Martin Ågren wrote:
> 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.

Nice!  I looked at this a long time ago and didn't figure
out how to use a postprocessor extension.  From my notes, I
found discussions about using ruby's tilt for templating and
it all seemed way too convoluted.

Your method looks quite simple and elegant.

> 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.

I played with this direction before.  Using Asciidoctor we
can convert directly from .txt to man without docbook
and xmlto.  That does have some other issues which need to
be worked out though.  Here's what I had as a start:

-- 8< --
Subject: [PATCH] WIP: doc: improve asciidoctor manpage generation

Avoid 'FIXME: Source' by setting mansource.  Skip xmlto step and render
manpages directly with asciidoctor.

TODO:
    - apply to all man pages
    - fix links to html docs, like user-manual.html in git.1 (currently
      it is listed in brackets inline rather than as a footnote)

Reference:
https://lore.kernel.org/lkml/20180424150456.17353-1-tiwai@suse.de/
Signed-off-by: Todd Zullinger <tmz@pobox.com>
---
 Documentation/Makefile                  | 8 ++++++++
 Documentation/asciidoctor-extensions.rb | 2 ++
 2 files changed, 10 insertions(+)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index a9697f5146..494f8c9464 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -197,6 +197,7 @@ ASCIIDOC_DOCBOOK = docbook45
 ASCIIDOC_EXTRA += -acompat-mode -atabsize=8
 ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions
 ASCIIDOC_EXTRA += -alitdd='&\#x2d;&\#x2d;'
+ASCIIDOC_EXTRA += -a mansource="Git $(GIT_VERSION)" -a manmanual="Git Manual"
 DBLATEX_COMMON =
 endif
 
@@ -354,9 +355,16 @@ $(OBSOLETE_HTML): %.html : %.txto asciidoc.conf
 manpage-base-url.xsl: manpage-base-url.xsl.in
 	$(QUIET_GEN)sed "s|@@MAN_BASE_URL@@|$(MAN_BASE_URL)|" $< > $@
 
+ifndef USE_ASCIIDOCTOR
 %.1 %.5 %.7 : %.xml manpage-base-url.xsl $(wildcard manpage*.xsl)
 	$(QUIET_XMLTO)$(RM) $@ && \
 	$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<
+else
+%.1 %.5 %.7 : %.txt
+	$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
+	$(ASCIIDOC_COMMON) -b manpage -d manpage -o $@+ $< && \
+	mv $@+ $@
+endif
 
 %.xml : %.txt asciidoc.conf asciidoctor-extensions.rb
 	$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
index f7a5982f8b..ebb078807a 100644
--- a/Documentation/asciidoctor-extensions.rb
+++ b/Documentation/asciidoctor-extensions.rb
@@ -12,6 +12,8 @@ module Git
         if parent.document.basebackend? 'html'
           prefix = parent.document.attr('git-relative-html-prefix')
           %(<a href="#{prefix}#{target}.html">#{target}(#{attrs[1]})</a>\n)
+        elsif parent.document.basebackend? 'manpage'
+          "#{target}(#{attrs[1]})"
         elsif parent.document.basebackend? 'docbook'
           "<citerefentry>\n" \
             "<refentrytitle>#{target}</refentrytitle>" \
-- 8< --

That was based on ma/asciidoctor-extensions, but it may be
missing other recent improvements you've made to the make
targets.  It's been a month or so since I worked on it.

I munged up doc-diff to set MANDWIDTH=1000 and set one
branch to default to asciidoctor to compare.  (Your other
recent series looks like it'll make doing asciidoc and
asciidoctor comparisons easier.)

There were a number of differences that I didn't work
through though.  Most importantly was the change in the
links noted in the commit message.

Thanks for working on asciidoctor.  I've been trying to poke
it off and on to help ensure the docs can be built if
asciidoc ever gets dropped from Fedora.

-- 
Todd