Re: [PATCH] doc: remove custom callouts format

[Jeff King <peff@peff.net>]

On Mon, Apr 17, 2023 at 11:30:18PM -0600, Felipe Contreras wrote:

> If we do this then the parser has no trouble understanding what we are trying
> to do:
> 
>   --- a/Documentation/git-checkout.txt
>   +++ b/Documentation/git-checkout.txt
>   @@ -523,36 +523,37 @@ EXAMPLES
>      the `Makefile` to two revisions back, deletes `hello.c` by
>      mistake, and gets it back from the index.
>    +
>   +--
>    ------------
>    $ git checkout master             <1>
>    $ git checkout master~2 Makefile  <2>
>    $ rm -f hello.c
>    $ git checkout hello.c            <3>
>    ------------
>   -+
>    <1> switch branch
>    <2> take a file out of another commit
>    <3> restore `hello.c` from the index
>   -+

Ah, that makes sense. I tried something like this, but asciidoc was
unhappy with the "+" continuation between the example and the callout
inside the block (which makes sense as there is no "list" to continue
within that block).

Just putting the example and its callouts in a block is sufficient, but
I agree that putting all of the "The following sequence..." list item's
content into a single block makes the source easier to read.

> I don't see why we insist on creating such complex list items though.
> 
> Creating a subsection is much clearer for everyone: the reader, the writer, and
> the parser:

Unless the subsection has a meaningful title, the formatting of the
result looks a bit odd to me:

  EXAMPLES
     1
         The following sequence checks out the master branch, reverts
         the Makefile to two revisions back, deletes hello.c by mistake,
         and gets it back from the index.

as opposed to:

          1. The following sequence checks out the master branch,
             reverts the Makefile to two revisions back, deletes hello.c
             by mistake, and gets it back from the index.

If each example had a short section title, it would make more sense.

At any rate, IMHO it is probably best to start with purely syntactic
fixes that don't change the output, as that is uncontroversial and
addresses the issue with your original patch (which is otherwise making
most spots look nicer). And then any conversation about sections versus
lists can proceed independently.

> > It's probably still worth moving forward with your patch, as I think it
> > takes us in the direction we want long-term (and which builds with
> > asciidoctor are already using). But we may want to pair it with a patch
> > to work around the issue with git-checkout.1 using asciidoc to avoid
> > regressing that section. It may require re-wording or re-organizing to
> > work around the bug.
> 
> I can add that patch depending what we want:
> 
> Open block:
> 
>   1. foo
>   +
>   --
>   bar
> 
>   roo
>   --
> 
> Or subsection:
> 
>   === 1
> 
>   foo
> 
>   bar
> 
>   roo

So I'd prefer the open block.

-Peff