Re: [PATCH] doc: remove custom callouts format

[Jeff King <peff@peff.net>]

On Tue, Apr 18, 2023 at 12:00:34AM -0400, Jeff King wrote:

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

Just to clarify my comment on asciidoctor: since our Makefile will put
its output through docbook, too, it actually is using the xsl you're
removing here (though I'm unclear on why its output looks good in
general even before your patch).

But the problem with git-checkout.1 in particular is that the XML
generated by asciidoc does not close the <calloutlist> at the right spot
(it sticks the continuation onto the calloutlist), whereas asciidoctor
does it right (it closes the calloutlist after item 3).

I had tried putting an open block around the whole example and callout
list before, which asciidoc doesn't like. But doing it just around the
callout list, like so:

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 6bb32ab460..bd83a6e5d2 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -530,9 +530,11 @@ $ 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
+--
 +
 If you want to check out _all_ C source files out of the index,
 you can say

seems to improve things. The generated XML looks sensible, and the
output looks like asciidoctor's, though unfortunately both omit the
blank line between the end of the callout list and the next paragraph.
That might be good enough to live with.

-Peff