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

From: Jeff King <peff@peff.net>
Date: Dec 16, 2018, 10:44 UTC
Message-ID: <20181216104458.GC13704@sigill.intra.peff.net>
In-Reply-To: <20181215112742.1475882-1-martin.agren@gmail.com>

On Sat, Dec 15, 2018 at 12:27:38PM +0100, Martin Ågren wrote:

> I have (ab)used doc-diff to try to find instances where Asciidoctor and
> Asciidoc render our documentation differently. (See [1] for details on
> the hack.) This series fixes the differences that somehow stood out in
> the diff. Many smaller differences remain.

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

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
    might be nice to fix with a mechanism similar to the GIT-BUILD-FLAGS
    we use in the top-level Makefile.

-Peff