Re: [PATCH] doc: remove custom callouts format

From: Jeff King <peff@peff.net>
Date: Apr 18, 2023, 04:41 UTC
Message-ID: <20230418044142.GA130759@coredump.intra.peff.net>
In-Reply-To: <20230418040034.GC60552@coredump.intra.peff.net>

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

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

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