add section on backwards compatibility

3 files changed, 67 insertions, 4 deletions

diff --git a/_conclusion.qmd b/_conclusion.qmd
index 446a421..8749612 100644
--- a/_conclusion.qmd
+++ b/_conclusion.qmd
@@ -3,17 +3,60 @@ on observation/reflection/envision discussions an conclusion*
 
 ## Observations from implementation work
 
+Work on implementing `sem-md` uncovered a few observations,
+not specific to the problem of annotations and Markdown
+but regardless considered relevant
+for others reaching at a similar combination of design choices.
+
+### Zero is True in Lua
+
 Programming in Lua has been a new experience
 but with a fairly low learning curve,
 after discovering (after a day of debugging) the oddity,
 compared to dynamically typed languages in general,
 that zero is a true value in a boolean context.
 
+### Backwards compatibility
+
+Some Pandoc features
+are unavailable in older Pandoc releases still in widespread use,
+affecting the coding style of `sem-md`.
+
+As a concrete example,
+the function `pandoc.List:at()` provides a convenient way
+to inspect the contents of a collection of Pandoc elements,
+but the function has only been available since Pandoc 3.5,
+released in November 2024.
+Pandoc is freely available for download from the author's website,
+but is commonly installed via general-purpose software distributions.
+The largest software distribution, Debian
+(supplying both directly to users
+and to the popular distribution Ubuntu, among others),
+currently provides Pandoc 3.1.11.1
+and is not likely to update in the coming 2-3 years,
+partly due to a conservative release cycle of Debian,
+and partly to complex dependency chains of Haskell libraries
+[@Debian2025; @Smedegaard2025].
+
+As a balance between keeping code simple and covering a larger user base,
+the filter implementation isolates calls to `pandoc.List:at()`
+in a local function `TableEmpty()`
+with more tedious fallback code for older releases of Pandoc,
+and resolves once at startup a static boolean `PANDOC_IS_OLD`
+to signal if the legacy code is required.
+When newer Pandoc releases become more widespread,
+uses of `PANDOC_IS_OLD` can be dropped.
+
+Currently only one small function uses this mechanism.
+It has been established mainly for the next phases
+that are expected to rely more heavily on newer libraries where possible
+(see @sec-rdf).
+
 ## Reflections on semantic annotations
 
 *TODO*
 
-## Future works
+## Future works {#sec-future}
 
 The central design choice
 of this project being implemented as a filter
diff --git a/ref.bib b/ref.bib
index 53037b3..8bac1a7 100644
--- a/ref.bib
+++ b/ref.bib
@@ -342,6 +342,24 @@
   urldate = {2025-05-23},
 }
 
+@Online{Smedegaard2025,
+  author       = {Jonas Smedegaard},
+  date         = {2025-05-14},
+  title        = {Re: Bug#1098377: new upstream release available},
+  url          = {https://bugs.debian.org/1098377#10},
+  organization = {Debian},
+  titleaddon   = {[Comment on code issue "new upstream release available"]},
+  urldate      = {2025-05-24},
+}
+
+@Online{Debian2025,
+  date         = {2025-05-17},
+  title        = {Debian Releases},
+  url          = {https://www.debian.org/releases/index.en.html},
+  organization = {Debian},
+  urldate      = {2025-05-24},
+}
+
 @Comment{jabref-meta: databaseType:biblatex;}
 
 @Comment{jabref-meta: fileDirectory-jonas-bastian:/home/jonas/Projects/RUC/LIB/md;}
diff --git a/sem-md/sem-md.lua b/sem-md/sem-md.lua
index 4c7ad01..1b0480d 100644
--- a/sem-md/sem-md.lua
+++ b/sem-md/sem-md.lua
@@ -113,10 +113,12 @@ os.setlocale 'C'
 
 -- flag running with older release of Pandoc
 --
--- Some Pandoc features,
--- notably pandoc.List:at() introduced wit Pandoc 3.5,
--- are unavailable in older Pandoc releases still in widespread use
+-- Some Pandoc features
+-- are unavailable in older Pandoc releases still in widespread use,
 -- due to complexities of keeping Haskell dependencies in sync.
+--
+-- * pandoc.List:at() since Pandoc 3.5
+--
 -- @see <https://bugs.debian.org/1098377>
 local PANDOC_IS_OLD <const> = PANDOC_VERSION[1] < 3
  or (PANDOC_VERSION[1] == 3 and PANDOC_VERSION[2] < 5)