Re: [PATCH 1/2] doc: git-checkout: trivial callout cleanup

From: Jeff King <peff@peff.net>
Date: Apr 25, 2023, 06:10 UTC
Message-ID: <20230425061029.GA4015844@coredump.intra.peff.net>
In-Reply-To: <xmqq8reg96cu.fsf@gitster.g>

On Mon, Apr 24, 2023 at 05:02:25PM -0700, Junio C Hamano wrote:

Show 18 quoted lines

> Felipe Contreras <felipe.contreras@gmail.com> writes:
> 
> > No, it's for the formatting machinery.
> >
> > The fact that both asciidoc and asciidoctor happen to understand our quircky
> > formatting in this particualr situation doesn't mean it isn't quirky.
> >
> > In this particular case the parsers do understand what we are trying to do,
> > because we just just pepper list continuations (`+`) everywhere and it happens
> > to work.
> 
> I'll stop at pointing out that the first "no" sounds much stronger
> than the text that tries to substantiate it, which says that the
> machinery works fine without the changes.
> 
> > This discrepancy confused Jeff in [1].
> 
> And this is a good reason to add this change for humans.

Since I'm being used as the example, I'd like to point that I think this is somewhat tangential to what actually confused me there.

What confused me in that earlier message was that having "+" as the continuation between a code-block and its call-out list is odd, since "+" is about continuing a list item. It happens to work because we're in a larger list item, but it breaks when you put the two of them in their own block (which is the part that got me).

Using just a blank line between the code block and the call-out list (instead of the "+") works for asciidoc (it is happy to keep the two together) but not asciidoctor (it ends the outer ordered list before starting the callout list).

So the second hunk in the patch, to drop the extra continuation between the code block and the callout, makes perfect sense to me.

The first hunk seems less obviously good to me. We're not part of a list, so there's no continuation. We might say that it is good to always stick the callout list directly adjacent to the associated code block, since it does matter in other cases. But dropping the blank lines between the paragraph-sized callout blocks makes the source less readable, and empty lines between list elements are a pretty normal thing in asciidoc.

That said, I don't feel _too_ strongly about it, so I'm OK with the patch as-is.

-Peff