Re: [PATCH] doc: remove custom callouts format

[Jeff King <peff@peff.net>]

On Tue, Apr 18, 2023 at 01:15:14AM -0600, Felipe Contreras wrote:

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

I hadn't looked at it, but yeah, I see it has the same issue. That makes
sense, since the XML output from asciidoc was wrong (and our xslt was
papering over it for the manpage build).

And yes, the pages no git-scm.com are built with asciidoctor.

> > So I'd prefer the open block.
> 
> What if I add a proper title?
> 
>     === 2. Merge

From the perspective of somebody skimming through the examples, that
doesn't seem to help much. But I'm not sure if there _is_ a succinct and
descriptive title for each of those examples (or at least I could not
easily come up with one, which is why I didn't offer a suggestion).

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

We may have to agree to disagree on that. But this is exactly why I
suggested doing the syntactic fix first, rather than reorganizing. Once
the fix is done, then there can be a separate discussion on reorganizing
(which, frankly, I don't really have much interest in either way; I gave
my opinion and I don't have anything else to say).

-Peff