git@vger.kernel.org list mirror (unofficial, one of many)
 help / color / mirror / code / Atom feed
From: Jeff King <peff@peff.net>
To: "brian m. carlson" <sandals@crustytoothpaste.net>
Cc: Bagas Sanjaya <bagasdotme@gmail.com>, Git Users <git@vger.kernel.org>
Subject: Re: [RFC suggestion] Generate manpage directly with Asciidoctor
Date: Fri, 7 May 2021 18:19:03 -0400	[thread overview]
Message-ID: <YJW81zNr5bgW+yVs@coredump.intra.peff.net> (raw)
In-Reply-To: <YJWiQH2nf0B14Zy7@camp.crustytoothpaste.net>

On Fri, May 07, 2021 at 08:25:36PM +0000, brian m. carlson wrote:

> > So completely migrating to Asciidoctor can eliminate xmlto requirement
> > for generating manpage.
> > 
> > What do you think about above?
> 
> I didn't do this because it makes things very complicated in the
> Makefile and my goal was to minimize the needed changes and divergence.
> I'm not opposed to someone else doing it, but I expect it will be a
> bunch of work.

Yeah. In the period where we support both asciidoc and asciidoctor,
using the same flow for both (even if it's suboptimal for asciidoctor)
kept the complexity down.

I _thought_ the original asciidoc was marked as deprecated /
unmaintained at some point. But it does seem to have gotten a few
releases in the last year (it looks like maybe the python 2 version was
EOL, but somebody decided to make the effort to port it to python 3?).

But I wouldn't be at all sad to just standardize on asciidoctor. I think
we're at parity in terms of the output (thanks to lots of work from you
and Martin over the past couple of years), and I've generally found it
nicer to work with.

The only downside is that it may be available in fewer places (though
I'd think that python vs ruby is not so different). IMHO it's OK to be
aggressive about the doc toolchain requirements, because the fallback is
always grabbing the preformatted roff or HTML pages that were generated
on a different system.

-Peff

  reply	other threads:[~2021-05-07 22:19 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 [this message]
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
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 \
    --in-reply-to=YJW81zNr5bgW+yVs@coredump.intra.peff.net \
    --to=peff@peff.net \
    --cc=bagasdotme@gmail.com \
    --cc=git@vger.kernel.org \
    --cc=sandals@crustytoothpaste.net \
    --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).