Introducing regfmt

2022-10-25T11:31:00-07:00

Sometimes a project you've had in the mental back burner for decades calls to you again, but this time you pay attention. So it is with regfmt, a command line utility that I spent this past month working on.

Backstory

While I was in grad school back in the early 1990's the department had prescribed using the AT&T troff tools for writing papers. Among those tools was one called dformat, which enabled you to easily draw out control register-style data formats using a domain specific language (DSL).

dformat was a great tool for its time but over the years got consigned to bit rot and ultimately forgotten by many. Among the reasons for it being forgotten was that it only supported the troff specific pic drawing language and used a make-shift DSL for its input.

Today

The world moved on and settled on other tools for writing and drawing. That said, the fundamentals of computer design haven't changed and control registers are still a thing, so the need to draw them out is still a thing, and drawing them by hand is still painful.

In the intervening time from the early '90s to 2022, I've run into times when I wished I had something like dformat but modern to use for writing technical documentation. What's modern you say? How about having:

a common vector graphics file format output such as SVG which can then be easily converted to a raster format (png, jpg, etc.).
an input specification that is based on a common data serialization language.

In the early summer of 2022, I got to thinking about dformat and how it could be re-imagined for today and realized wow, all the pieces I needed were there:

Use SVG for the output format
Use YAML for the input format
Use CSS to style the output
Implement in Python which has support for all of the above.

In October 2022, I found the cycles to go to work on this.

Announcing regfmt

regfmt is a Python command line utility to generate SVG diagrams for control register-style data formats. It is inspired by the dformat command from the troff family of tools, however re-imagined using contemporary (circa 2022) file formats.

Python installation: PyPI: https://pypi.org/project/regfmt/

Source Repository: GitHub: https://github.com/kickingvegas/regfmt

Example output of regfmt

Features

SVG output
Modern configuration input file formats
- YAML for register configuration
- CSS for styling SVG output

Try it out!

If you need a tool like this, please take the time to try it out. Any feedback would be appreciated!

Requirements

Python: ≧ 3.9

Installation

regfmt supports installation via PyPI. Is is recommend that you do this in a Python virtual environment.

$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) pip install regfmt

notes from /dev/null - regfmt