Re: [RFC suggestion] Generate manpage directly with Asciidoctor

From: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Date: May 11, 2021, 12:44 UTC
Message-ID: <877dk5tovj.fsf@evledraar.gmail.com>
In-Reply-To: <609a3a5a7aa08_5d5d32088@natae.notmuch>

On Tue, May 11 2021, Felipe Contreras wrote:

Show 19 quoted lines

> 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/874ltg2tvo.fsf@gmail.com/