Tools for creating PIEs.

This project is based on:

• kramdown-rfc, which is an excellent tool written in Ruby for transforming specially enhanced Markdown (kramdown) files into XML files that serve as inputs to writing RFCs.
• xml2rfc, which is an excellent tool written in Python for transforming XML files into RFC-formatted outputs (txt, pdf, html).

This project is not installable. It is intended to be used as a git submodule or via a symbolic link, or other type of include.

While it's not necessary two write PIEs in formats that align with RFCs, at minimum it would make later adoption by IETF working groups a whole lot easier. RFCs also follow document conventions that work well for the Interpeer Project.

But running tooling in two languages is cumbersome, and adapting tooling for slightly different publication conventions than they are made for can be frustrating. To simplify this, this project consists of a simple GNU Make based template that manages the Ruby and Python environments, plus some key extensions to kramdown-rfc that adapt some things to work better for PIEs than for RFCs.

Features

• Uses kramdown-rfc feature for providing a custom ERB template to provide distinct templates for PIEs, obsolete Interpeer drafts and regular IETF/IRTF documents such as Internet-Drafts and RFCs.
• For PIEs, provides extended functionality for manipulating document metadata.

Prerequisites

• You need to have a current (3.x) version of Ruby. I'd recommend something like rbenv to manage Ruby versions.
• You need to have Python in a version greater or equal to 3.9.
  • You need poetry, which you can install via pip install poetry.
• You need to have GNU Make.

Note that the forgejo action also sets up Go, but PIE tools do not need this. This is to then install goat, which can be used to turn ASCII art diagrams into SVG - a very useful addition to the kramdown-rfc workflow.

Installation

1. Create your project folder. You don't need to create a document first, but for the purposes of this guide, let's do it. There is only a rather lightweight naming convention:

• Input markdown files must end with .md.
• README.md is ignored as an input file.

$ touch my-doc.md

1. Make it so that this project exists in this folder under pie_tools. This document assumes some familiarity with the relative benefits and downsides of various approaches.

• Symbolic Linking
  1. Check out pie_tools somewhere else; let's assume afterwards you have $HOME/src/pie_tools
  2. Change to your document folder.
  3. Run $ ln -snf $HOME/src/pie_tools
• Use git submodules
  1. Run $ it submodule add https://codeberg.org/interpeer/pie_tools

1. Now initialize the project:
   1. $ make -f pie_tools/make/build.mk init This creates a number of files in your repository, most notably a Makefile that includes the above build.mk, a Gemfile that includes a Gemfile from pie_tools, similarly files for managing Python dependencies, etc.
2. Run $ make for usage instructions, e.g. make html for a htmlified version of the input markdown file(s).

Project Structure

• includes contains Markdown snippets one can use with kramdown's include mechanism.
• erb contains:
  • A main.erb file, which loads PIE tool's templating extensions.
  • A pie.erb file, which contains a custom template for PIEs.
• lib contains Ruby files that extends the templating functions used in the pie.erb file above.
• pie_tools contains a Python package with some functions and scripts.
• make contains functionality for the Makefile structure.
• templates contains all the template files that make init copies to the document directory.
• completion contains completion files; currently only bash completion is supported.
• 3rdparty refers to third-party tools we want to install and can't install via the pipenv mechanism directly:
  • protocol