Lua: add pandoc.scaffolding.Writer (#8377)

This can be used to reduce boilerplate in custom writers.

2 files changed, 70 insertions, 0 deletions

diff --git a/doc/custom-writers.md b/doc/custom-writers.md
index aa2796d00..0cedec7d7 100644
--- a/doc/custom-writers.md
+++ b/doc/custom-writers.md
@@ -126,6 +126,63 @@ end
 
 [Lua filters documentation]: https://pandoc.org/lua-filters.html
 
+## Reducing boilerplate with `pandoc.scaffolding.Writer`
+
+The `pandoc.scaffolding.Writer` structure is a custom writer scaffold
+that serves to avoid common boilerplate code when defining a custom
+writer. The object can be used as a function and allows to skip details
+like metadata and template handling, requiring only the render functions
+for each AST element type.
+
+The value of `pandoc.scaffolding.Writer` is a function that should
+usually be assigned to the global `Writer`:
+
+``` lua
+Writer = pandoc.scaffolding.Writer
+```
+
+The render functions for Block and Inline values can then be added
+to `Writer.Block` and `Writer.Inline`, respectively. The functions
+are passed the element and the WriterOptions.
+
+``` lua
+Writer.Inline.Str = function (str)
+  return str.text
+end
+Writer.Inline.SoftBreak = function (_, opts)
+  return opts.wrap_text == "wrap-preserve"
+    and cr
+    or space
+end
+Writer.Inline.LineBreak = cr
+
+Writer.Block.Para = function (para)
+  return {Writer.Inlines(para.content), pandoc.layout.blankline}
+end
+```
+
+The render functions must return a string, a pandoc.layout *Doc*
+element, or a list of such elements. In the latter case, the
+values are concatenated as if they were passed to
+`pandoc.layout.concat`. If the value does not depend on the input,
+a constant can be used as well.
+
+The tables `Writer.Block` and `Writer.Inline` can be used as
+functions; they apply the right render function for an element of
+the respective type. E.g., `Writer.Block(pandoc.Para 'x')` will
+delegate to the `Writer.Para` render function and will return the
+result of that call.
+
+Similarly, the functions `Writer.Blocks` and `Writer.Inlines` can
+be used to render lists of elements, and `Writer.Pandoc` renders
+the document's blocks.
+
+All predefined functions can be overwritten when needed.
+
+The resulting Writer uses the render functions to handle metadata
+values and converts them to template variables. The template is
+applied automatically if one is given.
+
 # Classic style
 
 A writer using the classic style defines rendering functions for
diff --git a/doc/lua-filters.md b/doc/lua-filters.md
index 90daa1365..6435280e6 100644
--- a/doc/lua-filters.md
+++ b/doc/lua-filters.md
@@ -5167,6 +5167,19 @@ Returns
 
 [Doc]: #type-doc
 
+# Module pandoc.scaffolding
+
+Scaffolding for custom writers.
+
+## Writer {#pandoc.scaffolding.writer}
+
+A structure to be used as a `Writer` function; the construct
+handles most of the boilerplate, expecting only render functions
+for all AST elements. See the documentation for custom writers for
+details.
+
+
+
 # Module pandoc.template
 
 Handle pandoc templates.