From: "Martin Ågren" <martin.agren@gmail.com>
To: Jeff King <peff@peff.net>
Cc: "brian m. carlson" <sandals@crustytoothpaste.net>,
Bagas Sanjaya <bagasdotme@gmail.com>,
Git Users <git@vger.kernel.org>
Subject: Re: [RFC suggestion] Generate manpage directly with Asciidoctor
Date: Tue, 11 May 2021 20:45:10 +0200 [thread overview]
Message-ID: <CAN0heSp6uw7yqNZLD5w13xJUgnUtgHM0OYw9KQ6Z-FKk+x4OPA@mail.gmail.com> (raw)
In-Reply-To: <YJmykGWaWi03+WoW@coredump.intra.peff.net>
On Tue, 11 May 2021 at 00:24, Jeff King <peff@peff.net> wrote:
>
> On Sun, May 09, 2021 at 10:20:37AM +0200, Martin Ågren wrote:
>
> > it was. So it's not so much "we should flip to avoid a bitrotting
> > dependency" as it is "asciidoctor is arguably nicer" or "it's the way
> > forward".
>
> I'm OK with those arguments, too. :)
Excellent. :)
> > When we looked at xmlto-less rendering around two years ago [1], we
> > found various asciidoctor bugs up to and around version 2.0. We would
> > likely need to require some >=2.0.x. The exact requirements will
> > probably only become clear when someone really does the work.
>
> That does make things a little less convenient; Debian stable, for
> instance, still has 1.5.8. It's not too hard to install an updated gem,
> but not quite as nice as using the system package (it also makes things
> weird for building the stable Debian package itself, which would want to
> rely only on other packages; but of course any proposed change to the
> doc toolchain would be for new versions, and would not get backported
> there anyway).
Right. And 1.5.8 is perfectly fine for ascidoctor *with* xmlto, i.e., as
long as we're discussing moving away from asciidoc, not moving away from
xmlto entirely. And soon enough, Debian stable should be at 2.12. ;-)
(I realize Debian stable was just an example.)
> > I think what I'm arguing for is
> >
> > 1) switch the default to asciidoctor,
> > 2) enable optionally using it without xmlto,
> > 3) figure out what broke and fix it, and document which is the minimum
> > asciidoctor version we're going to bother with for (2),
> > 4) lather, rinse, repeat (3),
> > 5) switch the default to not using xmlto,
> > 6) drop the xmlto way of generating the manpages(?).
>
> I'm unclear when support for python asciidoc goes away here. Is it part
> of step 6 (because it does not have another way of generating them)? Or
> does it live on forever as a non-default legacy system? I'd prefer not,
> but as long as we are clear about the primary target and leave it up to
> people interested in the legacy to do the compat fixes, that might be
> OK.
I think I meant it to happen somewhere in step 3 or 4, I just didn't
call it out. If it happens super-early in step 3, that would perhaps be
a bit unfortunate. But if fixing up the last few bits of
xmlto-vs-no-xmlto with asciidoctor involves giving up on asciidoc, then
so be it... If nothing else, we might all of a sudden find that our
asciidoc-processed docs look awful and that nobody seems to have
noticed.
Martin
next prev parent reply other threads:[~2021-05-11 18:45 UTC|newest]
Thread overview: 38+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-05-07 6:06 [RFC suggestion] Generate manpage directly with Asciidoctor Bagas Sanjaya
2021-05-07 12:02 ` Randall S. Becker
2021-05-07 22:55 ` Felipe Contreras
2021-05-07 22:57 ` brian m. carlson
2021-05-08 1:42 ` Randall S. Becker
2021-05-07 12:27 ` Đoàn Trần Công Danh
2021-05-07 12:47 ` Bagas Sanjaya
2021-05-07 23:03 ` Felipe Contreras
2021-05-08 4:27 ` Bagas Sanjaya
2021-05-07 20:25 ` brian m. carlson
2021-05-07 22:19 ` Jeff King
2021-05-08 4:22 ` Bagas Sanjaya
2021-05-09 8:20 ` Martin Ågren
2021-05-09 18:46 ` Felipe Contreras
2021-05-10 18:43 ` Martin Ågren
2021-05-10 22:24 ` Jeff King
2021-05-11 4:27 ` Felipe Contreras
2021-05-11 6:13 ` Jeff King
2021-05-11 8:03 ` Felipe Contreras
2021-05-11 12:44 ` Ævar Arnfjörð Bjarmason
2021-05-11 19:00 ` Felipe Contreras
2021-05-11 19:09 ` Jeff King
2021-05-11 20:22 ` Felipe Contreras
2021-05-11 23:14 ` brian m. carlson
2021-05-12 1:44 ` Felipe Contreras
2021-05-11 18:45 ` Martin Ågren [this message]
2021-05-11 19:07 ` Jeff King
2021-05-11 19:11 ` Martin Ågren
2021-05-11 20:14 ` Felipe Contreras
2021-05-11 9:04 ` Jean-Noël Avila
2021-05-11 18:54 ` Martin Ågren
2021-05-07 23:35 ` Felipe Contreras
2021-05-07 23:57 ` brian m. carlson
2021-05-08 3:10 ` Jeff King
2021-05-08 3:23 ` Jeff King
2021-05-09 0:22 ` brian m. carlson
2021-05-09 8:29 ` Martin Ågren
2021-05-07 22:48 ` Felipe Contreras
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=CAN0heSp6uw7yqNZLD5w13xJUgnUtgHM0OYw9KQ6Z-FKk+x4OPA@mail.gmail.com \
--to=martin.agren@gmail.com \
--cc=bagasdotme@gmail.com \
--cc=git@vger.kernel.org \
--cc=peff@peff.net \
--cc=sandals@crustytoothpaste.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 an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.