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
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 kramdown1.
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.
In case you are curious about my toolchain: The files are maintained via a private git repo, converted to HTML with Jekyll, and pushed to the server with rsync. That server is an Apache running under Docker on top of KVM2. When I push content, home-brew Docker images, or replace those on the server, I entrust rake with managing the proceedings. My setup needs no Docker registry, rsync does what’s needed. I standardize on Debian GNU Linux for my OS needs. ↩
I found that a KVM-based “virtual root server” that I can rent cheaply is good enough to run all the Docker containers I presently need. ↩