From: Felipe Contreras <felipe.contreras@gmail.com>
To: Jeff King <peff@peff.net>, Felipe Contreras <felipe.contreras@gmail.com>
Cc: git@vger.kernel.org, "Junio C Hamano" <gitster@pobox.com>,
"Martin Ågren" <martin.agren@gmail.com>
Subject: Re: [PATCH] doc: remove custom callouts format
Date: Tue, 18 Apr 2023 03:50:15 -0600 [thread overview]
Message-ID: <643e67d71c0ae_21cdec29495@chronos.notmuch> (raw)
In-Reply-To: <20230418090310.GA414708@coredump.intra.peff.net>
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
prev parent reply other threads:[~2023-04-18 9:50 UTC|newest]
Thread overview: 9+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-04-18 1:18 [PATCH] doc: remove custom callouts format Felipe Contreras
2023-04-18 4:00 ` Jeff King
2023-04-18 4:41 ` Jeff King
2023-04-18 7:25 ` Felipe Contreras
2023-04-18 5:30 ` Felipe Contreras
2023-04-18 6:17 ` Jeff King
2023-04-18 7:15 ` Felipe Contreras
2023-04-18 9:03 ` Jeff King
2023-04-18 9:50 ` Felipe Contreras [this message]
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=643e67d71c0ae_21cdec29495@chronos.notmuch \
--to=felipe.contreras@gmail.com \
--cc=git@vger.kernel.org \
--cc=gitster@pobox.com \
--cc=martin.agren@gmail.com \
--cc=peff@peff.net \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).