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
