[0/4] A few Asciidoctor-fixes

Message

Martin Ågren Dec. 15, 2018, 11:27 a.m. UTC

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.

With each patch, I am giving one or a few URLs which show the current
Asciidoctor rendering at git-scm.com.

With Asciidoc, `doc-diff origin/master HEAD` reports that there is no
difference.

[1] https://public-inbox.org/git/[e-mail]/

Martin Ågren (4):
  git-column.txt: fix section header
  git-init.txt: do not nest open blocks
  rev-list-options.txt: do not nest open blocks
  git-status.txt: render tables correctly under Asciidoctor

 Documentation/git-column.txt       |   2 +-
 Documentation/git-init.txt         |   4 -
 Documentation/git-status.txt       | 162 +++++++++++++++--------------
 Documentation/rev-list-options.txt |   4 -
 4 files changed, 86 insertions(+), 86 deletions(-)

Comments

Jeff King Dec. 16, 2018, 10:44 a.m. UTC | #1

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

Martin Ågren Dec. 16, 2018, 2:34 p.m. UTC | #2

On Sun, 16 Dec 2018 at 11:45, Jeff King <[e-mail]> 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

Jeff King Dec. 16, 2018, 4:17 p.m. UTC | #3

On Sun, Dec 16, 2018 at 03:34:42PM +0100, Martin Ågren wrote:

> 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.

If there are a small number of distinct problems (that each have many
instances), I'm not opposed to having a mode to suppress them in the
resulting diff, so we can see the other problems more clearly.  Of
course, just fixing them is even better. ;)

The first one sounds like it may be a candidate for suppressing (i.e.,
it's not necessarily an actual problem).

-Peff