From: "Jean-Noël Avila" <email@example.com> To: "Martin Ågren" <firstname.lastname@example.org>, "Jeff King" <email@example.com> Cc: "brian m. carlson" <firstname.lastname@example.org>, Bagas Sanjaya <email@example.com>, Git Users <firstname.lastname@example.org> Subject: Re: [RFC suggestion] Generate manpage directly with Asciidoctor Date: Tue, 11 May 2021 11:04:50 +0200 [thread overview] Message-ID: <email@example.com> (raw) In-Reply-To: <CAN0heSpN_ieGc2HJCvSsmUuEqS-GGPDcZHz=v2Z3hJY=Or_HMw@mail.gmail.com> 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 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." So, as soon as the asciidoc format formal specification will gain traction in the public, we can expect asciidoc to be abandoned for new projects and receive minimal maintenance only for compatibility with legacy documentation. One argument in favor of Asciidoctor is that it's delivered "with batteries", meaning that you can generate manpages, html and even pdf with the same tool, without requiring secondary or even tertiary toolchains, which should ease usage on a broader range of platforms. FWIW, we are already using Asciidoctor for publishing the manpages to https://git-scm.com JN
next prev parent reply other threads:[~2021-05-11 9:05 UTC|newest] Thread overview: 38+ messages / expand[flat|nested] mbox.gz Atom feed top 2021-05-07 6:06 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 [this message] 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 List information: http://vger.kernel.org/majordomo-info.html * Reply using the --to, --cc, and --in-reply-to switches of git-send-email(1): git send-email \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --subject='Re: [RFC suggestion] Generate manpage directly with Asciidoctor' \ /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
Code repositories for project(s) associated with this inbox: https://80x24.org/mirrors/git.git 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 read-only IMAP folder(s) and NNTP newsgroup(s).