Me and hypertext

The beginnings

In spring 1993, I started using a DOS tool dart, which was my first encounter with hypertext. The format could be described as an early precursor of markdown. At the time, I was user of a group of bulletin boards, and authored a text informing about said group. A floppy disk containing both software and text became a major giveaway at the group’s booth at some fair.

SGML and the bread recipe

Later in the 90s, I typed my share of HTML documents.

In 1997, my mother-in-law asked me how I baked my sourdough bread. I took that as an opportunity to investigate SGML (on which HTML was then based).

SGML is a meta-format, similar to its later offspring XML. SGML is also a typical brain-child of the 90s: Quite elaborated, somewhat of a mouthful to fully comprehend and implement in software, with its own beauty and bright ideas, later considered over-engineered and, by now, almost forgotten. From an author’s perspective, it is nicer to type, compared with its later offspring XML.

The whole bread recipe / SGML thing turned into a labor of love and an exercise in joyful over-engineering. Where a mere recipe was wanted, I wrote down everything I considered even remotely important for backing sourdough bread. (Developers hate documenting? I actually enjoy organizing knowledge into text. I did then, and I still do.) A 13 page manual resulted, where a simple sheet of paper would have quite satisfied my mom-in-law. Just for the fun of it, I rigged up a multi-media platform, generating HTML and PDF from the same SGML source.

SGML is rarely used these days, but, as of Debian Stretch 2018, my old multi-media platform still works, essentially unchanged for 20 years. The tools I used back then still exist. The material itself continues to be available on my web page. Its canonical URI has changed only twice in 20 years: First, when I obtained my personal domain, then again when I upgraded from HTTP to HTTPS.

Markdown and YAML

Today, I enjoy using the various markdown flavors. This site is written in kramdown¹.

Sometimes, one likes to author an overall document structure with content that software can interpret, but one also wants to intersperse documentation snippets for human consumption. Those documentation snippets are to be formatted nicely, but otherwise left alone and not truly interpreted by software.

Both SGML and XML offer straightforward solutions for this. Basically, a naming convention for tags is all that is needed. But one would not want to use SGML for new projects, and typing XML via an editor is not exactly a pleasure to actually do, either. If not these two, what else can one use?

When I had such a need a while ago, I tried with good success to insert markdown snippets into YAML documents. This combination is much nicer to type than was SGML. The YAML is machine-processed easily, the markdown snippets extract and format quite easily as well. To anybody running into a comparable need, I recommend considering this approach.