provide misparsing example

1 files changed, 50 insertions, 5 deletions

diff --git a/_pandoc.qmd b/_pandoc.qmd
index 72fc6bc..14726cc 100644
--- a/_pandoc.qmd
+++ b/_pandoc.qmd
@@ -209,10 +209,55 @@ that API effectively is discouraged.
 Since a core principle of Markdown is
 to treat unknown markup as content,
 a viable alternative for an extended Markdown format
-is to use a simpler Markdown Reader and then "finish up" the parsing
-in a filter.
+is to use use the regular Markdown Reader
+and then "finish up" the parsing in a filter.
+
+As an example, this Semantic Markdown text:
+
+```markdown
+[This]{:depiction} is not [a pipe]{:depiction}.
+```
+
+...should ideally become this as regular Markdown:
+
+```markdown
+This is not a pipe.
+```
+
+...but misparsed as regular Markdown would result in this Pandoc AST:
+
+* `Pandoc`
+  * `Para`
+    * `Str` "[This]{:depiction}"
+    * `Space`
+    * `Str` "is"
+    * `Space`
+    * `Str` "not"
+    * `Space`
+    * `Str` "[a"
+    * `Space`
+    * `Str` "pipe]{:depiction"
+    * `Space`
+    * `Str` "#the_object}."
+
+...where a filter would then look for `{...}`
+and reorganise the AST to become this:
+
+* `Pandoc`
+  * `Para`
+    * `Str` "This"
+    * `Space`
+    * `Str` "is"
+    * `Space`
+    * `Str` "not"
+    * `Space`
+    * `Str` "a"
+    * `Space`
+    * `Str` "pipe."
+
+The first `Str` simply needed its content reduced to "This".
+The trailing part is more involved, however,
+since it involves three `Str` and two `Space` elements.
+
 This is the approach chosen for this project,
 as covered next in @sec-filter.
-
-*TODO: also mention (reiterate) when wrapping up above
-that the filter API is more cumbersome*