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

From: Todd Zullinger <tmz@pobox.com>
Date: Sep 5, 2026, 15:23 UTC
Message-ID: <20260905152300.Zo2Zl39n@teonanacatl.net>
In-Reply-To: <20260905140217.GA3914642@coredump.intra.peff.net>

Jeff King wrote:

Show 7 quoted lines

> BTW, after having dug into Debian versioning for another
> patch this morning, I bothered to look at which
> asciidoctors they ship. Even Debian 11, which just went
> out of LTS, was on asciidoctor 2.x. Ditto for RHEL8, which
> has a 10-year cycle (it hasn't been 10 years since
> asciidoctor 2.0.0, but it luckily was released in the
> right part of the cycle).

FWIW, asciidoctor in RHEL and clones is part of the add-on EPEL repo from the Fedora project.

Being part of EPEL rather than the base RHEL is largely why the version bumps happen in what is otherwise a relatively static base OS -- EPEL is run by volunteers and allows for pushing breaking changes a bit more liberally than RHEL itself.

(Asking free laborers to be on the hook for backporting bug and security fixes for 10 years doesn't go down all that well, unsurprisingly.)

Looking at the Fedora/EPEL asciidoctor commit history¹, it looks like I pushed commits to bring it up to 2.0.20 for EL-9² before I stopped contributing. Those changes have never been pushed out though, so it doesn't look like anyone's really minding the ascidoctor packages in EPEL these days.

¹ https://src.fedoraproject.org/rpms/rubygem-asciidoctor ² https://src.fedoraproject.org/rpms/rubygem-asciidoctor/commits/epel9

As none of the CI jobs are installing documentation against any RHEL-like targets, this doesn't matter much. But if we were, we'd need to install the 'epel-release' package before installing asciidoctor, perhaps something like this:

  diff --git i/ci/install-dependencies.sh w/ci/install-dependencies.sh
  index 10c3530d1a..119e12041d 100755
  --- i/ci/install-dependencies.sh
  +++ w/ci/install-dependencies.sh
  @@ -32,6 +32,10 @@ alpine-*)
   		bash cvs gnupg perl-cgi perl-dbd-sqlite perl-io-tty cargo >/dev/null
   	;;
   fedora-*|almalinux-*)
  +	case "$distro" in
  +	almalinux-*)
  +		dnf -yq install epel-release >/dev/null
  +	esac
   	case "$jobname" in
   	*-meson)
   		MESON_DEPS="meson ninja";;

> I don't think that changes our conclusions. Just adding a
> little bit of research for posterity.

Ditto. ;)

I'm happy to see more Asciidoctor support. It seems to produce moderately better output than Asciidoc, in my experience. Though I admit I haven't looked closely at Asciidoc after development picked back up a little to add Python 3 support and keep the project going.

-- 
Todd