Skip to content

convert toolchain to kramdown + xml2rfc

Daniel Kahn Gillmor requested to merge kramdown-xml2rfc into master

Over in #7 (closed) and in !24 (closed), the difficulties in building the draft from source have come up a couple times.

I took a look at this and did some cleanup work on the sources so that it builds now with kramdown-rfc2629 and xml2rfc, producing almost exactly the same .txt output.

It's now a single markdown file to edit: rfc4880bis.md, and a single command to build: make. If you don't have a locally-cached copy of the reference XML, the IETF references will be fetched for you from the IETF's reference server, which gives a nice up-to-date reference list.

It didn't immediately give exactly the same output, i needed to go in and make a few simple cleanups along the way -- each cleanup is in its own commit and should be relatively easy to see that this series has no changes to the actual content.

The series also includes a makefile target rfc4880bis.txt.diff which offers a noise-filtered diff to show what actual characters have changed. The textual changes are:

  • minor changes to the boilerplate,
  • bulleted lists use different characters by default
  • dates are formatted differently
  • differences in pagination
  • different table formatting
  • slight differences in indentation
  • references are a bit more detailed

I've tested the build using the kramdown-rfc2629 and xml2rfc packages in debian 10 (buster). I've also tested it with the versions in Debian testing/unstable.

Using Debian testing/unstable (or ubuntu focal) means you can also add weasyprint into the mix, and that should produce a nicely-structured PDF, with a built-in table of contents as well.

In addition to these nice things, this rebuild highlighted that we were actually missing three references: REGEX, MZ05, and JKS02. This branch populates them appropriately, with details pulled from the original rfc4880.

I think we should merge this series so that it's easier to build the draft.

Merge request reports