Web lists-archives.com

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




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