Re: [PATCH 2/2] ci: use system asciidoctor

From: Patrick Steinhardt <ps@pks.im>
Date: Sep 2, 2026, 07:55 UTC
Message-ID: <apfWhYF6nmcFGKE3@pks.im>
In-Reply-To: <20260902071613.GB641414@coredump.intra.peff.net>

On Wed, Sep 02, 2026 at 03:16:13AM -0400, Jeff King wrote:

Show 14 quoted lines

> Our CI Documentation builds have pinned asciidoctor since 615a6c37e1
> (ci: stick with Asciidoctor v1.5.8 for now, 2019-03-29). Back then a few
> changes were needed to build with the then-new v2.0.0.
> 
> We've since made those changes, in f6461b82b9 (Documentation: fix build
> with Asciidoctor 2, 2019-09-15) and other commits. So it is not only
> safe to use newer versions of asciidoctor, but preferable: it's what
> people are likely to use for actually building the documentation in
> practice!
> 
> I don't think there's any need to pin to a specific version. We can just
> use what ships in our Ubuntu image, which should give us an arbitrary
> representative version (and if it changes and something breaks, we'd
> want to know).

Makes sense.

One thing that we might have to worry about is compatibility with _old_ versions of asciidoctor. Now that we're using a more modern version of it we might start relying on features that weren't available in older versions, and we wouldn't notice anymore. So we kind of have the reverse problem now.

The best-case scenario would be if asciidoctor had something like a compatibility mode where you can ask it to complain about features that aren't available in a specific cutoff version. But I have no idea whether such a thing even exists.

Also, I'm not sure though whether this concern is something that we really have to care about, I may be overthinking this quite a bit. So please don't read this as a "Let's not use a modern version", but rather as me writing down my unfiltered thoughts.

Show 17 quoted lines

>  ci/install-dependencies.sh | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/ci/install-dependencies.sh b/ci/install-dependencies.sh
> index 2f61fbb07c..d57dce5663 100755
> --- a/ci/install-dependencies.sh
> +++ b/ci/install-dependencies.sh
> @@ -164,9 +164,9 @@ sparse)
>  		libexpat-dev gettext zlib1g-dev sparse
>  	;;
>  Documentation)
> -	sudo apt-get -q -y install asciidoc xmlto docbook-xsl-ns make ruby
> +	sudo apt-get -q -y install asciidoc xmlto docbook-xsl-ns make ruby \
> +		asciidoctor
>  
> -	sudo gem install --version 1.5.8 asciidoctor
>  	sudo gem install concurrent-ruby

Huh. I was wondering whether we can now stop installing Ruby altogether, but we still install the "concurrent-ruby" Gem. But what even is that, and what do we use it for?

It's originally been introduced via 974cdca345 (doc: introduce a synopsis typesetting, 2024-09-24), but unfortunately the commit message does not document why we have to install that Gem now. I couldn't find any reasoning in the mailing list thread, either.

Patrick