From 8f185d6a88b13eea2f5fdfb6bc34f197b40fb121 Mon Sep 17 00:00:00 2001
From: Jonas Smedegaard <dr@jones.dk>
Date: Sat, 17 May 2025 16:34:36 +0200
Subject: add chapter on Markdown and annotation

---
 _markdown.qmd | 65 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 65 insertions(+)
 create mode 100644 _markdown.qmd

(limited to '_markdown.qmd')

diff --git a/_markdown.qmd b/_markdown.qmd
new file mode 100644
index 0000000..6966e99
--- /dev/null
+++ b/_markdown.qmd
@@ -0,0 +1,65 @@
+Markdown consists of blocks of content,
+optionally prepended a set of Metadata blocks.
+Visually, this can be described using a syntax diagram
+where the possible order of elements are laid out
+like trains on rails,
+as seen in @fig-def-Markdown and @fig-def-Block.
+
+![Markdown](def_Markdown.svg){#fig-def-Markdown}
+
+![Block](def_Block.svg){#fig-def-Block}
+
+Reading order matter.
+These syntax diagrams should be read left-to-right and top-to-bottom,
+also at places with choice --
+e.g. the block type "Header" should be tried before "Paragraph".
+since (as elaborated below) a paragraph begins with any words,
+including the initial words defitive for other block types.
+In other words,
+these syntax diagrams do not reflect the more common EBNF grammars,
+but instead a parsing expression grammar [@Ford2004],
+because context-free grammars are unlikely to cover Markdown
+[@MacFarlane2014].
+The grammar is included as [Appendix @sec-def-peg].
+
+The most common content block is a paragraph,
+which consists of lines of space-delimited words
+followed by two or more line breaks.
+
+![Paragraph](def_Paragraph.svg){#fig-def-Paragraph}
+
+Words are sets of printable characters
+(including punctuation and other printable characters).
+they can be styled
+(@fig-def-StyledWords),
+have a hyperlink attached
+(@fig-def-LinkedWords)
+and have annotations attached
+(@fig-def-AnnotatedWords).
+
+![StyledWords](def_StyledWords.svg){#fig-def-StyledWords}
+
+![LinkedWords](def_LinkedWords.svg){#fig-def-LinkedWords}
+
+![AnnotatedWords](def_AnnotatedWords.svg){#fig-def-AnnotatedWords}
+
+![PlainWords](def_PlainWords.svg){#fig-def-PlainWords}
+
+Other content blocks include a header
+consisting of words
+(@fig-def-Header),
+and a list consisting of list items,
+each containing a block
+(@fig-def-List).
+
+![Header](def_Header.svg){#fig-def-Header}
+
+![List](def_List.svg){#fig-def-List}
+
+Yet other content blocks and inline types exist.
+Those are omitted in this description,
+which is limited to the comonents affected
+by extending the Markdown language with additional types of annotation.
+
+Syntax diagrams for additional Markdown components are included
+as [Appendix @sec-def-dia].
-- 
cgit v1.2.3