Re: [PATCH 0/4] A few Asciidoctor-fixes

From: Martin Ågren <martin.agren@gmail.com>
Date: Dec 16, 2018, 14:34 UTC
Message-ID: <CAN0heSrccWop+KRKFCTNHTB43XcAv+Q8X7p0hT1t2+rPjS1THA@mail.gmail.com>
In-Reply-To: <20181216104458.GC13704@sigill.intra.peff.net>

On Sun, 16 Dec 2018 at 11:45, Jeff King <peff@peff.net> wrote:

Show 8 quoted lines

>
> On Sat, Dec 15, 2018 at 12:27:38PM +0100, Martin Ågren wrote:
> I think the relevant bits from [1] are:
>
>  * Use `make --always-make ... install-man` in doc-diff.
>  * ./doc-diff -f HEAD HEAD # note -f
>  * Add empty commit and tweak config.mak
>  * ./doc-diff HEAD^ HEAD # note no -f

Yes, that's it.

Show 15 quoted lines

> To make this easier, it would make sense to me to:
>
>   - teach doc-diff a flag for marking one or both of the endpoints to be
>     built with asciidoctor versus asciidoc
>
>   - mark the asciidoc/asciidoctor in the directory name. That name
>     serves as a cache key for avoiding re-doing the work, you should be
>     able to just:
>
>       ./doc-diff --asciidoctor HEAD HEAD
>
>     and actually build and compare what you want.
>
>   - it sounds from "make --always-make" that our Makefile does not
>     properly rebuild when we switch from asciidoc to asciidoctor. That

Exactly.

>     might be nice to fix with a mechanism similar to the GIT-BUILD-FLAGS
>     we use in the top-level Makefile.

Agreed on all three points. The last one would supposedly be useful on its own, beyond this doc-diff motivation.

Your list seems complete to me in terms of "how could we teach doc-diff to diff asciidoctor vs asciidoc?". For the resulting diff to actually be useful ;-) there are two more outstanding issues that I see:

  - Headers and footers. Asciidoc (driven by doc-diff) uses some
    boilerplate values which avoid timestamps and the like. Asciidoctor
    partly uses different values, partly interprets the ones given
    differently.

  - Asciidoctor introduces a space after linkgit:foo , e.g., before
    punctuation.

Both of these are problems in their own right, so they probably shouldn't be suppressed in the resulting diff. But as long as these issues remain, they produce a lot of noise which might hide more interesting (IMHO) differences.

Martin