lua-filters: auto-generate docs for `pandoc.layout` module.

2 files changed, 165 insertions, 131 deletions

diff --git a/doc/lua-filters.md b/doc/lua-filters.md
index 751a1f159..4ade18be2 100644
--- a/doc/lua-filters.md
+++ b/doc/lua-filters.md
@@ -5383,6 +5383,9 @@ The results of the call to `callback`.
 
 <!-- END: AUTOGENERATED CONTENT -->
 
+
+<!-- BEGIN: AUTOGENERATED CONTENT for module pandoc.layout -->
+
 # Module pandoc.layout
 
 Plain-text document layouting.
@@ -5391,20 +5394,20 @@ Plain-text document layouting.
 
 ### blankline {#pandoc.layout.blankline}
 
-Inserts a blank line unless one exists already.
+Inserts a blank line unless one exists already. ([Doc])
 
 ### cr {#pandoc.layout.cr}
 
-A carriage return. Does nothing if we\'re at the beginning of a
-line; otherwise inserts a newline.
+A carriage return. Does nothing if we're at the beginning of a
+line; otherwise inserts a newline. ([Doc])
 
 ### empty {#pandoc.layout.empty}
 
-The empty document.
+The empty document. ([Doc])
 
 ### space {#pandoc.layout.space}
 
-A breaking (reflowable) space.
+A breaking (reflowable) space. ([Doc])
 
 ## Functions {#pandoc.layout-functions}
 
@@ -5412,22 +5415,23 @@ A breaking (reflowable) space.
 
 `after_break (text)`
 
-Creates a `Doc` which is conditionally included only if it comes
+Creates a [Doc] which is conditionally included only if it comes
 at the beginning of a line.
 
 An example where this is useful is for escaping line-initial `.`
 in roff man.
 
-Parameters
+Parameters:
 
 `text`
-
 :   content to include when placed after a break (string)
 
-Returns
+Returns:
 
 -   new doc ([Doc])
 
+*Since: 2.18*
+
 ### before_non_blank {#pandoc.layout.before_non_blank}
 
 `before_non_blank (doc)`
@@ -5435,47 +5439,50 @@ Returns
 Conditionally includes the given `doc` unless it is followed by a
 blank space.
 
-Parameters
+Parameters:
 
 `doc`
-
 :   document ([Doc])
 
-Returns
+Returns:
 
 -   conditional doc ([Doc])
 
+*Since: 2.18*
+
 ### blanklines {#pandoc.layout.blanklines}
 
 `blanklines (n)`
 
 Inserts blank lines unless they exist already.
 
-Parameters
+Parameters:
 
 `n`
+:   number of blank lines ([integer]{unknown-type="integer"})
 
-:   number of blank lines (integer)
-
-Returns
+Returns:
 
 -   conditional blank lines ([Doc])
 
+*Since: 2.18*
+
 ### braces {#pandoc.layout.braces}
 
 `braces (doc)`
 
 Puts the `doc` in curly braces.
 
-Parameters
+Parameters:
 
 `doc`
-
 :   document ([Doc])
 
-Returns
+Returns:
+
+-   `doc` enclosed by {}. ([Doc])
 
--   doc enclosed by {}. ([Doc])
+*Since: 2.18*
 
 ### brackets {#pandoc.layout.brackets}
 
@@ -5483,16 +5490,17 @@ Returns
 
 Puts the `doc` in square brackets
 
-Parameters
+Parameters:
 
 `doc`
-
 :   document ([Doc])
 
-Returns
+Returns:
 
 -   doc enclosed by \[\]. ([Doc])
 
+*Since: 2.18*
+
 ### cblock {#pandoc.layout.cblock}
 
 `cblock (doc, width)`
@@ -5500,138 +5508,139 @@ Returns
 Creates a block with the given width and content, aligned
 centered.
 
-Parameters
+Parameters:
 
 `doc`
-
 :   document ([Doc])
 
 `width`
+:   block width in chars ([integer]{unknown-type="integer"})
 
-:   block width in chars (integer)
-
-Returns
+Returns:
 
--   doc, aligned centered in a block with max`width` chars per
+-   doc, aligned centered in a block with max `width` chars per
     line. ([Doc])
 
+*Since: 2.18*
+
 ### chomp {#pandoc.layout.chomp}
 
 `chomp (doc)`
 
 Chomps trailing blank space off of the `doc`.
 
-Parameters
+Parameters:
 
 `doc`
-
 :   document ([Doc])
 
-Returns
+Returns:
 
 -   `doc` without trailing blanks ([Doc])
 
+*Since: 2.18*
+
 ### concat {#pandoc.layout.concat}
 
 `concat (docs[, sep])`
 
 Concatenates a list of `Doc`s.
 
-Parameters
+Parameters:
 
 `docs`
-
-:   list of Docs (`{Doc,...}`)
+:   list of Docs ([\`{Doc,\...}\`]{unknown-type="`{Doc,...}`"})
 
 `sep`
-
 :   separator (default: none) ([Doc])
 
-Returns
+Returns:
 
 -   concatenated doc ([Doc])
 
+*Since: 2.18*
+
 ### double_quotes {#pandoc.layout.double_quotes}
 
 `double_quotes (doc)`
 
 Wraps a `Doc` in double quotes.
 
-Parameters
+Parameters:
 
 `doc`
-
 :   document ([Doc])
 
-Returns
+Returns:
 
 -   `doc` enclosed by `"` chars ([Doc])
 
+*Since: 2.18*
+
 ### flush {#pandoc.layout.flush}
 
 `flush (doc)`
 
 Makes a `Doc` flush against the left margin.
 
-Parameters
+Parameters:
 
 `doc`
-
 :   document ([Doc])
 
-Returns
+Returns:
 
 -   flushed `doc` ([Doc])
 
+*Since: 2.18*
+
 ### hang {#pandoc.layout.hang}
 
 `hang (doc, ind, start)`
 
 Creates a hanging indent.
 
-Parameters
+Parameters:
 
 `doc`
-
 :   document ([Doc])
 
 `ind`
-
-:   indentation width (integer)
+:   indentation width ([integer]{unknown-type="integer"})
 
 `start`
-
 :   document ([Doc])
 
-Returns
+Returns:
 
 -   `doc` prefixed by `start` on the first line, subsequent lines
     indented by `ind` spaces. ([Doc])
 
+*Since: 2.18*
+
 ### inside {#pandoc.layout.inside}
 
 `inside (contents, start, end)`
 
-Encloses a `Doc` inside a start and end `Doc`.
+Encloses a [Doc] inside a start and end [Doc].
 
-Parameters
+Parameters:
 
 `contents`
-
 :   document ([Doc])
 
 `start`
-
 :   document ([Doc])
 
 `end`
-
 :   document ([Doc])
 
-Returns
+Returns:
 
 -   enclosed contents ([Doc])
 
+*Since: 2.18*
+
 ### lblock {#pandoc.layout.lblock}
 
 `lblock (doc, width)`
@@ -5639,35 +5648,36 @@ Returns
 Creates a block with the given width and content, aligned to the
 left.
 
-Parameters
+Parameters:
 
 `doc`
-
 :   document ([Doc])
 
 `width`
+:   block width in chars ([integer]{unknown-type="integer"})
 
-:   block width in chars (integer)
-
-Returns
+Returns:
 
 -   doc put into block with max `width` chars per line. ([Doc])
 
+*Since: 2.18*
+
 ### literal {#pandoc.layout.literal}
 
 `literal (text)`
 
 Creates a `Doc` from a string.
 
-Parameters
+Parameters:
 
 `text`
-
 :   literal value (string)
 
-Returns
+Returns:
+
+-   doc contatining just the literal string ([Doc])
 
--   doc containing just the literal string ([Doc])
+*Since: 2.18*
 
 ### nest {#pandoc.layout.nest}
 
@@ -5675,68 +5685,71 @@ Returns
 
 Indents a `Doc` by the specified number of spaces.
 
-Parameters
+Parameters:
 
 `doc`
-
 :   document ([Doc])
 
 `ind`
+:   indentation size ([integer]{unknown-type="integer"})
 
-:   indentation size (integer)
-
-Returns
+Returns:
 
 -   `doc` indented by `ind` spaces ([Doc])
 
+*Since: 2.18*
+
 ### nestle {#pandoc.layout.nestle}
 
 `nestle (doc)`
 
 Removes leading blank lines from a `Doc`.
 
-Parameters
+Parameters:
 
 `doc`
-
 :   document ([Doc])
 
-Returns
+Returns:
 
 -   `doc` with leading blanks removed ([Doc])
 
+*Since: 2.18*
+
 ### nowrap {#pandoc.layout.nowrap}
 
 `nowrap (doc)`
 
 Makes a `Doc` non-reflowable.
 
-Parameters
+Parameters:
 
 `doc`
-
 :   document ([Doc])
 
-Returns
+Returns:
 
 -   same as input, but non-reflowable ([Doc])
 
+*Since: 2.18*
+
 ### parens {#pandoc.layout.parens}
 
 `parens (doc)`
 
 Puts the `doc` in parentheses.
 
-Parameters
+Parameters:
 
 `doc`
-
 :   document ([Doc])
 
-Returns
+Returns:
 
 -   doc enclosed by (). ([Doc])
 
+*Since: 2.18*
+
 ### prefixed {#pandoc.layout.prefixed}
 
 `prefixed (doc, prefix)`
@@ -5744,36 +5757,37 @@ Returns
 Uses the specified string as a prefix for every line of the inside
 document (except the first, if not at the beginning of the line).
 
-Parameters
+Parameters:
 
 `doc`
-
 :   document ([Doc])
 
 `prefix`
-
 :   prefix for each line (string)
 
-Returns
+Returns:
 
 -   prefixed `doc` ([Doc])
 
+*Since: 2.18*
+
 ### quotes {#pandoc.layout.quotes}
 
 `quotes (doc)`
 
 Wraps a `Doc` in single quotes.
 
-Parameters
+Parameters:
 
 `doc`
+:   document ([Doc])
 
-:   document (Doc)
-
-Returns
+Returns:
 
 -   doc enclosed in `'`. ([Doc])
 
+*Since: 2.18*
+
 ### rblock {#pandoc.layout.rblock}
 
 `rblock (doc, width)`
@@ -5781,21 +5795,21 @@ Returns
 Creates a block with the given width and content, aligned to the
 right.
 
-Parameters
+Parameters:
 
 `doc`
-
-:   document (Doc)
+:   document ([Doc])
 
 `width`
+:   block width in chars ([integer]{unknown-type="integer"})
 
-:   block width in chars (integer)
-
-Returns
+Returns:
 
--   doc, right aligned in a block with max`width` chars per line.
+-   doc, right aligned in a block with max `width` chars per line.
     ([Doc])
 
+*Since: 2.18*
+
 ### vfill {#pandoc.layout.vfill}
 
 `vfill (border)`
@@ -5803,103 +5817,110 @@ Returns
 An expandable border that, when placed next to a box, expands to
 the height of the box. Strings cycle through the list provided.
 
-Parameters
+Parameters:
 
 `border`
-
 :   vertically expanded characters (string)
 
-Returns
+Returns:
 
 -   automatically expanding border Doc ([Doc])
 
+*Since: 2.18*
+
 ### render {#pandoc.layout.render}
 
 `render (doc[, colwidth])`
 
-Render a @\'Doc\'@. The text is reflowed on breakable spaces to
-match the given line length. Text is not reflowed if the line
+Render a [Doc]. The text is reflowed on breakable spaces to match
+the given line length. Text is not reflowed if the line line
 length parameter is omitted or nil.
 
-Parameters
+Parameters:
 
 `doc`
-
-:   document (Doc)
+:   document ([Doc])
 
 `colwidth`
+:   planned maximum line length
+    ([integer]{unknown-type="integer"})
 
-:   planned maximum line length (integer)
-
-Returns
+Returns:
 
 -   rendered doc ([Doc])
 
+*Since: 2.18*
+
 ### is_empty {#pandoc.layout.is_empty}
 
 `is_empty (doc)`
 
 Checks whether a doc is empty.
 
-Parameters
+Parameters:
 
 `doc`
-
 :   document ([Doc])
 
-Returns
+Returns:
 
 -   `true` iff `doc` is the empty document, `false` otherwise.
     (boolean)
 
+*Since: 2.18*
+
 ### height {#pandoc.layout.height}
 
 `height (doc)`
 
 Returns the height of a block or other Doc.
 
-Parameters
+Parameters:
 
 `doc`
-
 :   document ([Doc])
 
-Returns
+Returns:
+
+-   doc height ([integer]{unknown-type="integer"}\|string)
 
--   doc height (integer\|string)
+*Since: 2.18*
 
 ### min_offset {#pandoc.layout.min_offset}
 
 `min_offset (doc)`
 
-Returns the minimal width of a `Doc` when reflowed at breakable
+Returns the minimal width of a [Doc] when reflowed at breakable
 spaces.
 
-Parameters
+Parameters:
 
 `doc`
-
 :   document ([Doc])
 
-Returns
+Returns:
 
--   minimal possible width (integer\|string)
+-   minimal possible width
+    ([integer]{unknown-type="integer"}\|string)
+
+*Since: 2.18*
 
 ### offset {#pandoc.layout.offset}
 
 `offset (doc)`
 
-Returns the width of a `Doc` as number of characters.
+Returns the width of a [Doc] as number of characters.
 
-Parameters
+Parameters:
 
 `doc`
-
 :   document ([Doc])
 
-Returns
+Returns:
+
+-   doc width ([integer]{unknown-type="integer"}\|string)
 
--   doc width (integer\|string)
+*Since: 2.18*
 
 ### real_length {#pandoc.layout.real_length}
 
@@ -5909,15 +5930,16 @@ Returns the real length of a string in a monospace font: 0 for a
 combining character, 1 for a regular character, 2 for an East
 Asian wide character.
 
-Parameters
+Parameters:
 
 `str`
-
 :   UTF-8 string to measure (string)
 
-Returns
+Returns:
+
+-   text length ([integer]{unknown-type="integer"}\|string)
 
--   text length (integer\|string)
+*Since: 2.18*
 
 ### update_column {#pandoc.layout.update_column}
 
@@ -5926,21 +5948,28 @@ Returns
 Returns the column that would be occupied by the last laid out
 character.
 
-Parameters
+Parameters:
 
 `doc`
-
 :   document ([Doc])
 
 `i`
+:   start column ([integer]{unknown-type="integer"})
+
+Returns:
+
+-   column number ([integer]{unknown-type="integer"}\|string)
+
+*Since: 2.18*
 
-:   start column (integer)
+## Types {#pandoc.layout-types}
 
-Returns
+### Doc {#type-pandoc.Doc}
 
--   column number (integer\|string)
+See the description [above][Doc].
+
+<!-- END: AUTOGENERATED CONTENT -->
 
-[Doc]: #type-doc
 
 <!-- BEGIN: AUTOGENERATED CONTENT for module pandoc.scaffolding -->
 
diff --git a/tools/update-lua-module-docs.lua b/tools/update-lua-module-docs.lua
index a13ffdadc..3680c4640 100644
--- a/tools/update-lua-module-docs.lua
+++ b/tools/update-lua-module-docs.lua
@@ -264,6 +264,11 @@ local function render_type (name, level, modulename)
     end
   end
 
+  if name == 'Doc' then
+    local header_id = 'type-' .. nameprefix .. '.' .. name
+    return {Header(level, name, {header_id})} ..
+      Blocks{Para {"See the description ", Link("above", "#type-doc"), "."}}
+  end
   local header_id = 'type-' .. nameprefix .. '.' .. name
   known_types[name] = header_id
   return {Header(level, name, {header_id})} ..