Producing documents is unavoidable, but digital elves can help. In this article we look at how using plain text marked up with basic formatting instructions opens the door to a world of automation.

We have become very used to a series of tech-transformations in the infotainment media we consume:

  • VHS -> laser-disc -> DVD -> Netflix
  • Wax cylinder -> 78 -> LP -> cassette -> CD -> Spotify
  • Illuminated scroll -> printing press -> text document -> Word document

With the hardware transformations for the delivery come software transfomations of the media – in the form of changing and proliferating media formats, and often a lack of backward compatability. Often today’s applications can’t properly read your old document or a friend’s offering prepared on a different system. Come on, if you deny it, the elves will be bypassing you next Christmas for being naughty long-nosed Pinocchios. That’s better, it didn’t hurt to admit that a friend’s Mac MS Word font was not available on your PC and that all the carefully contrived layout went awry and that you swore as you had a deadline to meet.

We promise you won’t have such problems with pure text…

Marking up text with markdown

Remember we mentioned markdown on Day 1? If you have forgotten, to be fair, it was last year now. When we produce a document we think about both style and substance. We modify the impact of our message by choosing fonts, colours, layouts etc, most commonly from drop down MS Word menus. Markup languages allow explicit control over layouts when their elements are mixed with the document content. The more control we want (ultimately arriving at computerised typesetting), the more involved our markup syntax. HTML for formatting web pages is a bit too much for most babyElfs, but they rapidly learn to babble in markdown.

Lets try a simple example with a heading, italics, bold and a bulleted list. Copy this text and save in a file on your machine:

# Very basic markdown
We can render text in a variety of styles:

* Plain
* **Bold**
* *italicised*
* ~~Crossed out~~

#### A less important bit follows...

This text did not warrant such a big heading

The text styles we want are enforced by the addition of the markup characters. We now need an application to ‘render’ the text either to verify to ourselves that it looks as we think it should (in editing), or to present to our audience. There are many markdown renderers - you might like to start with the plugin for Chrome. Set its preferences so that it can access files on your machine and then open your markdown file. You should get something that looks like this:

Very basic markdown

We can render text in a variety of styles:

  • Plain
  • Bold
  • italicised
  • Crossed out

A less important bit follows…

This text did not warrant such a big heading.

Further documentation can be found in The Markdown Guide to effect a longer list of styles and layouts.

Applications

I suspect that the digitalElves have not quite convinced you to uninstall MS Word from your laptop yet and make the leap into the world of markdown. It is after all just another tool in the box. Here follows a little markdown marketing targetted at the kind of things that professionals do.

Blogs and personal websites

Suppose you wanted to communicate some seasonal digital education without spending more than a few quid or having ongoing subscriptions to a website provider. You could write the whole thing in markdown and put up The digital elf project. Its content is markdown articles, and the site is built with jekyll. For the site design you can start with freely downloadable templates.

Advertising with popup websites

Perhaps you want to advertise a scientific meeting and keep it up to date as you convert your speakers TBD to a series of megastars. jekyll new sci_meet will set you up a skeleton website in a new folder sci_meet in 10s or so and you can have it up on the web by zipping it and uploading to tiiny.host in about another 30 or so - Boom!

Writing scientific papers

As markdown files are plain text, it is easy to get into their guts and change them automatically. Scientific papers are often sequential pieces of data with explanatory linking text. Whilst the jupyter notebook offers some of these features, the format is not flexible enough to form the basis of a publishable work, where data and text are more intimately entwined. With markdown, the results of computation can be inserted into the text seamlessly. Here is the gist of it:

from statistics import mean

# this is our experimental data
data = [56, 98, 43, 71]
graft_years = 'three'

# now the complex calculation
av = mean(data)

# next the paper for Nature Averages
results_section = f'''
# Experimental results

We worked very hard to get our {len(data)} results
 and after {graft_years} years of graft in the lab
 we announce that the average of the values is {av}'''
 
# save the paper to disk
with open('Our_paper.markdown', 'w') as f:
    f.write(results_section)

Note that results flow into the document from the data without the possibity of human error (assuming the code for the calculations has been properly tested). If the data needs to be augmented or corrected the new write up will follow by rerunning the code. No searching and tweaking of any Word document.

Here is our paper as viewed in Chrome. Note that the data has been converted by machine into the results. No person ever typed ‘4’ or ‘67’ or miscounted or misculculated.

Once we have a final draft the markdown document can be exported inot another file format using the free tool pandoc. If our less digitally savvy collaborators need a Word document, give them one:

pandoc Our_paper.markdown -o Our_paper.docx

Under no circumstances, however are they to fiddle with the figures!

This is very much a ‘toy’ example - for more detail have a look a the following reference How to write academic papers in Markdown