On Sun, 16 Dec 2018 at 11:45, Jeff King <[email protected]> wrote:
>
> 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.
> 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
