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

From: Felipe Contreras <felipe.contreras@gmail.com>
Date: May 3, 2023, 13:46 UTC
Message-ID: <6452659e704df_682294b6@chronos.notmuch>
In-Reply-To: <xmqqpm7ivtd0.fsf@gitster.g>

Junio C Hamano wrote:

Show 19 quoted lines

> Jeff King <peff@peff.net> writes:
> 
> >> > 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).
> >> ...
> >  $ git checkout hello.cgit checkout hello.c            <3>
> >  ------------
> > -+
> > +
> >  <1> switch branch
> >  <2> take a file out of another commit
> >  <3> restore `hello.c` from the index
> >
> > which asciidoc renders the same, but asciidoctor is not.
> 
> Yet another random annoying differences that explains why we wrote
> it that way in the first place X-<.

I don't think so. This is the sequence of events:

 1. 1e2ccd3abc (Documentation: more examples., 2005-12-12)
 2. 1be0659efc (checkout: merge local modifications while switching branches., 2006-01-12)
 3. 48aeecdcc1 (Fix up remaining man pages that use asciidoc "callouts"., 2006-04-28)

In 1 "callouts" were added inside the listing itself, so they were not actually callouts, the space was added just for formatting. In 2 other examples were added, which transformed the original example to a list element, and everything was peppered with `+`. Finally in 3 the code was transformed to actual AsciiDoc callouts, which meant that the original space that previously was protected inside a listing block would not be protected anymore, so it could either be 1) removed or 2) converted to `+`.

In the thread that added this `+` [1] I see no discussion about the alternatives.

At no point did anyone consider using a newline inside a list element, because spaces inside list elements don't work, so the actual two choices were:

A:

  ----
  line 1 <1>
  ----
  <1> callout 1

B:

  ----
  line 1 <1>
  ----
  +
  <1> callout 1

And there never was any actual reason given as to why B was "chosen".

I think the reality is most of the AsciiDoc code doesn't really have any consideration as to what is the actual AsciiDoc syntax, it's there because it seems to work, and that's it.

So I think the real reason is that a newline was there before, and newlines stop list elements.

It couldn't have possibly been because a newline didn't work in asciidoctor, because asciidoctor would not have been created for another 6 years.

> If it has been removed to make it not to matter, that was lucky of us ;-)

Only if following the actual syntax of a language is considered "luck", in the same way that it's "lucky" that following the C specification makes C code work on most C compilers.

[1] https://lore.kernel.org/git/BAYC1-PASMTP028F5C1C39F7EF6A6EEB95AEB20@CEZ.ICE/

-- 
Felipe Contreras