Subject: Re: [RFC suggestion] Generate manpage directly with Asciidoctor

From: Ævar Arnfjörð Bjarmason <[email-masked]>
Date: Tue, 11 May 2021 14:44:41 +0200

On Tue, May 11 2021, Felipe Contreras wrote:

> Jeff King wrote:
>> On Mon, May 10, 2021 at 11:27:54PM -0500, Felipe Contreras wrote:
>> > Jeff King wrote:
>> [...]
>> > I've never understood developers worried about how the bleeding edge
>> > would build in ancient platforms, when ancient platforms don't care
>> > about the bleeding edge.
>> 
>> Again, this is about developers. Are there people contributing new
>> documentation to Git who are doing so on Debian stable, and would be
>> inconvenienced by needing to upgrade their toolchain?
>
> Developers don't need to create (or use) debian packages. They can
> simply do `gem install asciidoctor` and be done with it. Some may even
> create a docker container to install all the doc toolchain in order to
> avoid polluting their main environment.
>
> I for one would start building the documentation more if all I needed is
> one dependency.

Just because I'm developing the latest git.git revision on Debian stable
that doesn't mean that I'm keen to install the very latest openssl,
libcurl, asciidoc, C compiler, or whatever other thing we depend on.

I'm not disagreeing with bumping the dependency in this case (I haven't
looked into it). I'm just pointing out that in general there's a lot of
use-cases for e.g. building a latest git on an N year old OS.

Of course we can ask these people to just build their dependencies too,
as I noted in [1] in a past discussion. Whether we bump our required
dependencies is a trade-off between our own convenience and these sorts
of in-the-wild builds.

I'm just saying we should keep this use-case in mind, it's not an all or
nothing where you either have ancient deps + ancient git or bleeding
edge deps + bleeding edge git. A lot of people build ancient deps +
bleeding edge git.

The "just use the built doc tarballs" is only a partial solution, and
e.g. won't work for someone who's interested in building "next" or
otherwise applying local patches that have doc changes.

1. https://lore.kernel.org/git/[email-masked]/