add section on Pandoc APIs

2 files changed, 44 insertions, 1 deletions

diff --git a/_filter.qmd b/_filter.qmd
index 1384b32..5851f5a 100644
--- a/_filter.qmd
+++ b/_filter.qmd
@@ -15,6 +15,8 @@ of priority for this project is to improve existing tools
 rather than implement parallel competing ones,
 despite the latter potentially being easier to do
 or lead to a simpler product.
+Pandoc offers an API specifically for custom-implementing a source format
+(see @sec-pandoc-apis).
 In @sec-pandoc-complex
 
 *FIXME: tie pieces together, and continue from there
diff --git a/_pandoc.qmd b/_pandoc.qmd
index 3703707..95ba8e3 100644
--- a/_pandoc.qmd
+++ b/_pandoc.qmd
@@ -67,6 +67,9 @@ for enabling semantic annotations in Markdown-based authoring workflows.
 
 ## An AST in the spirit of Markdown
 
+The data processing workflow of Pandoc
+is shaped in the spirit of Markdown.
+
 The Pandoc AST evolved from the needs of tracking Markdown.
 It mainly keeps track of structure of content,
 and only to a limited extend handles layout:
@@ -74,9 +77,47 @@ import from layout-rich document formats reduces such information,
 and export to layout-rich document formats
 use templates to effectively impose a normalized style.
 
+*TODO: dot diagram  
+"import -> AST, { AST, template } -> export"  
+workflow components*
+
+## APIs to supplant or extend workflow components {#sec-pandoc-apis}
+
+Pandoc is designed with extension in mind,
+not only in its programming design
+where most code is externally exposed as public libraries
+reusable by third-party projects,
+but also at runtime through several APIs.
+
+Styling (templates), import (parsing) and export (serialising)
+are overridable.
+The styling of the target document is isolated as one or more templates.
+Parsing of source content and rendering of target document
+are both isolated as sets of Reader and Writer routines.
+All three --
+template, Reader and Writer --
+can be superseded at runtime,
+either by passing command-line options
+or by declaring options in document-wide metadata in the source file
+(for the source text formats supporting that).
+
+*TODO: dot diagram  
+"**custom** import -> AST, { AST, **custom** template } -> **custom** export"  
+customizable workflow components*
+
+The AST itself is also exposed as a so-called filter API,
+allowing for intervening in the data processing workflow
+after source import and before target export,
+by directly mangling the AST.
+
+*TODO: dot diagram  
+"import -> AST -> **filter**; { **filter**, template } -> export"  
+workflow components with a filter applied*
+
 ## Complex features {#sec-pandoc-complex}
 
-Some functionalities of Pandoc hook into multiple places of its workflow.
+Some functionalities of Pandoc hook into multiple components
+of its workflow.
 
 An example of a complex functionality is citation handling.
 The source text contains citation annotations,