From: Jeff King <peff@peff.net>
Date: Thu, 10 Sep 2026 16:38:20 GMT
Subject: Re: [PATCH] doc: Make asciidoc bullet items separate
Message-ID: <20260910163820.GE251185@coredump.intra.peff.net>
In-Reply-To: <9f455224-f156-493f-a21c-27a8922f3360@app.fastmail.com>

On Mon, Sep 07, 2026 at 12:18:48PM +0200, Kristoffer Haugsbakk wrote:

> I wonder if this gives different results for asciidoc and asciidoctor.
> 
> • asciidoctor: seems that the bullet list is correct with or without
>   this change (no change)
> • asciidoc: needs this change

Yeah, I think we've run into this sort of parsing subtlety between the
two before.

I imagine this is how you did it, but for the original author and
anybody else working on documentation, it is often useful to do:

  cd Documentation
  ./doc-diff HEAD^ HEAD
  ./doc-diff --asciidoctor HEAD^ HEAD

to see how your changes work in both systems. You can also do:

  ./doc-diff --from-asciidoctor --to-asciidoc HEAD HEAD

to see how the two renderers differ currently, but there's quite a lot
of noise (differing wrapping, indentation, use of quotes, etc). All of
those may be candidates for examination and fixing, but it is a lot of
noise if you are looking at your one area. ;)

> I also idly wonder why git-scm renders this bullet list as it ought
> to. This hunk has not been modified for a while. The second paragraph
> which ostensibly made it conjoined was d9bccf2e (builtin/maintenance:
> introduce "geometric" strategy, 2025-10-24).

It uses asciidoctor. :)

-Peff