From 6b462e59332242c18ea38a721ae672b88f33d621 Mon Sep 17 00:00:00 2001
From: Albert Krewinkel <albert@zeitkraut.de>
Date: Sat, 6 Nov 2021 11:00:26 +0100
Subject: Lua: allow to pass custom reader options to `pandoc.read`

Reader options can now be passed as an optional third argument to
`pandoc.read`. The object can either be a table or a ReaderOptions value
like `PANDOC_READER_OPTIONS`. Creating new ReaderOptions objects is
possible through the new constructor `pandoc.ReaderOptions`.

Closes: #7656
---
 doc/lua-filters.md | 42 ++++++++++++++++++++++++++++++++++++++----
 1 file changed, 38 insertions(+), 4 deletions(-)

(limited to 'doc')

diff --git a/doc/lua-filters.md b/doc/lua-filters.md
index e9a121f50..ba5f58120 100644
--- a/doc/lua-filters.md
+++ b/doc/lua-filters.md
@@ -2742,7 +2742,33 @@ format, and functions to filter and modify a subtree.
 [`sha1`]{#pandoc.sha1}
 
 :   Alias for [`pandoc.utils.sha1`](#pandoc.utils.sha1)
-    (DEPRECATED).
+    (DEPRECATED, use `pandoc.utils.sha1` instead).
+
+## Other constructors
+
+[`ReaderOptions (opts)`]{#pandoc.readeroptions}
+
+:   Creates a new [ReaderOptions] value.
+
+    Parameters
+
+    `opts`:
+    :   Either a table with a subset of the properties of a
+        [ReaderOptions] object, or another ReaderOptions object.
+        Uses the defaults specified in the manual for all
+        properties that are not explicitly specified. Throws an
+        error if a table contains properties which are not present
+        in a ReaderOptions object. ([ReaderOptions]|table)
+
+    Returns: new [ReaderOptions] object
+
+    Usage:
+
+        -- copy of the reader options that were defined on the command line.
+        local cli_opts = pandoc.ReaderOptions(PANDOC_READER_OPTIONS)
+
+        -- default reader options, but columns set to 66.
+        local short_colums_opts = pandoc.ReaderOptions {columns = 66}
 
 ## Helper functions
 
@@ -2815,17 +2841,23 @@ Returns: the transformed inline element
 
 ### read {#pandoc.read}
 
-`read (markup[, format])`
+`read (markup[, format[, reader_options]])`
 
 Parse the given string into a Pandoc document.
 
 Parameters:
 
 `markup`:
-:   the markup to be parsed
+:   the markup to be parsed (string)
 
 `format`:
-:   format specification, defaults to `"markdown"`.
+:   format specification, defaults to `"markdown"` (string)
+
+`reader_options`:
+:   options passed to the reader; may be a ReaderOptions object or
+    a table with a subset of the keys and values of a
+    ReaderOptions object; defaults to the default values
+    documented in the manual. ([ReaderOptions]|table)
 
 Returns: pandoc document
 
@@ -2838,6 +2870,8 @@ Usage:
     -- The inline element in that block is an `Emph`
     assert(block.content[1].t == "Emph")
 
+[ReaderOptions]: #type-readeroptions
+
 # Module pandoc.utils
 
 This module exposes internal pandoc functions and utility
-- 
cgit v1.2.3