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

[Jeff King <peff@peff.net>]

On Sat, Sep 07, 2019 at 04:06:48PM +0200, Martin Ågren wrote:

> So of these steps:
> 
>   0. Get Asciidoctor (v1) in shape.
> 
>   1. Switch the default to Asciidoctor (v1).
> 
>   2. Drop AsciiDoc to have faster Asciidoctor-processing, avoid xmlto
>      and support Asciidoctor 2. And to avoid the Python 2 EOL, too.
> 
> Step 0 is not far away, so step 1 could be done fairly soon IMHO. Step 2
> would "hopefully" happen soon after -- maybe even in the same release
> cycle as step 1, and if not the same then the one just after. But I
> might be the wrong person to trust on that one. I currently don't even
> try to build with Asciidoctor 2. I might perhaps look into installing
> it, but it could also be that I'll only start using it when it happens
> to arrive through my distro.
> 
> So as long as I'm not looking into Asciidoctor 2, maybe I shouldn't be
> the one to impose "default to asciidoctor" on the world. Dunno. In any
> case, I should be able to bring the asciidoc/tor1 differences to a state
> where we trust asciidoctor 1 to be in a good shape, so that "someone
> else" could pick up the ball and work on asciidoctor 2 vs 1, knowing
> that it's ok if they regress AsciiDoc support or even drop it entirely
> in the process.

We could also drop xmlto for the asciidoctor codepaths, without making
it the default. That requires a little bit more Makefile massaging, but
here's a hacky way to do it (this is on top of brian's asciidoctor 2
patch, which I've been experimenting with, but obviously we could skip
that entirely, too):

---
diff --git a/Documentation/Makefile b/Documentation/Makefile
index 485f365cbf..c3ebca6e36 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -197,12 +197,12 @@ ifdef USE_ASCIIDOCTOR
 ASCIIDOC = asciidoctor
 ASCIIDOC_CONF =
 ASCIIDOC_HTML = xhtml5
-ASCIIDOC_DOCBOOK = docbook5
+ASCIIDOC_DOCBOOK = manpage
 ASCIIDOC_EXTRA += -acompat-mode -atabsize=8
 ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions
 ASCIIDOC_EXTRA += -alitdd='&\#x2d;&\#x2d;'
 DBLATEX_COMMON =
-XMLTO_EXTRA += --skip-validation
+XMLTO = ./fake-xmlto
 endif
 
 SHELL_PATH ?= $(SHELL)
diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
index 4ae130d2c6..aae891e8ff 100644
--- a/Documentation/asciidoctor-extensions.rb
+++ b/Documentation/asciidoctor-extensions.rb
@@ -17,6 +17,8 @@ module Git
             "<refentrytitle>#{target}</refentrytitle>" \
             "<manvolnum>#{attrs[1]}</manvolnum>\n" \
           "</citerefentry>"
+        elsif parent.document.basebackend? 'manpage'
+          "#{target}(#{attrs[1]})"
         end
       end
     end
diff --git a/Documentation/fake-xmlto b/Documentation/fake-xmlto
new file mode 100755
index 0000000000..eca7ba289d
--- /dev/null
+++ b/Documentation/fake-xmlto
@@ -0,0 +1,9 @@
+#!/bin/sh
+
+# pick last arg as file
+for file in "$@"; do
+  : nothing
+done
+
+nr=$(perl -lne '/^\.TH ".*?" "(\d)"/ and print $1' $file)
+cp $file ${file%.xml}.$nr
-- 
2.23.0.554.g6dbe768f61


That's enough to let you do:

  ./doc-diff --from-asciidoc --to-asciidoctor HEAD^ HEAD

and see what jumping to direct-manpage generation would look like. After
applying all of your recent patches, I see some improvements. E.g.:

  -           Files to add content from. Fileglobs (e.g.  *.c) can be given to
  +           Files to add content from. Fileglobs (e.g. *.c) can be given to add

and some regressions:

  -           of nothing). The other file, git-add--interactive.perl, has 403
  +           of nothing). The other file, git-add&#x2d;&#x2d;interactive.perl,

There's also a lot of noise. One curiosity is that it refuses to break
linkgit output when wrapping:

  -           Remove everything in body before a scissors line (see git-
  -           mailinfo(1)). Can be activated by default using the
  +           Remove everything in body before a scissors line (see
  +           git-mailinfo(1)). Can be activated by default using the

I think that's fine (and probably even better), but it makes the
doc-diff quite hard to read. ;) Setting MANWIDTH=1000 in doc-diff is a
hacky way to eliminate these, but I'm not sure it's a good idea in
general.

-Peff