Simplistic Diagrams with ASCII Art

I am a huge fan of visual description. When I think abstractly, I use visual cues to illustrate my thoughts and my thought process. As an autodidact, I find I better understand descriptions of just about anything when they are accompanied with visualizations.

I’m also a minimalist. I don’t have formal design training (or much formal training in anything at all, really), so what I consider minimalistic may not be in the strictest sense of the word.

When I transitioned to a software architecture role at Message Systems, I found a real need for more documentation on the technical interplays between (and within) our products. I’ve tried to use tools like dia, but I find the interface to be difficult. My diagrams never end up looking like what I envisioned in my head.

A Minor Digression…

When I was younger, I spent a lot of time on local BBSes in Durham, NC. One of my favorite message boards was the ANSI / ASCII art board. I played around with creating this art (using tools like ACiDDraw), but I never got particularly good at it. Still, it molded my brain enough to make drawing in ASCII more viable for me later in life. Indeed, if any readers are users of Momentum, check out ec_console, and run the command \debug. You’ll be placed in “debugging mode,” and you’ll be greeted with a screen:

  .pQQQQQp                 ffpQQQQQQQQQQQQQQQQQQQQQQpp              QQQQQQQp.
 .QQQQQQQQpp                  ppQQQQQQQQQQQQQQQQQpp.               pPQQQQQQQQ.
 PQQQQQQQQQQQQQQQQQQQQQQ         `QQQp  ,PQQQQQQQQ       pPQQQQQQQQQQQQQQQQQQQQ
 QQQQQQQQQQQQQQQQQQQQQQQQQQQQQpp  pQQp  pPQQQQQQP   ppPQQQQQQQQQQQQQQQQQQQQQQQQQ
 QQQQQQQQQQQQQQQQQQQQQQQQQQQQQPPPppQp  pPQQQQQQQP  pPQQQQQQQQQQQQQQQQQQQQQQQQQQQQ
 QQQQQQQQp              'pQQQQQQQQQQQQQQQQQQQQQPPPQQQPfp'                 'p,QQQQ
 QQfa'            AQp       'fpQQQQQQQQQQQQQQQQQQQQPfp'         Afp           fAQ
 QQQfa' .fAAQ'.   QQ,  .fF p  hhQQQQQQQQQQQQQQQQQQQQh    hFF.   QQP  ;QQQ   ;AQQQ
  fFQQQQQQQQQQFp      'QQQQQQQQQQQQQQQQQQQQQQQQQQ fQQQQQQQQQPF.      pPQQQQQQQFP'
    pQQQQQQQQQQQQQQQppfQQQQQQf ,QQQQQQQQQQQQQQQQQp  pQQQQQQQQQQQPpppPQQQQQQQQQQP
       pQQQQQQQQQQQQQQQQQ       PQQQQQQQQQQQQQQQPP   .pQQQQQQQQQQQQQQQQQQQQQQFP

                        I   A M    T E N    N I N J A S

This ASCII art is based on an image that was passed around our internal IRC channel one day several years ago:

I had played around with using various utilities wrapping libraries like aalib to generate the image, but nothing looked very good. So I did it by hand. I was genuinely amazed by the results. It had been at least 15 years since I had seriously tried to do any ASCII art, and it had “just worked.”

For those playing along, run \debug again to turn off debugging mode.

…and We’re Back

So the next time I tried using Dia for creating architectural diagrams, I got really frustrated. For one, I was writing my document in Markdown. Since this document was supposed to holistically describe the software architecture of a particular product, it felt rather unfortunate that I couldn’t view the diagram inline with the document. I looked again at the diagram I had created. It didn’t look very good anyway. I tossed it and made an ASCII diagram inside a code block.

It worked. Spectacularly.

After this huge success, I had to ask another question. Was there a way to render this diagram to an image?

I searched for quite some time and finally came across a utility called Ditaa. It worked splendidly; I only needed to make a small number of changes for my diagram to render into a beautiful PNG image. We integrated support for Markdown and Ditaa into the wiki system of mtrack. The only problem was that editing became extremely slow. This was exacerbated by two factors:

• Ditaa is written in Java; as mtrack is written in PHP, the only way to integrate with Ditaa is to spawn a process every time you want it to run.
• Ditaa outputs rasterized images which are not easy to inline in HTML.
• Mtrack provides a live preview mode when editing files.

These three properties caused filesystem buildup, a large amount of disk I/O, and tons of temporary files that needed reference counting and cleanup (over a stateless protocol, no less). Additionally, the live preview caused a buildup of JVMs as the more bogged down the server got, the more JVMs were spawned due to subsequent edits.

It was clear that Ditaa would not hold up (not necessarily through any faults of its own), and we ultimately disabled it.

Enter ASCIIToSVG

I was disappointed, but not deterred. I decided to write a utility to replicate the functionality of Ditaa in a way that would be easier to integrate with mtrack.

I figured that SVG would be a good format to output. The diagrams could then be modified by external GUIs and they could be infinitely (or infinitesimally) scaled. Additionally, it would be possible to integrate the output directly into a live preview, since every modern browser supports inline SVG.

Within a day, I had something that worked for the diagram I was writing. Enter ASCIIToSVG. It was implemented in PHP in order to make integration with mtrack easier – it allowed us to avoid spawning new processes entirely.

I partially regret that it is implemented in PHP. PHP is not great at text processing and doesn’t have any syntactic sugar for matrices of any dimension. Languages such as Perl or Python that do have well-understood idioms for these sorts of tasks also have communities filled with people who are not particularly fond of PHP. (That’s fair; I’m not particularly fond of PHP either.) Implementing it in PHP means I am constrained to PHP consumers. I think ASCIIToSVG would serve the world better if it had been implemented in Python, Perl, Ruby, or Go.

Recent Success

I have never advertised ASCIIToSVG, and it is therefore always a pleasant surprise when I find new users. I’ve had a few people email bug reports to me, but most of the users are necessarily inside Message Systems.

I was therefore surprised and excited when I found out that ASCIIToSVG is now in use to generate the diagrams for the ØMQ handbook. This book is in fact in print under the title “Code Connected”.

This blew my mind.

It’s a huge milestone for me to have written something and have been able to release it to the open source community under my own copyright – and to have others use and trust it for their own professional purposes. Here’s an example diagram from the book (the diagrams are licensed under CC-BY-SA and Pieter Hintjens holds the copyright). This diagram is showing the notional flow of data between publish / subscribe sockets in ØMQ.

                 #-----------#
                 | Publisher |
                 +-----------+
                 |    PUB    |
                 '-----------'
                     bind
           tcp://192.168.55.210:5556
                       |
                       |
      .----------------+----------------.
      |                |                |
      |                |                |
   connect           connect          connect
.------------.   .------------.   .------------.
|    SUB     |   |    SUB     |   |    SUB     |
+------------+   +------------+   +------------+
| Subscriber |   | Subscriber |   | Subscriber |
#------------#   #------------#   #------------#

ASCIIToSVG helpfully renders this to:

The image in the published version differs slightly due to an unfortunate off-by-one error in the line walking code. Pieter’s set of diagrams is by far the most complete and diverse usage of ASCIIToSVG to date, and I intend to add several more features and bugfixes over the coming days and weeks.

If you’re interested in making such diagrams, or if you’d like to port ASCIIToSVG to another language, please feel free to get in touch with me. I’d love to make the software even better.