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

From: Felipe Contreras <felipe.contreras@gmail.com>
Date: Apr 24, 2023, 13:28 UTC
Message-ID: <644684018a766_aba29424@chronos.notmuch>
In-Reply-To: <xmqq8ren8xz1.fsf@gitster.g>

Junio C Hamano wrote:

Show 15 quoted lines

> Felipe Contreras <felipe.contreras@gmail.com> writes:
> 
> > The callouts are directly tied to the listing above, remove spaces to
> > make it clear they are one and the same.
> >
> > Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
> > ---
> >  Documentation/git-checkout.txt | 4 ----
> >  1 file changed, 4 deletions(-)
> 
> I tried to format git-checkout.1 and git-checkout.html from HEAD and
> HEAD^ after applying this step, with asciidoc and asciidoctor, and
> did not see any difference that came from this patch.  Am I correct
> to understand that this patch is done purely for the benefit of
> human readers, and not for formatting machinery?

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.

This works:

  1. item
  +
  ----
  line 1 <1>
  ----
  +
  <1> callout 1

But if we used an open block instead (which is more propper), this does not:

  1. item
  +
  --
  ----
  line 1 <1>
  ----
  +
  <1> callout 1
  --

This discrepancy confused Jeff in [1].

[1] https://lore.kernel.org/git/20230418061713.GA169940@coredump.intra.peff.net/

> It may be subjective for those who read the source if it is easier
> to read with or without inter-paragraph spaces, but in any case, the
> resulting source material now look the same way between two hunks,
> and consistency is good.

That is an added benefit.

It's simply a good practice to follow the format asciidoctor documentation: which doesn't contain spaces, doesn't require adding list continations, it's easier to interpret by the parsers, and works inside open blocks.

-- 
Felipe Contreras