-
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.
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
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