Lumosql: Building an Internet-Draft or RFC from kramdown-rfc on Ubuntu

This compiles any Internet-Draft or RFC whose source is written in kramdown-rfc Markdown.

Target format: RFCXML v3, defined in RFC 7991: https://www.rfc-editor.org/rfc/rfc7991
Source tool: kramdown-rfc: https://github.com/cabo/kramdown-rfc

There are two stages, kramdown-rfc (Ruby) converts Markdown to v3 XML and then xml2rfc (Python) renders the XML to text or other formats. There is a handy online IETF service that does much the same at https://author-tools.ietf.org .

Verified with Ruby 3.2.3, kramdown-rfc 1.7.39, xml2rfc 3.34.0.

Install

kramdown-rfc runs on Ruby; xml2rfc on Python. Install Ruby from the system package manager and xml2rfc with uv. This is for Ubuntu, but tested also on Arch Linux and other operating systems.

    apt-get update
    apt-get install -y ruby
    gem install kramdown-rfc erb
    export PATH="`ruby -e 'puts Gem.user_dir + "/bin"'`:$PATH" # for installs in .local

Install uv with its standalone installer, unless your operating system packages a recent version.

    curl -LsSf https://astral.sh/uv/install.sh | sh
    uv tool install xml2rfc

no virtualenv and no --break-system-packages are needed. To run xml2rfc without installing it, use uvx xml2rfc.

Confirm:

    kramdown-rfc --version
    xml2rfc --version

Build

Reference resolution fetches bibxml over the network on first run and caches it. Set a cache directory so repeat builds are offline:

    export KRAMDOWN_REFCACHE=/tmp/refcache

    kramdown-rfc draft.md > draft.xml

    sed -i 's/\xc2\xa0/ /g' draft.xml  # remove annoying non-breaking space from BCP 14

    xml2rfc --text draft.xml -o draft.txt

    # optional other outputs, mostly not useful

    xml2rfc --html draft.xml -o draft.html
    xml2rfc --pdf  draft.xml -o draft.pdf

kramdown-rfc is silent on success.

Note: The first build needs to populate the cache from bib.ietf.org and datatracker.ietf.org with the references the draft cites.

You can check for any remaining non-ASCII with grep -nP '[^\x00-\x7F]' draft.txt, but be careful not to strip from human names. Unicode characters in general are fine, it's just the non-breaking space that can be a pain, and they are also invisible if you're just quickly looking with ordinary tools.