-
Notifications
You must be signed in to change notification settings - Fork 84
This wiki page collects some information on getting various additional tools to work that aid in creating and using SVG graphics with kramdown-rfc that are being generated from text-based specifications.
kramdown-rfc does not attempt to install any of the executables needed for this with its own installation. The below gives installation instructions. (These are heavily slanted to macOS, as that is what the author uses; additions for Debian, Ubuntu etc. welcome.)
For now, it is safe to assume that these additional tools are not
available on the kramdown-rfc web service offered by the tools team.
Most of them can be made to work with GitHub Actions, including via
Martin Thomson's I-D-template distribution. When using this
template on github, just add an m to:
uses: martinthomson/i-d-template@v1
yielding:
uses: martinthomson/i-d-template@v1m
in .github/workflows/ghpages.yml (v1m stands for Mega-image).
The basic idea is to mark an input code block with one of the labels
discussed below (language types), yielding some plaintext form in the
.TXT output and a graphical form in the .HTML output.
In some cases, the .TXT plaintext is the input (e.g., ASCII art,
mscgen), in other cases, the tool may be able to generate some
plaintext rendition (e.g., plantuml-utxt).
As calling the external processes does take some time, kramdown-rfc
caches the results (at the same place where references are cached,
e.g., .refcache or, if configured so, ~/.caches/xml2rfc).
The cached result is re-used until either the
input (what is in the code block) changes or the version number of
kramdown-rfc changes.
After installing a new version of kramdown-rfc, a new invocation of
kramdown-rfc will therefore run tools again, with messages that you
haven't seen in a while; this alone is no cause for alarm.
Most of the SVG tools are integrated via the svgcheck tool.
Installation (depending on your environment, use pip if pip3 does
not work:)
pip3 install svgcheck
This tool would do well with a bit of love, but is usable enough as is. Note that it usually spews a number of misleading error messages; these are relayed by kramdown-rfc in the event they can help with diagnosing an error, but usually can be ignored.
The SVG tools support in kramdown-rfc is rapidly moving forward. In this evolution, we will attempt to not invalidate markdown source documents that already have worked. But there is less guarantee about this intention than in other parts of kramdown-rfc, and a bit more expectation of interaction between document and tool authors.
goat, ditaa: ASCII (plaintext) art to SVG figure conversion
A lean, golang-based "ASCII-art" to SVG converter.
Install via go get github.com/blampe/goat
(you need an installation of the go language, e.g., via brew install go)
Set the executable lookup path in the environment ($PATH) to include the golang executable location, or simply:
ln -s $(brew --prefix)/.gocode/bin/goat $(brew --prefix)/bin/goat
A drop-in goat replacement that provides a more natural character spacing and may be easier to install has been provided by Martin Thomson.
npm install -g aasvg
More about aasvg: /~https://github.com/martinthomson/aasvg
Two nice examples:
https://thomas-fossati.github.io/draft-psa-token/draft-tschofenig-rats-psa-token.html#figure-1 https://thomas-fossati.github.io/draft-psa-token/draft-tschofenig-rats-psa-token.html#figure-2 from: https://raw.githubusercontent.com/thomas-fossati/draft-psa-token/master/draft-tschofenig-rats-psa-token.md (search for aasvg) in: /~https://github.com/thomas-fossati/draft-psa-token/
Somewhat heavyweight, Java-based tool that used to be quite popular. Notable for its color support that unfortunately cannot be used in RFCXML.
- mscgen: Message Sequence Charts
brew install mscgen
- plantuml: widely used multi-purpose diagram generator
- plantuml-utxt: Like plantuml, except that a plantuml-generated plaintext form is used
plantuml can be set up to provide a UTF-8 based plaintext fallback;
use plantuml-utxt to select that.
brew install plantuml
kgt (Kate's Grammar Tool) is amazing, but unfortunately a bit hard to install.
It requires a working pmake (or bmake).
Homebrew-style instructions that worked for me:
brew install bmake
git clone --recursive /~https://github.com/katef/kgt.git kgt-work
cd kgt-work
CC=clang PREFIX=$(brew --prefix) bmake -r install
## While you are at it, do this to get the amazing `re` tool:
cd ..
git clone --recursive /~https://github.com/katef/libfsm.git libfsm-work
cd libfsm-work
CC=clang PREFIX=$(brew --prefix) bmake -r install
...
$ re -l abnf "[A-Za-z]bc*"
➔ e = (%x41-5A / %x61-7A) %s"b" *%s"c"kgt's railroad tool translates a single ABNF rule into a railroad
(race-track) diagram, both in SVG and ASCII form.
Use railroad to select this.
This tool can also be set up to provide a slightly more polished
looking UTF-8 based plaintext fallback;
use railroad-utf8 to select that.
- mermaid: Very experimental; the conversion to SVG is prone to generate black-on-black text in this version
Very useful for instance for Gantt charts. RFCXML integration via svgcheck does not work very well yet.
npm install -g mermaid.cli
npm install -g tex2svg
brew install asciitex
\
(but see below)
Besides the SVG-creating tools, there is a need to provide text/plain alternatives. In many cases, the SVG tool input is all we can get at the moment, in others the SVG tool has its own plaintext mode (e.g., plantuml). In some cases, additional tools need to be installed to get the text/plain output.
Lars Eggert has created an updated version of asciiTeX: /~https://github.com/larseggert/asciiTeX
Installation instructions can be gleaned from /~https://github.com/martinthomson/i-d-template/blob/main/docker/math/Dockerfile
protocol is a relatively obscure tool for creating ascii art box
diagrams of protocol encodings, documented at http://www.luismg.com/protocol/
and installable from /~https://github.com/luismartingarcia/protocol.
This tool requires manual installation from its setup.py;
note that this is different from what you get with pip3 install protocol.
It can be used standalone, e.g. in
~~~ protocol
Source:16
Reserved:40
TTL:8
~~~
to create the equivalent of
~~~~
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Source | |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
| Reserved | TTL |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
~~~~
or in combination with goat or aasvg as in
~~~ protocol-aasvg
Source:16
Reserved:40
TTL:8
~~~
{: artwork-svg-options="--spaces=2"}
to create conventional ascii art box diagrams for text rendering in conjunction with SVG for the HTML rendering.
The previous example also shows how to provide command line options to the SVG-creating tool. An analogous example for providing command line options to the plaintext-creating tool (here: 16 bits per row, no bit numbers):
~~~ protocol-aasvg
Source:16
Reserved:40
TTL:8
~~~
{: artwork-txt-options="-b 16 -n"}