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

[Felipe Contreras <felipe.contreras@gmail.com>]

Junio C Hamano wrote:
> 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