Re: [PATCH] doc: remove custom callouts format

From: Jeff King <peff@peff.net>
Date: Apr 18, 2023, 09:03 UTC
Message-ID: <20230418090310.GA414708@coredump.intra.peff.net>
In-Reply-To: <643e43824a220_21b043294f8@chronos.notmuch>

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

Show 5 quoted lines

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

Show 5 quoted lines

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

Show 5 quoted lines

> 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