Tissevert/pandoc
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

doc/lua-filters.md: fix and improve documentation

Browse source
This commit is contained in:
Albert Krewinkel 2022-01-02 14:50:56 +01:00
parent 85334eb6c4
commit 60fc05e2ce
No known key found for this signature in database
GPG key ID: 388DC0B21F631124
1 changed files with 67 additions and 63 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

130
doc/lua-filters.md
View file

@ -151,15 +151,15 @@ filters on lists of blocks or lists of inlines.
lists of inline elements, like the content of a [Para] lists of inline elements, like the content of a [Para]
(paragraph) block, or the description of an [Image]. The (paragraph) block, or the description of an [Image]. The
`inlines` argument passed to the function will be a [List] of `inlines` argument passed to the function will be a [List] of
[Inlines] for each call. [Inline] elements for each call.
[`Blocks (blocks)`]{#blocks-filter} [`Blocks (blocks)`]{#blocks-filter}
: If present in a filter, this function will be called on all : If present in a filter, this function will be called on all
lists of block elements, like the content of a [MetaBlocks] lists of block elements, like the content of a [MetaBlocks]
meta element block, on each item of a list, and the main meta element block, on each item of a list, and the main
content of the [Pandoc] document. The `blocks` argument content of the [Pandoc] document. The `blocks` argument
passed to the function will be a [List] of [Blocks] for each passed to the function will be a [List] of [Block] elements
call. for each call.
These filter functions are special in that the result must either These filter functions are special in that the result must either
be nil, in which case the list is left unchanged, or must be a be nil, in which case the list is left unchanged, or must be a
@ -190,7 +190,7 @@ local filter = {
return {filter} return {filter}
``` ```
Support for this was added in pandoc 2.16.3; previous versions Support for this was added in pandoc 2.17; previous versions
ignore the `traverse` setting. ignore the `traverse` setting.
### Typewise traversal ### Typewise traversal
@ -525,7 +525,7 @@ local vars = {}
function get_vars (meta) function get_vars (meta)
for k, v in pairs(meta) do for k, v in pairs(meta) do
if type(v) == 'table' and v.t == 'MetaInlines' then if pandoc.utils.type(v) == 'Inlines' then
vars["%" .. k .. "%"] = {table.unpack(v)} vars["%" .. k .. "%"] = {table.unpack(v)}
end end
end end
@ -582,8 +582,8 @@ headers), removes footnotes, and replaces links with regular
text. text.
``` lua ``` lua
-- we use preloaded text to get a UTF-8 aware 'upper' function -- we use pandoc.text to get a UTF-8 aware 'upper' function
local text = require('text') local text = pandoc.text
function Header(el) function Header(el)
if el.level == 1 then if el.level == 1 then
@ -844,7 +844,7 @@ Values of this type can be created with the
equal in Lua if and only if they are equal in Haskell. equal in Lua if and only if they are equal in Haskell.
`blocks` `blocks`
: document content ([List] of [Blocks]) : document content ([Blocks][])
`meta` `meta`
: document meta information ([Meta] object) : document meta information ([Meta] object)
@ -916,6 +916,9 @@ can be made into an empty `MetaList` by calling
using the generic functions like `pandoc.List`, `pandoc.Inlines`, using the generic functions like `pandoc.List`, `pandoc.Inlines`,
or `pandoc.Blocks`. or `pandoc.Blocks`.
Use the function [`pandoc.utils.type`](#pandoc.utils.type) to
get the type of a metadata value.
## Block {#type-block} ## Block {#type-block}
Block values are equal in Lua if and only if they are equal in Block values are equal in Lua if and only if they are equal in
@ -967,7 +970,7 @@ Values of this type can be created with the
Fields: Fields:
`content`: `content`:
: block content ([List] of [Blocks]) : block content ([Blocks][])
`tag`, `t` `tag`, `t`
: the literal `BlockQuote` (string) : the literal `BlockQuote` (string)
@ -982,7 +985,7 @@ Values of this type can be created with the
Fields: Fields:
`content` `content`
: list items ([List] of [List] of [Blocks]) : list items ([List] of items, i.e., [List] of [Blocks][])
`tag`, `t` `tag`, `t`
: the literal `BulletList` (string) : the literal `BulletList` (string)
@ -1039,7 +1042,7 @@ Values of this type can be created with the
Fields: Fields:
`content` `content`
: block content ([List] of [Blocks]) : block content ([Blocks][])
`attr` `attr`
: element attributes ([Attr]) : element attributes ([Attr])
@ -1070,7 +1073,7 @@ Fields:
: header level (integer) : header level (integer)
`content` `content`
: inline content ([List] of [Inlines]) : inline content ([Inlines][])
`attr` `attr`
: element attributes ([Attr]) : element attributes ([Attr])
@ -1111,7 +1114,7 @@ Values of this type can be created with the
Fields: Fields:
`content` `content`
: inline content : inline content ([List] of lines, i.e. [List] of [Inlines][])
`tag`, `t` `tag`, `t`
: the literal `LineBlock` (string) : the literal `LineBlock` (string)
@ -1137,7 +1140,7 @@ Values of this type can be created with the
Fields: Fields:
`content` `content`
: list items ([List] of [List] of [Blocks]) : list items ([List] of items, i.e., [List] of [Blocks][])
`listAttributes` `listAttributes`
: list parameters ([ListAttributes]) : list parameters ([ListAttributes])
@ -1164,7 +1167,7 @@ Values of this type can be created with the
Fields: Fields:
`content` `content`
: inline content ([List] of [Inlines]) : inline content ([Inlines][])
`tag`, `t` `tag`, `t`
: the literal `Para` (string) : the literal `Para` (string)
@ -1179,7 +1182,7 @@ Values of this type can be created with the
Fields: Fields:
`content` `content`
: inline content ([List] of [Inlines]) : inline content ([Inlines][])
`tag`, `t` `tag`, `t`
: the literal `Plain` (string) : the literal `Plain` (string)
@ -1259,8 +1262,8 @@ of this type in user scripts, as pandoc can convert other types
into Blocks wherever a value of this type is expected: into Blocks wherever a value of this type is expected:
- a list of [Block] (or Block-like) values is used directly; - a list of [Block] (or Block-like) values is used directly;
- a single [Inlines] value is wrapped into a [Plain] element; - a single [Inlines][] value is wrapped into a [Plain] element;
- string values are turned into an [Inlines] value by splitting - string values are turned into an [Inlines][] value by splitting
the string into words (see [Inlines](#type-inlines)), and the string into words (see [Inlines](#type-inlines)), and
then wrapping the result into a Plain singleton. then wrapping the result into a Plain singleton.
@ -1284,14 +1287,14 @@ see the section on [traversal order][Traversal order].
Parameters: Parameters:
`self` `self`
: the list ([Blocks](#type-blocks)) : the list ([Blocks][])
`lua_filter` `lua_filter`
: map of filter functions (table) : map of filter functions (table)
Result: Result:
- filtered list ([Blocks](#type-blocks)) - filtered list ([Blocks][])
Usage: Usage:
@ -1350,7 +1353,7 @@ Values of this type can be created with the
Fields: Fields:
`content` `content`
: ([List] of [Inlines]) : ([Inlines][])
`citations` `citations`
: citation entries ([List] of [Citations]) : citation entries ([List] of [Citations])
@ -1395,7 +1398,7 @@ Values of this type can be created with the
Fields: Fields:
`content` `content`
: inline content ([List] of [Inlines]) : inline content ([Inlines][])
`tag`, `t` `tag`, `t`
: the literal `Emph` (string) : the literal `Emph` (string)
@ -1410,7 +1413,7 @@ Values of this type can be created with the
Fields: Fields:
`caption` `caption`
: text used to describe the image ([List] of [Inlines]) : text used to describe the image ([Inlines][])
`src` `src`
: path to the image file (string) : path to the image file (string)
@ -1458,7 +1461,7 @@ Fields:
: attributes ([Attr]) : attributes ([Attr])
`content` `content`
: text for this link ([List] of [Inlines]) : text for this link ([Inlines][])
`target` `target`
: the link target (string) : the link target (string)
@ -1508,7 +1511,7 @@ Values of this type can be created with the
Fields: Fields:
`content` `content`
: ([List] of [Blocks]) : ([Blocks][])
`tag`, `t` `tag`, `t`
: the literal `Note` (string) : the literal `Note` (string)
@ -1527,7 +1530,7 @@ Fields:
`DoubleQuote` (string) `DoubleQuote` (string)
`content` `content`
: quoted text ([List] of [Inlines]) : quoted text ([Inlines][])
`tag`, `t` `tag`, `t`
: the literal `Quoted` (string) : the literal `Quoted` (string)
@ -1560,7 +1563,7 @@ Values of this type can be created with the
Fields: Fields:
`content` `content`
: ([List] of [Inlines]) : ([Inlines][])
`tag`, `t` `tag`, `t`
: the literal `SmallCaps` (string) : the literal `SmallCaps` (string)
@ -1602,7 +1605,7 @@ Fields:
: attributes ([Attr]) : attributes ([Attr])
`content` `content`
: wrapped content ([List] of [Inlines]) : wrapped content ([Inlines][])
`identifier` `identifier`
: alias for `attr.identifier` (string) : alias for `attr.identifier` (string)
@ -1641,7 +1644,7 @@ Values of this type can be created with the
Fields: Fields:
`content` `content`
: inline content ([List] of [Inlines]) : inline content ([Inlines][])
`tag`, `t` `tag`, `t`
: the literal `Strikeout` (string) : the literal `Strikeout` (string)
@ -1656,7 +1659,7 @@ Values of this type can be created with the
Fields: Fields:
`content` `content`
: inline content ([List] of [Inlines]) : inline content ([Inlines][])
`tag`, `t` `tag`, `t`
: the literal `Strong` (string) : the literal `Strong` (string)
@ -1671,7 +1674,7 @@ Values of this type can be created with the
Fields: Fields:
`content` `content`
: inline content ([List] of [Inlines]) : inline content ([Inlines][])
`tag`, `t` `tag`, `t`
: the literal `Subscript` (string) : the literal `Subscript` (string)
@ -1686,7 +1689,7 @@ Values of this type can be created with the
Fields: Fields:
`content` `content`
: inline content ([List] of [Inlines]) : inline content ([Inlines][])
`tag`, `t` `tag`, `t`
: the literal `Superscript` (string) : the literal `Superscript` (string)
@ -1701,7 +1704,7 @@ Values of this type can be created with the
Fields: Fields:
`content` `content`
: inline content ([List] of [Inlines]) : inline content ([Inlines][])
`tag`, `t` `tag`, `t`
: the literal `Underline` (string) : the literal `Underline` (string)
@ -1805,10 +1808,10 @@ The caption of a table, with an optional short caption.
Fields: Fields:
`long` `long`
: long caption (list of [Blocks]) : long caption ([Blocks][])
`short` `short`
: short caption (list of [Inlines]) : short caption ([Inlines][])
### Cell {#type-cell} ### Cell {#type-cell}
@ -1823,7 +1826,7 @@ Fields:
: individual cell alignment ([Alignment]). : individual cell alignment ([Alignment]).
`contents` `contents`
: cell contents (list of [Blocks]). : cell contents ([Blocks][]).
`col_span` `col_span`
: number of columns spanned by the cell; the width of the cell : number of columns spanned by the cell; the width of the cell
@ -1862,10 +1865,10 @@ Fields:
`NormalCitation` (string) `NormalCitation` (string)
`prefix` `prefix`
: citation prefix ([List] of [Inlines]) : citation prefix ([Inlines][])
`suffix` `suffix`
: citation suffix ([List] of [Inlines]) : citation suffix ([Inlines][])
`note_num` `note_num`
: note number (integer) : note number (integer)
@ -2092,7 +2095,7 @@ constructor.
Fields: Fields:
`caption`: `caption`:
: [List] of [Inlines] : [Inlines][]
`aligns`: `aligns`:
: column alignments ([List] of [Alignments](#type-alignment)) : column alignments ([List] of [Alignments](#type-alignment))
@ -2101,11 +2104,12 @@ Fields:
: column widths; a ([List] of numbers) : column widths; a ([List] of numbers)
`headers`: `headers`:
: table header row ([List] of lists of [Blocks]) : table header row ([List] of simple cells, i.e., [List] of
[Blocks][])
`rows`: `rows`:
: table rows ([List] of rows, where a row is a list of lists of : table rows ([List] of rows, where a row is a list of simple
[Blocks]) cells, i.e., [List] of [Blocks][])
## Version {#type-version} ## Version {#type-version}
@ -2159,7 +2163,7 @@ Usage:
[Attr]: #type-attr [Attr]: #type-attr
[Attributes]: #type-attributes [Attributes]: #type-attributes
[Block]: #type-block [Block]: #type-block
[Blocks]: #type-block [Blocks]: #type-blocks
[Caption]: #type-caption [Caption]: #type-caption
[Cell]: #type-cell [Cell]: #type-cell
[Cells]: #type-cell [Cells]: #type-cell
@ -2169,7 +2173,7 @@ Usage:
[CommonState]: #type-commonstate [CommonState]: #type-commonstate
[Image]: #type-image [Image]: #type-image
[Inline]: #type-inline [Inline]: #type-inline
[Inlines]: #type-inline [Inlines]: #type-inlines
[List]: #type-list [List]: #type-list
[ListAttributes]: #type-listattributes [ListAttributes]: #type-listattributes
[Meta]: #type-meta [Meta]: #type-meta
@ -2283,7 +2287,7 @@ format, and functions to filter and modify a subtree.
`blocks`: `blocks`:
: blocks : blocks
Returns: [Blocks](#type-blocks) Returns: [Blocks][]
[`MetaInlines (inlines)`]{#pandoc.metainlines} [`MetaInlines (inlines)`]{#pandoc.metainlines}
@ -2296,7 +2300,7 @@ format, and functions to filter and modify a subtree.
`inlines`: `inlines`:
: inlines : inlines
Returns: [Inlines](#types-inlines) Returns: [Inlines][]
[`MetaList (meta_values)`]{#pandoc.metalist} [`MetaList (meta_values)`]{#pandoc.metalist}
@ -2534,7 +2538,7 @@ format, and functions to filter and modify a subtree.
[`Blocks (block_like_elements)`]{#pandoc.blocks} [`Blocks (block_like_elements)`]{#pandoc.blocks}
: Creates a [Blocks](#type-blocks) list. : Creates a [Blocks][] list.
Parameters: Parameters:
@ -2542,7 +2546,7 @@ format, and functions to filter and modify a subtree.
: List where each element can be treated as a [Block] : List where each element can be treated as a [Block]
value, or a single such value. value, or a single such value.
Returns: [Blocks] list Returns: [Blocks][]
## Inline ## Inline
@ -2837,7 +2841,7 @@ format, and functions to filter and modify a subtree.
[`Inlines (inline_like_elements)`]{#pandoc.inlines} [`Inlines (inline_like_elements)`]{#pandoc.inlines}
: Converts its argument into an [Inlines](#type-inlines) list: : Converts its argument into an [Inlines][] list:
- copies a list of [Inline] elements into a fresh list; any - copies a list of [Inline] elements into a fresh list; any
string `s` within the list is treated as `pandoc.Str(s)`; string `s` within the list is treated as `pandoc.Str(s)`;
@ -2851,7 +2855,7 @@ format, and functions to filter and modify a subtree.
: List where each element can be treated as an [Inline] : List where each element can be treated as an [Inline]
values, or just a single such value. values, or just a single such value.
Returns: [Inlines] list Returns: [Inlines][] list
## Element components ## Element components
@ -2880,7 +2884,7 @@ format, and functions to filter and modify a subtree.
Parameters: Parameters:
`blocks`: `blocks`:
: cell contents (list of [Blocks]) : cell contents ([Blocks][])
`align`: `align`:
: text alignment; defaults to `AlignDefault` (Alignment) : text alignment; defaults to `AlignDefault` (Alignment)
@ -2989,7 +2993,7 @@ format, and functions to filter and modify a subtree.
Parameters: Parameters:
`caption`: `caption`:
: [List] of [Inlines] : [Inlines][]
`aligns`: `aligns`:
: column alignments ([List] of [Alignments](#type-alignment)) : column alignments ([List] of [Alignments](#type-alignment))
@ -2998,11 +3002,11 @@ format, and functions to filter and modify a subtree.
: column widths; a ([List] of numbers) : column widths; a ([List] of numbers)
`headers`: `headers`:
: table header row ([List] of lists of [Blocks]) : table header row ([List] of [Blocks][])
`rows`: `rows`:
: table rows ([List] of rows, where a row is a list of lists : table rows ([List] of rows, where a row is a list
of [Blocks]) of [Blocks][])
Returns: [SimpleTable] object Returns: [SimpleTable] object
@ -3298,16 +3302,16 @@ Squash a list of blocks into a list of inlines.
Parameters: Parameters:
`blocks`: `blocks`:
: List of [Blocks](#type-block) to be flattened. : List of [Block](#type-block) elements to be flattened.
`sep`: `sep`:
: List of [Inlines](#type-inline) inserted as separator between : List of [Inline](#type-inline) elements inserted as
two consecutive blocks; defaults to separator between two consecutive blocks; defaults to `{
`{ pandoc.Space(), pandoc.Str'¶', pandoc.Space()}`. pandoc.Space(), pandoc.Str'¶', pandoc.Space()}`.
Returns: Returns:
- [List](#type-list) of [Inlines](#type-inline) - [Inlines][]
Usage: Usage:
@ -3366,7 +3370,7 @@ Usage:
`make_sections (number_sections, base_level, blocks)` `make_sections (number_sections, base_level, blocks)`
Converts list of [Blocks](#type-block) into sections. Converts list of [Block](#type-block) elements into sections.
`Div`s will be created beginning at each `Header` `Div`s will be created beginning at each `Header`
and containing following content until the next `Header` and containing following content until the next `Header`
of comparable level. If `number_sections` is true, of comparable level. If `number_sections` is true,
@ -3386,11 +3390,11 @@ Parameters:
: shift top-level headings to this level. (integer|nil) : shift top-level headings to this level. (integer|nil)
`blocks` `blocks`
: list of blocks to process ([Blocks](#type-blocks)) : list of blocks to process ([Blocks][])
Returns: Returns:
- [Blocks](#type-blocks). - [Blocks][].
Usage: Usage: