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

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

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.

The question was if this patch was done *purely* for the benefit of human
readers:

> > > Am I correct to understand that this patch is done purely for the benefit
> > > of human readers, and not for formatting machinery?

Even if the conclusion was that it was done primarily for the benefit of human
readers and secondarily for machine parsers (it shouldn't), that's still a
"no".

> > This discrepancy confused Jeff in [1].
> 
> And this is a good reason to add this change for humans.
> 
> > It's simply a good practice to follow the format asciidoctor documentation:
> 
> That one I would agree with 100%.

---

To draw a parallel with a situation the git dev community is much more familiar
with: we can think of asciidoc as the shell language. AsiiDoc is trying to be a
specified language [1], just like POSIX shell.

The fact that some syntax happens to work on all the *current* shells does not
mean it is specified, and it does not mean that it must work on future shells.

Similarly, the fact some asciidoc syntax happens to work on the current
transformers doesn't mean it will work on all future ones. Moreover,
transformers are not the only consideration, as text editors trying to parse
the same text also matter.

Not to mention blurry lines like human-like-machines like LLMs helping humans
with the code, and machine-like-humans because apparently the way I read the
asciidoc code is different than my fellow humans (I'm thinking of how a parser
could interpret it).

Either way, if the question was about *my* motivation for the patch, it was
just consistency, which helps both humans and machines.

Cheers.

[1] https://asciidoc-wg.eclipse.org/

-- 
Felipe Contreras