docbook-xml is hard to write/maintain/preview, and e.g. also has been orphaned in Debian for almost a decade now. Let's investigate moving to Markdown or asciidoc.

This concerns both the guide and the manpages (which are also rendered as part of the HTML guide).

Markdown:

• pro: Familiar to all of us, instant preview on GitHub
• con: not very suitable for larger multi-file documents; there may be extensions/tools for file inclusion and building table of contents
• pandoc has reasonable conversion from docbook to markdown, and from markdown to html/man (there are also more specialized tools)

Asciidoc:

• pro: it is exactly meant for this purpose, and also officially supports manpage buliding
• Cockpit's RHEL documentation is in asciidoc
• Migrate from DocBook to Asciidoc: https://docs.asciidoctor.org/asciidoctor/latest/migrate/docbook-xml/

Let's investigate both and pick one.