---
title: |
 Processing Semantic Text Annotations
 in Markdown
subtitle: Semantic Markdown Implemented as a Pandoc Filter

date: 2025-05-27

toc-depth: 2

format:
  stylish-report-pdf:
    pdfversion: "2.0"
    pdfstandard: [A-4f, UA-2]

# generate Well-Tagged PDF using tag tagging
# requires documentmetadatasupport 1.0n (2025-03-25)
#    tagging: on
# else generate Well-Tagged PDF using latest testphase components
# <https://latex3.github.io/tagging-project/documentation/prototype-usage-instructions>
# requires documentmetadatasupport 1.0k (2024-12-21)
    pdftestphase: latest

# fail on error generating Well-Tagged PDF
#    pdftestphasestrict: true

# debugging of Well-Tagged PDF
#    pdfdebug: ["para"]

metadata-files:
  - _actors.yml
keywords:
  - Markdown
  - Commonmark
  - Lua
  - pandoc
  - text editor
  - semantic publishing

link-citations: true
bibliography: ref.bib
csl: apa
resource-path:
- /usr/share/citation-style-language/styles

filters:
  - en2em
  - nobreaks
  - include-code-files

include-in-header:
# add alt text to embedded image, to aid non-visual rendering
- text: |
    \renewcommand{\doclicenseImage}[1][]{%
      \setkeys{doclicense}{#1}
      \href{\doclicenseURL}{%
        \includegraphics[
          alt=\doclicenseText%
          width=\doclicense@imagewidth%
        ]{\doclicenseImageFileName}%
      }
    }
# fix british spelling of "licence", and append link to published source
- text: |
    \makeatletter
    \@namedef{doclicense@lang@word@license}{ licence.\\
    Source is available at
    \href{https://source.jones.dk/sem-md}{https://source.jones.dk/sem-md}
    and decentrally with
    \href{https://app.radicle.xyz/nodes/seed.radicle.garden/rad:z3ckfAxH326pgPFKe7rDYJ4mxBoWo}{%
      rad:z3ckfAxH326pgPFKe7rDYJ4mxBoWo}%
    }
    \makeatother

#keep-tex: true
---

# Abstract

*FIXME and TODO notes in cursive text (like this)
are editorial notes not intended for inclusion in the final delivery.*

# Introduction

{{< include _intro.qmd >}}

# Markdown syntax for annotations

{{< include _markdown.qmd >}}

# How Pandoc processes Markdown

{{< include _pandoc.qmd >}}

# Extending Pandoc with a filter

{{< include _filter.qmd >}}

# Evaluation

{{< include _evaluation.qmd >}}

# Discussion and Conclusion

{{< include _conclusion.qmd >}}

# Bibliography {.appendix}

\begingroup
\raggedright
::: {#refs}
:::
\endgroup

\appendix

# Pandoc filter `semantic-markdown` {.appendix}

```{.lua include="_extensions/ruc-play/semantic-markdown/semantic-markdown.lua" code-line-numbers="true"}
```

# Markdown syntax as PEG {.appendix #sec-def-peg}

```{.peg include="syntax/def.peg" code-line-numbers="true"}
```

# Markdown syntax as syntax diagrams {.appendix #sec-def-dia}

{{< include _syntax.qmd >}}