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

On Tue, 19 Mar 2019 at 04:55, Junio C Hamano [off-list ref] wrote:

Jeff King [off-list ref] writes:

quoted

So in my mind, the endgame is that we eventually drop asciidoc in favor
of asciidoctor. The repo at:

  https://github.com/asciidoc/asciidoc

says:

  NOTE: This implementation is written in Python 2, which EOLs in Jan
  2020. AsciiDoc development is being continued under @asciidoctor.

;-)

quoted

I'm not sure when is the right time to switch. If we can get the output
at parity, I don't think asciidoctor is too onerous to install (and we
don't have to worry about ancient platforms, as they can use
pre-formatted manpages).

One minor thing that bothers me abit is the continuity of the
pre-formatted pages when I switch to asciidoctor to update them.

I do not mind having to see a huge diff in the "git log -p" output
run in pre-formatted manpages and htmldocs repositories at the
boundary due to e.g. the differences how lines are broken or folded
between the formatters, but by the time we have to transition, the
efforts by you, Martin and friends to allow us compare the formatted
docs would have made the real differences to empty (or at least
negligible).  Knock knock...

This might be a good spot to provide a bit of current status on this.

The patch under discussion here and 185f9a0ea0 ("asciidoctor-extensions:
fix spurious space after linkgit", 2019-02-27), reduce the diff
between asciidoc and asciidoctor considerably. Let's assume for the
moment that these patches or something like them enter master...

There's one larger difference in git-checkout.txt which I'm staying away
from at the moment, since Duy is doing a lot of work there at the time.
(He's not making that asciidoc/tor issue any worse, and he's not
spreading it to say git-switch.txt, so I'd rather just not rush to it.)
Let's assume I get around to this soonish...

Let's also assume that `./doc-diff --cut-header-footer --from-asciidoc
--to-asciidoctor HEAD HEAD` enters master [1]. Then what remains is a
fairly small and understandable diff where most issues are "yeah, I
guess that looks nicer" or even "they're just as fine", rather than "oh
wow, that's ugly". (IMHO.)

Martin

[1] You could already now run it to diff "master master", but you'd
trip on the Makefile thinking there's nothing to do. That'd be fixed by
9a71722b4d ("Doc: auto-detect changed build flags", 2019-03-17).