Jeff King wrote:
> 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.
To me it's the exact opposite: it's odd that the whole example is indented,
when it's part of the main content.
I prefer the example to be indented at the same level as all the other text.
Also, because I use manpage color trick, the subsection header "1" is rendered
in red, while the list number is not. It's odd that even the callout numbers
inside the example are highlighted in red, but not the number of the example.
> If each example had a short section title, it would make more sense.
I don't particularly mind, but if you think that's a requirement, then why not
add that?
I sent a patch series doing precisely t hat.
> 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.
But the syntactic fixes changes the output.
Have you looked at the HTML output with asciidoc-py? It has the same
indentation problem you spotted in the manpages.
I don't see it in git-scm.com, but I presume that documentation there is
generated with asciidoctor.
> > > 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.
What if I add a proper title?
=== 2. Merge
Another advantage is that we can link directly to the subsection in HTML:
git-checkout.html#_2_merge
It's not something that's probably going to be used in practice, but to me it
makes total semantic sense to have big chunks of prose in a section of its own.
Having a huge list item on the other hand does not make sense, it would be like
having a list item that spans more than one page of a book.
Cheers.
--
Felipe Contreras
