Markdown’s Tower of Babel

One name, many grammars: the standard that never was

Mention “Markdown,” and most developers think of a single, universal standard. It isn’t. The name actually covers a messy family of related, yet mutually incompatible grammars. Back in 2004, John Gruber released the original version as a basic Perl script accompanied by a prose description. Neither specified the syntax with anywhere near the precision needed for independent parsers to agree. Ten years later, CommonMark (2014) finally brought order to the core syntax. But it only goes so far. Real-world documents need tables, footnotes, math, metadata, task lists, and callouts which are all features that CommonMark leaves entirely to a wild west of custom extensions. How hosts support these extensions varies widely.

Hugo

I decided to start working on my personal website again, and as an exercise I decided I’d create my own theme etc. as a way to learn Hugo. I am purposefully limiting the styling and use of JavaScript to create a very minimalist look and feel.

Despite it’s popularity, the documentation for Hugo, even though there is a lot of it, isn’t all that great. You actually have to learn the templating language, as well as get a handle on the variables etc. etc. and I am sure there are many, many nooks and crannies to explore. There’s even a diagramming system built into Hugo, which might be interesting to play with, because it converts ASCII art into the following.

Hacking away on the PIC16F88 trying to get it to talk to the NeXT host machine, and I kept getting very long rise or fall times for the signal when twiddling the TRIS bits. I also saw some very unusual signals on the clock line. It finally occurred to me that as an open collector bus, with no keyboard attached, the lines would float without the addition of pullups. I added two 10k resistors, and lo and behold, deterministic timings! With that I was finally able to start sending data to the NeXT machine.

After getting most things working on the PIC16F88 I started looking at the timing. On the NeXT side, data needs to be transmitted after the channel select signal on the clock line, and there is only a few hundred microseconds on either side to do anything. On the PS/2 keyboard/mouse side, given the relatively slow transmission speeds, reading the data takes on the order of a millisecond. Basically, unless I want to run the PIC16F88 at a high clock rate and continuously sampling pins to detect bits, and then feeding detected bits into concurrent hierarchical state machines, we’re stuck. It’s doable, but the resulting code will be dense and almost impossible to understand. I actually started to write a simple state machine to PIC assembler compiler that would generate the concurrent state machines thinking it might be a better way to go…