Installation and Setup

August 5, 2020 ยท View on GitHub

At a minimum, you need make and xml2rfc.

make

Mac users might need to install Homebrew to get a version of make that works properly (the version shipped in XCode is subtly broken).

brew install make

Note that this installs as gmake. Follow the instructions to add this as make to your path.

Windows users will need to use Cygwin or the Windows Subsystem for Linux to get make.

xml2rfc

All systems require xml2rfc. This requires Python 3. Be sure not to get Python 2, which is no longer supported. The easiest way to get xml2rfc is with pip, which is either installed with python, or part of the python-pip or python3-pip package on most distributions.

On Cygwin, you'll need to install pip directly:

$ curl https://bootstrap.pypa.io/get-pip.py | python

Once pip is installed, you can install xml2rfc.

Using a virtualenv:

$ virtualenv venv
# remember also to activate the virtualenv before any 'make' run
$ source venv/bin/activate
$ pip3 install xml2rfc

To your local user account:

$ pip3 install --user xml2rfc

Or globally (not advisable):

$ sudo pip3 install xml2rfc

xml2rfc might need development versions of libxml2 and libxslt1. These packages are named libxml2-dev and libxslt1-dev (Debian, Ubuntu); libxml2-devel and libxslt1-devel (RedHat, Fedora); or libxml2-devel and libxslt-devel (Cygwin).

Markdown

If you use markdown, you will also need to install kramdown-rfc2629 or mmark.

The template stuff tries to work out which of these you are working with based on the first line of the file:

  • kramdown-rfc2629 files must start with '---'

  • mmark files must start with '%%%'

kramdown-rfc2629

kramdown-rfc2629 requires Ruby and can be installed using the Ruby package manager, gem:

$ gem install kramdown-rfc2629

mmark

mmark requires go, and that comes with its own complications.

cd ~/bin
go get github.com/miekg/mmark/mmark
go build github.com/miekg/mmark/mmark

You might want to set aside a directory for your go code other than the default, and find a directory that is on the path where you can install mmark. For these, I set GOPATH=~/gocode.

Other tools

Some other helpful tools are listed in config.mk.