Parsing footnotes and code blocks (MDL Log #4)

In this update I've added footnote parsing and basic rendering¹. This is motivated by Mogo's user story, where he needs to add source information to his articles. This is something I need when I write health related articles. Footnotes provide an alternative to linking words -- they are more natural in many contexts when citing sources.

Mogo's User Portrait

I'm doing the user stories as they help me check what features I need now. Instead of going down the route of perfect library code, I'm trying to get all the primary user features working first. This will help a lot when it comes to the extension features: I'll already have examples of all the things that need to be supported, lessening the fear the design will be wrong.

If you'd like a quick introduction to user stories, check out my class on Skillshare.

Mogo is a freelance medical journalist. Free travels to various countries, primarily Africa, and publishes health articles in a prestigious online journal. She conducts local interviews to get a personal feeling to events, and to discover what is important to these communities. She supplements her interviews with searchs in science publications for source information

The journal has farily rigid requirements for publishing articles. Prior to writing they request outlines and will provde feedback on them. They have a Word template to submit the outlines. Mogo, as most writers, starts recording her ideas and interview notes, prior to completing the outline. She then manually transfers the key sections into the headline template. When feedback is returned she then manually updates her source notes.

The journal requires extensive sourcing information, both references for interviews and source links for research. This must be done as endnotes in Word, with numeric links in the text. Mogo spends a lot of time cleaning up this information as she forgets to update links or notes. Occassionally she deletes a source with the text as well. It's a tedious part of her work.

This lets us derive two relevant user stories, the first, in short-form is "A user, will export an outline, to satisfy publication pre-planning". It sounds okay.

But the next feature, is about using the various footnote features of MDL, and having them formatted to the target format. This is somewhat awkward to record in a standard user story short-form. Saying, "A user, will use various inline, external, and end notes, because they want to have unified footnotes" is somewhat wordy and confusing. It's why I'm not in favour of strict user story forms. We can instead say, "Mogo wants convenient MDL notes that export to her publication's desired format."

As with last time, I'm going to focus on the low-level MDL features here. The project is not interested in the UI layer yet, which this user would most likely desire. Though possibly not, a lot of content writers don't care what tool they use, and a text editor that fulfills their other needs might be acceptible to some.

Footnotes

Footnotes allow numeric links at the end of sentences to a corresponding entry at the end of the doc. Note however, in MDL they'll be called onl "notes". It's up to renderer to decide how they are rendered. It'd be reasonable for an HTML render to provide a popup block. That popup won't be possible with Markdown backed systems unfortunately.

This may seem like an exotic feature, but that lack of it has caused me some grief in my own writing. Footnotes are common when writing researched material.

MDL provides two options for producing footnotes. Either they are inline², or they are linked³. Let's look at the syntax of that syntax⁴:

Either they are inline^[MDL on Github](https://github.com/mortoray/mdl/), or they are linked^linked.

The inline links are a quick way to reference a source. The linked notes are a way to keep the text clean for editing, and also to provide a block of text for the note. The linked notes are indicated by a ^ followed by a sequence of letters. This is matched later in the document by a defintiion of the note:

^linked The body of a note is regular MDL, allowing _formatting_ and [linking](https://edaqa.com/what_is_programming/).

I apologize if this code samples get out-of-sync with the code of this doc by the time I publish. It's a bit weird to copy-paste part of a document within itself as an example.

This is a development log entry for the MDL Document Processor Project.

1. See, it's not a lie. There was indeed a footnote reference from the introduction to here.
2. MDL on Github
3. The body of a note is regular MDL, allowing formatting and linking.
4. The addition of code blocks was also necessary to show how footnotes work.