On Sun, 16 Dec 2018 at 11:45, Jeff King <peff@xxxxxxxx> 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