Re: [PATCH] doc: remove custom callouts format

From: Jeff King <peff@peff.net>
Date: Apr 18, 2023, 06:17 UTC
Message-ID: <20230418061713.GA169940@coredump.intra.peff.net>
In-Reply-To: <643e2aeae0515_217cdb29473@chronos.notmuch>

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

Show 21 quoted lines

> 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.

Show 28 quoted lines

> > 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