Re: [NOTES 03/07] Documentation

From: Todd Zullinger <tmz@pobox.com>
Date: Oct 7, 2026, 04:49 UTC
Message-ID: <20261007044944.PjN-Ln9E@teonanacatl.net>
In-Reply-To: <summit-2026.94e33e9ddf234334.03@ttaylorr.com>

Thank you for the nice summaries Taylor.

Taylor Blau wrote:

Show 12 quoted lines

> Topic: Documentation
> * Peff: We support both AsciiDoc and Asciidoctor. Would it help to get
>   out of that dual world?
> 
> * Patrick: Traditionally this was for migration. AsciiDoc was thought to
>   be unmaintained, but it is maintained now.
> 
> * Peff: We could move to Asciidoctor.
> 
> * brian: Fedora still uses AsciiDoc. Asciidoctor is well maintained,
>   written in Ruby, and reasonably portable. It depends on how much we
>   want to support. I do not know whether Fedora is still an obstacle.

The Fedora packages have used Asciidoctor by default since e942c8d (use Asciidoctor to build documentation when possible, 2020-02-25).

    https://src.fedoraproject.org/rpms/git/c/e942c8d

That hasn't changed since I stopped maintaining the git package, so Fedora hasn't had an issue with a switch to Asciidoctor for quite a long time.

CentOS Stream / RHEL uses AsciiDoc (with the odd exception of 9). They _could_ use Asciidoctor relatively easily; it is maintained for EPEL already.

But if Red Hat really dislike requiring Asciidoctor for git builds in RHEL, they could ship the pre-built docs, as I used to do for EL-5 builds due to an unsupported (read: ancient) AsciiDoc version.

If we switched to Asciidoctor, it _might_ open the door to replacing the docbook/xmlto dependencies and having Asciidoctor directly generate the man pages.

I haven't thought about or looked at that in a long, long time, so I don't know if that would be a worthwhile change or not. I don't recall if we need the XML step for other outputs, like info or PDF (neither of which I ever spent much time trying to build).

-- 
Todd