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

["Martin Ågren" <martin.agren@gmail.com>]

On Tue, 19 Mar 2019 at 04:55, Junio C Hamano <gitster@pobox.com> wrote:
>
> Jeff King <peff@peff.net> writes:
>
> > 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.
>
> ;-)
>
> > 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).