improve formal comments

1 files changed, 35 insertions, 7 deletions

diff --git a/_extensions/ruc-play/semantic-markdown/semantic-markdown.lua b/_extensions/ruc-play/semantic-markdown/semantic-markdown.lua
index b4c1028..70f4970 100644
--- a/_extensions/ruc-play/semantic-markdown/semantic-markdown.lua
+++ b/_extensions/ruc-play/semantic-markdown/semantic-markdown.lua
@@ -122,29 +122,57 @@ end
 
 --- Statements - process inline RDF statements
 ---
---- Track enclosure changes and process relevant embedded statements
---- for each Inlines object in a Pandoc Abstract Syntax Tree (AST).
+--- Locate and extract ontological annotations
+--- within a [Block] element of a Pandoc Abstract Syntax Tree (AST).
+---
+--- Markup for ontological annotations is an extension to Markdown
+--- using similar syntax as hypermedia annotations,
+--- but listing RDFa [CURIEs] in a braced enclosure.
 ---
 --- ```ASCII-art
 --- Simple ontological annotation:
 --- "A [map]{foaf:depiction} is not the territory"
 ---    |   ||\~~~~~~~~~~~~/|
----    a   bc    curie     d
+---    a   bc    CURIEa    d
 ---
 --- Nested and mixed-use annotations:
 --- ["[Ceci]{foaf:depiction} n'est pas une pipe"]{lang=fr dc:Text}
 --- | |    ||\~~~~~~~~~~~~/|                    ||        \~~~~~/|
---- a a1   |c1   curie1    d1                   bc         curie d
+--- a a1   |c1   CURIEa    d1                   bc        CURIEb d
 ---        b1
 ---
+--- Chained hypermedia and ontological annotations:
+--- "A [map](https://osm.org/){foaf:depiction} is not the territory"
+---    |   ||                ||\~~~~~~~~~~~~/|
+---    a   be                fc    CURIEa    d
+---
 --- Legend:
----  a-b, a1-b1: braced enclosure
----  c-d, c1-d1: bracketed enclosure
+---  a-b: braceted enclosure around content
+---  c-d: bracketed enclosure around ontological or other annotation
+---  e-f: parenthesized enclosure around hypermedia annotation
 --- ```
 ---
+--- Ontological annotations are parsed and reorganised
+--- using the following algorithm:
+---
+---  1. locate pairs of bracketed text and braced text
+---     either adjacent or separated by parenthesized text,
+---     where braced text contains one or more [CURIEs]
+---  2. for each pair,
+---    1. add CURIEs in braced text to metadata
+---    2. add positions of brackets to metadata
+---    3. delete CURIEs
+---    4. delete braced enclosure if now structurally empty
+---    5. delete brackets if now unannotated
+---
+--- The implementation is inspired by Pandoc [issue#6038].
+---
 --- @param inlines  Markdown with semantic annotations as Inlines
 --- @returns        Markdown stripped of semantic annotations as Inlines
---- @see <https://pandoc.org/lua-filters.html#type-inline>
+--- @see [Block]: <https://pandoc.org/lua-filters.html#type-block>
+--- @see [CURIEs]: <https://www.w3.org/TR/rdfa-core/#s_curies>
+--- @see [issue#6038]: <https://github.com/jgm/pandoc/issues/6038>
+-- TODO: maybe instead as step #5 add/reuse hypermedia anchor
 function Statements (block)
 
   -- flags for enclosing stages