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

[Patrick Steinhardt <ps@pks.im>]

On Wed, Sep 02, 2026 at 03:16:13AM -0400, Jeff King wrote:
> 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.

>  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