Re: [RFC suggestion] Generate manpage directly with Asciidoctor

From: Felipe Contreras <felipe.contreras@gmail.com>
Date: May 11, 2021, 19:00 UTC
Message-ID: <609ad46776dec_6011e208d7@natae.notmuch>
In-Reply-To: <877dk5tovj.fsf@evledraar.gmail.com>

Ævar Arnfjörð Bjarmason wrote:

Show 29 quoted lines

> 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.

I'm not disagreeing with that. The reason I mentioned it is what Jeff said next:

Show 6 quoted lines

> > > It's not too hard to install an updated gem, but not quite as nice
> > > as using the system package (it also makes things weird for
> > > building the stable Debian package itself, which would want to
> > > rely only on other packages; but of course any proposed change to
> > > the doc toolchain would be for new versions, and would not get
> > > backported there anyway).

Doing `gem install` solves the problem for whomever wants to build the latest git in Debian stable.

Building Debian stable packages is something else.

Show 9 quoted lines

> 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.

But what is "this"?

 1) Building the latest documentation in Debian stable
 2) Packaging the latest git in Debian stable

If it's 1) then there's no problem: `gem install` does the trick, and in fact in their CI builds [1] they test with versions of Ruby as old as 2.3, and Debian stable ships with 2.5.

I test my own Ruby code with versions of Ruby as old as 2.0 and there's rarely any issue. What works with Ruby 2.3 works with Ruby 2.0. Ruby is not like python (where 3.0 is completely different from 2.0).

If it's 2) then that's where I say: who cares?

> 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.

Right, but "just use the built doc tarballs" is not the suggestion for people trying to do 1).

Cheers.

[1] https://github.com/asciidoctor/asciidoctor/actions/runs/830132862

-- 
Felipe Contreras