From: "Martin Ågren" <martin.agren@gmail.com>
To: "Jean-Noël Avila" <avila.jn@gmail.com>
Cc: Jeff King <peff@peff.net>,
"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:54:33 +0200 [thread overview]
Message-ID: <CAN0heSpNhfmsVO5rME1xZzPPbkCuDm0ng64xWNx4xy+8ZrVz+Q@mail.gmail.com> (raw)
In-Reply-To: <0fd3182c-3805-ee1b-5a35-e0c9a67892ab@gmail.com>
On Tue, 11 May 2021 at 11:04, Jean-Noël Avila <avila.jn@gmail.com> wrote:
>
> On 09/05/2021 at 10:20, Martin Ågren wrote :
> >
> > I tend to think asciidoctor even renders our manpages *better* than
> > asciidoc does. Not by a huge margin, but a few things here and there.
> > Some time around the Python 2 EOL, I was about to propose flipping the
> > default, but then I went to look up the asciidoc EOL schedule, and like
> > you, I noticed that it was a lot more alive and kicking than I thought
> > 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".
>
> If we start to change the documentation format to "the way forward", we
> may soon end up with a format which is no longer handled by the legacy
> asciidoc.py
We used to be in a situation where Asciidoctor looked worse and the
rendered versions were quite different. We've fixed up quite a few
discrepancies by making some change that "happens" to be a noop with one
engine but an improvement with the other. (That it just "happens" has
sometimes been my feeling anyway.) Sometimes, we've been able to improve
both by spotting a difference, so that's good.
I would also expect that with more eyes on asciidoctor-built docs
(because default) and fewer on the other, the non-default will start to
degrade.
> As stated on https://github.com/asciidoc-py/asciidoc-py :
>
> "AsciiDoc.py is a legacy processor for this syntax, handling an older
> rendition of AsciiDoc. As such, this will not properly handle the
> current AsciiDoc specification. It is suggested that unless you
> specifically require the AsciiDoc.py toolchain, you should find a
> processor that handles the modern AsciiDoc syntax."
Thanks for that quote. It's very enlightening.
> FWIW, we are already using Asciidoctor for publishing the manpages to
> https://git-scm.com
Thank you for all your work on that site!
Martin
next prev parent reply other threads:[~2021-05-11 18:54 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
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 [this message]
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=CAN0heSpNhfmsVO5rME1xZzPPbkCuDm0ng64xWNx4xy+8ZrVz+Q@mail.gmail.com \
--to=martin.agren@gmail.com \
--cc=avila.jn@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.