Re: [PATCH] doc: remove custom callouts format

[Felipe Contreras <felipe.contreras@gmail.com>]

Jeff King wrote:
> 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).

Yeah, so the problem is already there and had nothing to do with my patch.

I sent a separate patch series to fix that _separate_ problem.

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

I think it helps that the examples are not indented to a level that no main
prose in the manpage is indented at.

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

Do we though?

Do you actually think the output of this command with a huge list item makes
semantic sense?

  (
    printf '1. '
    for x in $(seq 1 10000); do
      printf 'foo '
    done
    echo

    printf '2. bar\n'
  ) | asciidoctor - -o test.html


> But this is exactly why I suggested doing the syntactic fix first, rather
> than reorganizing.

The syntactic fix is--first of all--orthogonal to my patch.

And secondly: causes another glitch. So it doesn't seem like much of a fix,
more like a workaround in which we trade a big glitch for a small glitch.

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

I'm not sure it's a fix, but more relevantly: I'm not sure what that has to do
with my patch.

The fix for how we use asciidoc in git-checkout.txt can be implemented in a
totally separate patch series that has nothing to do with $subject.

Cheers.

-- 
Felipe Contreras