Merge branch 'master' into groff_reader

3 files changed, 441 insertions, 9 deletions

diff --git a/doc/lua-filter-types-and-objects.md b/doc/lua-filter-types-and-objects.md
new file mode 100644
index 000000000..f6d11a928
--- /dev/null
+++ b/doc/lua-filter-types-and-objects.md
@@ -0,0 +1,396 @@
+% Lua filter types and objects
+% Albert Krewinkel
+% Oct 6, 2018
+
+## Pandoc
+
+blocks
+:   document content ([list] of [blocks])
+
+meta
+:   document meta information ([Meta] object)
+
+
+## Meta
+
+Meta information on a document; string-indexed collection of [meta
+values](#metavalue). This is represented as a string-indexed table containing
+[meta values](#MetaValue).
+
+
+## MetaValue
+
+Document meta information items.
+
+### MetaBlocks
+
+blocks
+:   a list of blocks usable as meta value ([list] of [blocks])
+
+
+## Block
+
+### BlockQuote
+
+A block quote element
+
+content:
+:   block content ([list] of [blocks])
+
+tag, t
+:   the literal `BlockQuote` (string)
+
+### BulletList
+
+A bullet list
+
+content
+:   list of items ([list] of [blocks])
+
+tag, t
+:   the literal `BlockQuote` (string)
+
+### CodeBlock
+
+Block of code.
+
+text
+:   code string (string)
+
+attr
+:   element attributes (Attr)
+
+identifier
+:   alias for `attr.identifier` (string)
+
+classes
+:   alias for `attr.classes` ([list] of strings)
+
+attributes
+:   alias for `attr.attributes` ([attributes])
+
+tag, t
+:   the literal `CodeBlock` (string)
+
+### DefinitionList
+
+Definition list, containing terms and their explanation.
+
+content
+:   list of items
+
+tag, t
+:   the literal `DefinitionList` (string)
+
+### Div
+
+Generic block container with attributes
+
+content
+:   block content ([list] of [blocks])
+
+attr
+:   element attributes (Attr)
+
+identifier
+:   alias for `attr.identifier` (string)
+
+classes
+:   alias for `attr.classes` ([list] of strings)
+
+attributes
+:   alias for `attr.attributes` ([attributes])
+
+tag, t
+:   the literal `Div` (string)
+
+### Header
+
+Creates a header element.
+
+level
+:   header level (integer)
+
+content
+:   inline content ([list] of [inlines])
+
+attr
+:   element attributes (Attr)
+
+identifier
+:   alias for `attr.identifier` (string)
+
+classes
+:   alias for `attr.classes` ([list] of strings)
+
+attributes
+:   alias for `attr.attributes` ([attributes])
+
+tag, t
+:   the literal `Header` (string)
+
+
+### HorizontalRule
+
+A horizontal rule.
+
+tag, t
+:   the literal `HorizontalRule` (string)
+
+### LineBlock
+
+A line block, i.e. a list of lines, each separated from the next
+by a newline.
+
+content
+:   inline content
+
+tag, t
+:   the literal `LineBlock` (string)
+
+### Null
+
+A null element; this element never produces any output in the
+target format.
+
+tag, t
+:   the literal `Null` (string)
+
+### OrderedList
+
+An ordered list.
+
+Parameters:
+
+items
+:   list items ([list] of [blocks])
+
+listAttributes
+:   list parameters
+
+tag, t
+:   the literal `OrderedList` (string)
+
+### Para
+
+A paragraph
+
+content
+:   inline content
+
+tag, t
+:   the literal `Para` (string)
+
+### Plain
+
+Plain text, not a paragraph
+
+content
+:   inline content
+
+tag, t
+:   the literal `Plain` (string)
+
+### RawBlock
+
+Raw content of a specified format.
+
+format
+:   format of content (string)
+
+text
+:   raw content (string)
+
+tag, t
+:   the literal `RawBlock` (string)
+
+### Table
+
+A table.
+
+caption:
+:   table caption
+
+aligns:
+:   alignments
+
+widths:
+:   column widths
+
+headers
+:   header row
+
+rows:
+:   table rows
+
+tag, t
+:   the literal `Table` (string)
+
+## Inline
+
+### Cite
+Citation
+
+content
+:   ([list] of [inlines])
+
+citations
+:   citation entries ([list] of [citations])
+
+tag, t
+:   the literal `Cite` (string)
+
+### Code
+Inline code
+
+text
+:   code string (string)
+
+attr
+:   attributes ([Attr])
+
+identifier
+:   alias for `attr.identifier` (string)
+
+classes
+:   alias for `attr.classes` ([list] of strings)
+
+attributes
+:   alias for `attr.attributes` ([attributes])
+
+tag, t
+:   the literal `Code` (string)
+
+### Emph
+Emphasized text
+
+content
+:   inline content ([list] of [inlines])
+
+tag, t
+:   the literal `Emph` (string)
+
+<!-- TODO -->
+
+### Image
+Image:  alt text (list of inlines), target
+
+tag, t
+:   the literal `Image` (string)
+
+### Link
+Hyperlink: alt text (list of inlines), target
+
+tag, t
+:   the literal `Link` (string)
+
+### LineBreak
+Hard line break
+
+tag, t
+:   the literal `LineBreak` (string)
+
+### Math
+TeX math (literal)
+
+tag, t
+:   the literal `Math` (string)
+
+### Note
+Footnote or endnote
+
+tag, t
+:   the literal `Note` (string)
+
+### Quoted
+Quoted text (list of inlines)
+
+tag, t
+:   the literal `Quoted` (string)
+
+### RawInline
+Raw inline
+
+tag, t
+:   the literal `RawInline` (string)
+
+### SmallCaps
+Small caps text (list of inlines)
+
+tag, t
+:   the literal `SmallCaps` (string)
+
+### SoftBreak
+Soft line break
+
+tag, t
+:   the literal `SoftBreak` (string)
+
+### Space
+Inter-word space
+
+tag, t
+:   the literal `Space` (string)
+
+### Span
+Generic inline container with attributes
+
+attr
+:   attributes ([Attr])
+
+identifier
+:   alias for `attr.identifier` (string)
+
+classes
+:   alias for `attr.classes` ([list] of strings)
+
+attributes
+:   alias for `attr.attributes` ([attributes])
+
+tag, t
+:   the literal `Span` (string)
+
+### Str
+Text (string)
+
+tag, t
+:   the literal `Str` (string)
+
+### Strikeout
+Strikeout text (list of inlines)
+
+tag, t
+:   the literal `Strikeout` (string)
+
+### Strong
+Strongly emphasized text (list of inlines)
+
+tag, t
+:   the literal `Strong` (string)
+
+### Subscript
+Subscripted text (list of inlines)
+
+tag, t
+:   the literal `Subscript` (string)
+
+### Superscript
+Superscripted text (list of inlines)
+
+tag, t
+:   the literal `Superscript` (string)
+
+## Attributes
+
+List of key/value pairs. Values can be accessed by using keys as indices to the
+list table.
+
+
+[block]: #block
+[blocks]: #block
+[list]: #list
+[meta value]: #metavalue
+[inline]: #inline
+[inlines]: #inline
+[Attr]: #attr
+[attributes]: #attributes
diff --git a/doc/lua-filters.md b/doc/lua-filters.md
index 170aaa8f5..917b9cc16 100644
--- a/doc/lua-filters.md
+++ b/doc/lua-filters.md
@@ -10,11 +10,11 @@ title: Pandoc Lua Filters
 
 Pandoc has long supported filters, which allow the pandoc
 abstract syntax tree (AST) to be manipulated between the parsing
-and the writing phase. Traditional pandoc filters accept a JSON
-representation of the pandoc AST and produce an altered JSON
-representation of the AST. They may be written in any
-programming language, and invoked from pandoc using the
-`--filter` option.
+and the writing phase. [Traditional pandoc
+filters](filters.html) accept a JSON representation of the
+pandoc AST and produce an altered JSON representation of the
+AST. They may be written in any programming language, and
+invoked from pandoc using the `--filter` option.
 
 Although traditional filters are very flexible, they have a
 couple of disadvantages. First, there is some overhead in
@@ -114,7 +114,7 @@ The return of a filter function must one of the following:
 -   a pandoc object: this must be of the same type as the input
     and will replace the original object.
 -   a list of pandoc objects: these will replace the original
-    object; the list is merged with the neighbors of the orignal
+    object; the list is merged with the neighbors of the original
     objects (spliced into the list the original object belongs
     to); returning an empty list deletes the object.
 
@@ -240,6 +240,11 @@ colon syntax (`mystring:uc_upper()`).
 
 # Examples
 
+The following filters are presented as examples.
+A repository of useful lua filters (which may also serve
+as good examples) is available at
+<https://github.com/pandoc/lua-filters>.
+
 ## Macro substitution.
 
 The following filter converts the string `{{helloworld}}` into
@@ -948,7 +953,7 @@ Lua functions for pandoc scripts.
     Parameters:
 
     `text`:
-    :   brief image description
+    :   code string
 
     `attr`:
     :   additional attributes
@@ -1438,6 +1443,37 @@ Lua functions for pandoc scripts.
 This module exposes internal pandoc functions and utility
 functions.
 
+[`blocks_to_inlines (blocks[, sep])`]{#utils-blocks_to_inlines}
+
+:   Squash a list of blocks into a list of inlines.
+
+    Parameters:
+
+    `blocks`:
+    :   List of blocks to be flattened.
+
+    `sep`:
+    :   List of inlines inserted as separator between two
+        consecutive blocks; defaults to `{ pandoc.Space(),
+        pandoc.Str'¶', pandoc.Space()}`.
+
+    Returns:
+
+    -   ({[Inline][#Inline]}) List of inlines
+
+    Usage:
+
+        local blocks = {
+          pandoc.Para{ pandoc.Str 'Paragraph1' },
+          pandoc.Para{ pandoc.Emph 'Paragraph2' }
+        }
+        local inlines = pandoc.utils.blocks_to_inlines(blocks)
+        -- inlines = {
+        --   pandoc.Str 'Paragraph1',
+        --   pandoc.Space(), pandoc.Str'¶', pandoc.Space(),
+        --   pandoc.Emph{ pandoc.Str 'Paragraph2' }
+        -- }
+
 [`hierarchicalize (blocks)`]{#utils-hierarchicalize}
 
 :   Convert list of blocks into an hierarchical list. An
diff --git a/doc/using-the-pandoc-api.md b/doc/using-the-pandoc-api.md
index 8527f6373..550b38c65 100644
--- a/doc/using-the-pandoc-api.md
+++ b/doc/using-the-pandoc-api.md
@@ -42,7 +42,7 @@ limitation is mostly a help rather than a hindrance, since many
 of the formats pandoc supports have similar limitations.
 
 The best way to explore the pandoc AST is to use `pandoc -t
-native`, which will display the AST correspoding to some
+native`, which will display the AST corresponding to some
 Markdown input:
 
 ```
@@ -187,7 +187,7 @@ Some particularly important options to know about:
 # Builder
 
 Sometimes it's useful to construct a Pandoc document
-programatically.  To make this easier we provide the
+programmatically.  To make this easier we provide the
 module [Text.Pandoc.Builder] `pandoc-types`.
 
 Because concatenating lists is slow, we use special