Re: [NOTES 03/07] Documentation

[Todd Zullinger <tmz@pobox.com>]

Thank you for the nice summaries Taylor.

Taylor Blau wrote:
> 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