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

[Jeff King <peff@peff.net>]

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

> 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