MDL Log (6 Part Series)
Progress continues on my parser . I’ve done a lot of restructuring lately and added a few new important features. Continue paragraphs is the one that required the most effort. It's a parser feature, at the high level this provides for embedded lists and extended blockquotes.
Two recent articles required this feature:
- This one about soft skills in interviews had embedded lists. It was quite a challenge to support these. I first attempted special list support, then abandoned it as too complicated.
- An article about saturated fats needed a two paragraph comment (an “aside” block). It didn’t strictly need this, but as it’s a structure that comes up often it felt like a good time to support it.
The continuation feature supports both.
As I based MDL on markdown syntax, new paragraphs create new blocks of text. As the articles show, there are few situations where this isn’t desired. A continuation groups a block with the previous one.
Whitespace indentation controls the continuations. A longer indent groups the block to the previous block. This example is from the saturated fats article.
@Aside In fairness, the WHO is heavily influenced by politics, lobbying, and cultural norms. It’d be impossible for them to publish that differs too much from current trends. Though I’m concerned by a followup report^whoup in 2016. It’s a significant meta-study, but appears to have hand-picked studies supporting their cause. It makes little mention of contrary studies, nor low-carb trends, still makes that non-causal leap to heart disease, and fails to mention the differentiation of LDL classes. There is good information in there, but it feels like politics have kept it biased. We can’t ignore the types of diets that WHO is analyzing as well. They are focused on popular diets, which include a lot of animal fats, as well as industrially refined products. Their consumer level recommendations^whohealth for a healthy-diet include nuts, seeds, and oils which contain a lot of saturated fat. Switching from one source to the other probably has a positive health impact — too bad that advice contradicts their own heart-diet research.
The indent on the second paragraph associates it with the previous paragraph. The initial paragraph has an
@Aside annotation — is more of a comment that part of the flow of text. These get converted to blockquotes on output. I wanted to ensure that the two paragraphs are part of the same blockquote, instead two separate blockquotes. This makes it easier to style them correctly.
The same feature is used to create nested lists.
- Outer A - Inner I - Further In 1 - Further In 2 - Inner 2 - Outer B - Outer C
Which renders as:
- Outer A
- Inner I
- Further In 1
- Further In 2
- Inner 2
- Inner I
- Outer B
- Outer C
The indented lists are combined with the list item above them. This is the standard continuation rule, it is not a special rule for lists. Because this isn’t a special rule, it allows for other types of blocks to be used in a list, not only plain text.
You may have seen that I experimented with type annotations. Though I think it’s rough still, I persisted, first by figuring out how to upgrade to Python 2.8. The now partially annotated helps a lot! Refactoring the document tree became possible, and I easily found many bugs.
The code, and structure of the document tree, is in heavy flux. Until I have enough examples of all the documents I want to do, I won’t be stabilizing anything. This also means no automated test cases for now -- though I have several minor sample documents I frequently use.
I am trying to use MDL for all my documents now. This one, and the last four I published, were written in MDL and exported to HTML and Markdown.