add workflow diagrams

7 files changed, 144 insertions, 9 deletions

diff --git a/Makefile b/Makefile
index 499658a..83b764d 100644
--- a/Makefile
+++ b/Makefile
@@ -19,6 +19,8 @@ PANDOC = pandoc --from commonmark
 
 SYNTAX_DIAGRAMS := $(patsubst %.py,%.svg,$(wildcard def_*.py))
 
+WORKFLOW_DIAGRAMS := $(patsubst %.cwl,%.svg,$(wildcard workflow/phase*.cwl))
+
 RAPPER = rapper -i rdfa
 
 #RAPPER += -f relativeURIs
@@ -35,11 +37,14 @@ NS += ov=http://open.vocab.org/terms/
 
 RAPPER += $(foreach s,$(NS),$(let a b,$(subst =, $(),$s), -f 'xmlns:$a="$b"'))
 
-_site/report.pdf: $(wildcard _*.qmd) $(SYNTAX_DIAGRAMS)
+_site/report.pdf: $(wildcard _*.qmd) $(SYNTAX_DIAGRAMS) $(WORKFLOW_DIAGRAMS)
 
 $(SYNTAX_DIAGRAMS): %.svg: %.py
 	python3 $<
 
+$(WORKFLOW_DIAGRAMS): %.svg: %.cwl
+	cwltool --print-dot $< | gvpr -f workflow/rotate.gvpr | dot -Tsvg > $@
+
 check: $(DIFFTESTS:%=check-%)
 	luacheck --quiet $(FILTER)
 
diff --git a/_conclusion.qmd b/_conclusion.qmd
index 052e07b..d34481b 100644
--- a/_conclusion.qmd
+++ b/_conclusion.qmd
@@ -13,20 +13,34 @@ Implement renderers that makes use of Markdown with embedded annotations.
 Beyond both authoring and rendering of annotations,
 several already emerging use cases may be aided by this work.
 
-### Rendering of annotations {#sec-rdf}
+### Further annotation processing {#sec-rdf}
 
 *FIXME: rewrite and reduce
 to describe concrete future works
-of rendering RDFa in HTML and XMP in PDF.*
+of extracting RDF and and rendering as RDFa and XMP.*
 
-* output format extension to generate PDF
-  * read semantic metadata from Pandoc YAML document header
+1. Restore non-annotated Markdown structure
+  * strip annotations from Markdown structure
+2. extract annotations as document-wide metadata
+  * extract annotations from Markdown structure
   * structure semantic metadata as RDF triples
-  * append RDF triples serialized as part of XMP metadata in PDF
-* output format extension to generate web page
+  * Markdown output: save RDF triples serialized as turtle
+    in YAML document header
+  * PDF output: embed RDF triples serialized as XMP
+    in document-wide XMP
+3. convert annotation to target-specific annotations
   * read semantic metadata from Pandoc YAML document header
   * structure semantic metadata as RDF triples
-  * append RDF triples serialized as RDFa
+  * Markdown output: preserve annotations,
+    and also save RDF triples serialized as turtle
+    in YAML document header
+  * HTML output: embed RDF triples serialized as RDFa
+    inline at text strings.
+  * PDF output: embed RDF triples serialized as XMP
+    inline at text strings.
+See @fig-phases
+
+![Implementation levels.](workflow/phases.svg){#fig-phases}
 
 Some document containers support metadata
 expressed in some serialization of the abstract language RDF,
diff --git a/_intro.qmd b/_intro.qmd
index 30f086c..a15883a 100644
--- a/_intro.qmd
+++ b/_intro.qmd
@@ -77,7 +77,10 @@ Annotations are metadata, not directly part of the content.
 Consequently, the simplest way
 to correctly process markdown with semantic text annotations
 is to omit the annotations altogether,
-rendering as if they had not been applied at all.
+rendering as if they had not been applied at all,
+as illustrated in @fig-phase1.
+
+![Simplest implementation level.](workflow/phase1.svg){#fig-phase1}
 
 More advanced processing may optionally embed semantic text annotations
 as semantic document annotations, i.e. embed as document-wide metadata.
@@ -88,6 +91,7 @@ for embedded hypermedia markup like links and anchors.
 
 This project aims at the simplest processing level as described above,
 due to the limited time of the project.
+(further processing is discussed in @sec-rdf).
 
 ## Maintaining usability and interoperability
 
diff --git a/workflow/pandoc-filter-tool.cwl b/workflow/pandoc-filter-tool.cwl
new file mode 100755
index 0000000..a433081
--- /dev/null
+++ b/workflow/pandoc-filter-tool.cwl
@@ -0,0 +1,37 @@
+#!/usr/bin/env cwl-runner
+
+cwlVersion: v1.0
+class: CommandLineTool
+label: Pandoc filter
+doc: Transforms Pandoc AST
+$namespaces:
+  dc: http://purl.org/dc/elements/1.1/
+  license: https://spdx.org/licenses/
+
+inputs:
+  input_file:
+    type: File
+    inputBinding:
+      position: 1
+
+outputs:
+  html_with_rdfa:
+    type: File
+    outputBinding:
+      glob: output
+  latex_with_xmp:
+    type: File
+    outputBinding:
+      glob: output
+  markdown:
+    type: File
+    outputBinding:
+      glob: output
+stdout: output
+
+baseCommand: pandoc
+arguments:
+- --output=output.${output_format}
+dc:license: license:GPL-3.0-or-later
+dc:rights: Copyright 2025, Jonas Smedegaard <dr@jones.dk>
+stdin: $(inputs.file1.path)
diff --git a/workflow/phase1.cwl b/workflow/phase1.cwl
new file mode 100755
index 0000000..f531e69
--- /dev/null
+++ b/workflow/phase1.cwl
@@ -0,0 +1,25 @@
+#!/usr/bin/env cwl-runner
+
+cwlVersion: v1.0
+class: Workflow
+$namespaces:
+  dc: http://purl.org/dc/elements/1.1/
+  license: https://spdx.org/licenses/
+
+inputs:
+  annotated_markdown: File
+
+outputs:
+  plain_markdown:
+    type: File
+    outputSource: strip/markdown
+
+steps:
+  strip:
+    in:
+      input_file: annotated_markdown
+    run: pandoc-filter-tool.cwl
+    out:
+    - markdown
+dc:license: license:GPL-3.0-or-later
+dc:rights: Copyright 2025, Jonas Smedegaard <dr@jones.dk>
diff --git a/workflow/phases.cwl b/workflow/phases.cwl
new file mode 100755
index 0000000..95df658
--- /dev/null
+++ b/workflow/phases.cwl
@@ -0,0 +1,47 @@
+#!/usr/bin/env cwl-runner
+
+cwlVersion: v1.0
+class: Workflow
+$namespaces:
+  dc: http://purl.org/dc/elements/1.1/
+  license: https://spdx.org/licenses/
+
+inputs:
+  annotated_markdown: File
+
+outputs:
+  annotated_html:
+    type: File
+    outputSource: convert/html_with_rdfa
+  annotated_pdf:
+    type: File
+    outputSource: convert/latex_with_xmp
+  markdown_with_metadata:
+    type: File
+    outputSource: extract/markdown
+  plain_markdown:
+    type: File
+    outputSource: strip/markdown
+
+steps:
+  convert:
+    in:
+      input_file: annotated_markdown
+    run: pandoc-filter-tool.cwl
+    out:
+    - html_with_rdfa
+    - latex_with_xmp
+  extract:
+    in:
+      input_file: annotated_markdown
+    run: pandoc-filter-tool.cwl
+    out:
+    - markdown
+  strip:
+    in:
+      input_file: annotated_markdown
+    run: pandoc-filter-tool.cwl
+    out:
+    - markdown
+dc:license: license:GPL-3.0-or-later
+dc:rights: Copyright 2025, Jonas Smedegaard <dr@jones.dk>
diff --git a/workflow/rotate.gvpr b/workflow/rotate.gvpr
new file mode 100644
index 0000000..33ca779
--- /dev/null
+++ b/workflow/rotate.gvpr
@@ -0,0 +1,3 @@
+// rotate rendering direction from default top → down to left → right
+BEG_G { $G.rankdir = "LR" }
+END_G { $O = $G; }