From 9ada1defb572cacdf561e9d436a6961f8ea426e0 Mon Sep 17 00:00:00 2001 From: Albert Krewinkel Date: Wed, 30 Aug 2017 15:09:54 +0200 Subject: [PATCH 1/4] Document fallback functions in lua filters --- doc/lua-filters.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/doc/lua-filters.md b/doc/lua-filters.md index 5d0bfaf1e..23ea59a43 100644 --- a/doc/lua-filters.md +++ b/doc/lua-filters.md @@ -111,6 +111,11 @@ inline element must return an inline, and a block element must remain a block element after filter application. Pandoc will throw an error if this condition is violated. +If there is no function matching the element's node type, then +the filtering system will look for a more general fallback +function. Two fallback functions are supported, `Inline` and +`Block`. Each matches elements of the respective type. + Elements without matching functions are left untouched. See [module documentation](pandoc-module.html) for a list of pandoc From bc47cfd40e408b50c010e9d56a7a010a95cde0c8 Mon Sep 17 00:00:00 2001 From: Albert Krewinkel Date: Thu, 31 Aug 2017 13:17:38 +0200 Subject: [PATCH 2/4] Add ldoc template for lua module documentation The template can be used instead of the default template by calling ldoc with the `-l doc` option, where *doc* is the directory of the template. --- doc/ldoc.ltp | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 doc/ldoc.ltp diff --git a/doc/ldoc.ltp b/doc/ldoc.ltp new file mode 100644 index 000000000..3fa96bb0f --- /dev/null +++ b/doc/ldoc.ltp @@ -0,0 +1,38 @@ +# local iter = ldoc.modules.iter +# local M = ldoc.markup + +

Module $(module.name)

+ +

$(M(module.summary))

+ +# for kind, items in module.kinds() do + +

$(kind)

+
+# for item in items() do ldoc.item = item -- provides context for M() +
$(ldoc.display_name(item))
+
+

$(item.summary)

+# if item.params and #item.params > 0 then + $(module.kinds:type_of(item).subnames): +
+# for p in iter(item.params) do +
$(p):
+
$(M(item.params.map[p]))
+# end -- for +
+# end -- if params +# if item.ret then +

Returns: $(item.ret[1])

+# end -- if returns +# if item.usage then +

Usage:

+ 
$(item.usage[1])
+# end -- if usage +# if item.see then + See also: $(item.see[1].label) + +# end -- if see +# end -- for items +
+# end -- for kinds From 1a4658c57390415ec8d59504d096d4383b8970d4 Mon Sep 17 00:00:00 2001 From: Albert Krewinkel Date: Thu, 31 Aug 2017 13:22:27 +0200 Subject: [PATCH 3/4] data/pandoc.lua: fix typos in documentation --- data/pandoc.lua | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/data/pandoc.lua b/data/pandoc.lua index 16387d27b..bce4e9326 100644 --- a/data/pandoc.lua +++ b/data/pandoc.lua @@ -135,7 +135,7 @@ end -- @section document --- A complete pandoc document --- @function Panoc +-- @function Pandoc -- @tparam {Block,...} blocks document content -- @tparam[opt] Meta meta document meta data function M.Pandoc(blocks, meta) @@ -772,7 +772,7 @@ M.UpperAlpha = "UpperAlpha" -- `--from` command line option. -- @tparam string markup the markup to be parsed -- @tparam[opt] string format format specification, defaults to "markdown". --- @return Doc pandoc document +-- @treturn Pandoc pandoc document -- @usage -- local org_markup = "/emphasis/" -- Input to be read -- local document = pandoc.read(org_markup, "org") From 79b1a701b8452db4e49f633d0cc9dae7d0d93a0d Mon Sep 17 00:00:00 2001 From: Albert Krewinkel Date: Thu, 31 Aug 2017 13:23:24 +0200 Subject: [PATCH 4/4] lua-filters.md: append docs for pandoc's lua module The documentation was generated from `data/pandoc.lua` using the following command: ldoc -l doc -d /tmp data/pandoc.lua; pandoc -t markdown --columns=65 \ --atx-headers /tmp/index.html >> \ doc/lua-filters.md --- doc/lua-filters.md | 737 ++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 736 insertions(+), 1 deletion(-) diff --git a/doc/lua-filters.md b/doc/lua-filters.md index 23ea59a43..9e4d438ea 100644 --- a/doc/lua-filters.md +++ b/doc/lua-filters.md @@ -1,6 +1,6 @@ % Pandoc Lua Filters % Albert Krewinkel, John MacFarlane -% August 21, 2017 +% August 31, 2017 # Introduction @@ -309,3 +309,738 @@ then running `pandoc --lua-filter=meta-vars.lua occupations.md` will output: ``` + +# Module pandoc + +Lua functions for pandoc scripts. + +## Pandoc Document + +[`Pandoc (blocks[, meta])`]{#Pandoc} + +: A complete pandoc document + + Parameters: + + `blocks`: + : document content + + `meta`: + : document meta data + +## MetaValue + +[`MetaBlocks (blocks)`]{#MetaBlocks} + +: Meta blocks + + Parameters: + + `blocks`: + : blocks + +[`MetaInlines (inlines)`]{#MetaInlines} + +: Meta inlines + + Parameters: + + `inlines`: + : inlines + +[`MetaList (meta_values)`]{#MetaList} + +: Meta list + + Parameters: + + `meta_values`: + : list of meta values + +[`MetaMap (key_value_map)`]{#MetaMap} + +: Meta map + + Parameters: + + `key_value_map`: + : a string-indexed map of meta values + +[`MetaString (str)`]{#MetaString} + +: Creates string to be used in meta data. + + Parameters: + + `str`: + : string value + +[`MetaBool (bool)`]{#MetaBool} + +: Creates boolean to be used in meta data. + + Parameters: + + `bool`: + : boolean value + +## Blocks + +[`Block`]{#Block} + +: Block elements + +[`BlockQuote (content)`]{#BlockQuote} + +: Creates a block quote element + + Parameters: + + `content`: + : block content + + Returns: block quote element + +[`BulletList (content)`]{#BulletList} + +: Creates a bullet (i.e. + + Parameters: + + `content`: + : list of items + + Returns: block quote element + +[`CodeBlock (text[, attr])`]{#CodeBlock} + +: Creates a code block element + + Parameters: + + `text`: + : code string + + `attr`: + : element attributes + + Returns: code block element + +[`DefinitionList (content)`]{#DefinitionList} + +: Creates a definition list, containing terms and their + explanation. + + Parameters: + + `content`: + : list of items + + Returns: block quote element + +[`Div (content[, attr])`]{#Div} + +: Creates a div element + + Parameters: + + `content`: + : block content + + `attr`: + : element attributes + + Returns: code block element + +[`Header (level, content[, attr])`]{#Header} + +: Creates a block quote element. + + Parameters: + + `level`: + : header level + + `content`: + : inline content + + `attr`: + : element attributes + + Returns: header element + +[`HorizontalRule ()`]{#HorizontalRule} + +: Creates a horizontal rule. + + Returns: horizontal rule + +[`LineBlock (content)`]{#LineBlock} + +: Creates a line block element. + + Parameters: + + `content`: + : inline content + + Returns: block quote element + +[`Null ()`]{#Null} + +: Creates a null element. + + Returns: null element + +[`OrderedList (items[, listAttributes])`]{#OrderedList} + +: Creates an ordered list. + + Parameters: + + `items`: + : list items + + `listAttributes`: + : list parameters + + Returns: + +[`Para (content)`]{#Para} + +: Creates a para element. + + Parameters: + + `content`: + : inline content + + Returns: block quote element + +[`Plain (content)`]{#Plain} + +: Creates a plain element. + + Parameters: + + `content`: + : inline content + + Returns: block quote element + +[`RawBlock (format, text)`]{#RawBlock} + +: Creates a raw content block of the specified format. + + Parameters: + + `format`: + : format of content + + `text`: + : string content + + Returns: block quote element + +[`Table (caption, aligns, widths, headers, rows)`]{#Table} + +: Creates a table element. + + Parameters: + + `caption`: + : table caption + + `aligns`: + : alignments + + `widths`: + : column widths + + `headers`: + : header row + + `rows`: + : table rows + + Returns: block quote element + +## Inline + +[`Inline`]{#Inline} + +: Inline element class + +[`Cite (content, citations)`]{#Cite} + +: Creates a Cite inline element + + Parameters: + + `content`: + : List of inlines + + `citations`: + : List of citations + + Returns: citations element + +[`Code (text[, attr])`]{#Code} + +: Creates a Code inline element + + Parameters: + + `text`: + : brief image description + + `attr`: + : additional attributes + + Returns: code element + +[`Emph (content)`]{#Emph} + +: Creates an inline element representing emphasised text. + + Parameters: + + `content`: + : inline content + + Returns: emphasis element + +[`Image (caption, src[, title[, attr]])`]{#Image} + +: Creates a Image inline element + + Parameters: + + `caption`: + : text used to describe the image + + `src`: + : path to the image file + + `title`: + : brief image description + + `attr`: + : additional attributes + + Returns: image element + +[`LineBreak ()`]{#LineBreak} + +: Create a LineBreak inline element + + Returns: linebreak element + +[`Link (content, target[, title[, attr]])`]{#Link} + +: Creates a link inline element, usually a hyperlink. + + Parameters: + + `content`: + : text for this link + + `target`: + : the link target + + `title`: + : brief link description + + `attr`: + : additional attributes + + Returns: image element + +[`Math (mathtype, text)`]{#Math} + +: Creates a Math element, either inline or displayed. + + Parameters: + + `mathtype`: + : rendering specifier + + `text`: + : Math content + + Returns: Math element + +[`DisplayMath (text)`]{#DisplayMath} + +: Creates a DisplayMath element (DEPRECATED). + + Parameters: + + `text`: + : Math content + + Returns: Math element + +[`InlineMath (text)`]{#InlineMath} + +: Creates an InlineMath inline element (DEPRECATED). + + Parameters: + + `text`: + : Math content + + Returns: Math element + +[`Note (content)`]{#Note} + +: Creates a Note inline element + + Parameters: + + `content`: + : footnote block content + +[`Quoted (quotetype, content)`]{#Quoted} + +: Creates a Quoted inline element given the quote type and + quoted content. + + Parameters: + + `quotetype`: + : type of quotes to be used + + `content`: + : inline content + + Returns: quoted element + +[`SingleQuoted (content)`]{#SingleQuoted} + +: Creates a single-quoted inline element (DEPRECATED). + + Parameters: + + `content`: + : inline content + + Returns: quoted element + + See also: [Quoted](#Quoted) + +[`DoubleQuoted (content)`]{#DoubleQuoted} + +: Creates a single-quoted inline element (DEPRECATED). + + Parameters: + + `content`: + : inline content + + Returns: quoted element + + See also: [Quoted](#Quoted) + +[`RawInline (format, text)`]{#RawInline} + +: Creates a RawInline inline element + + Parameters: + + `format`: + : format of the contents + + `text`: + : string content + + Returns: raw inline element + +[`SmallCaps (content)`]{#SmallCaps} + +: Creates text rendered in small caps + + Parameters: + + `content`: + : inline content + + Returns: smallcaps element + +[`SoftBreak ()`]{#SoftBreak} + +: Creates a SoftBreak inline element. + + Returns: softbreak element + +[`Space ()`]{#Space} + +: Create a Space inline element + + Returns: space element + +[`Span (content[, attr])`]{#Span} + +: Creates a Span inline element + + Parameters: + + `content`: + : inline content + + `attr`: + : additional attributes + + Returns: span element + +[`Str (text)`]{#Str} + +: Creates a Str inline element + + Parameters: + + `text`: + : content + + Returns: string element + +[`Strikeout (content)`]{#Strikeout} + +: Creates text which is striked out. + + Parameters: + + `content`: + : inline content + + Returns: strikeout element + +[`Strong (content)`]{#Strong} + +: Creates a Strong element, whose text is usually displayed in + a bold font. + + Parameters: + + `content`: + : inline content + + Returns: strong element + +[`Subscript (content)`]{#Subscript} + +: Creates a Subscript inline element + + Parameters: + + `content`: + : inline content + + Returns: subscript element + +[`Superscript (content)`]{#Superscript} + +: Creates a Superscript inline element + + Parameters: + + `content`: + : inline content + + Returns: strong element + +## Helpers + +[`Attr ([identifier[, classes[, attributes]]])`]{#Attr} + +: Create a new set of attributes (Attr). + + Parameters: + + `identifier`: + : element identifier + + `classes`: + : element classes + + `attributes`: + : table containing string keys and values + + Returns: element attributes + +[`Citation (id, mode[, prefix[, suffix[, note_num[, hash]]]])`]{#Citation} + +: Creates a single citation. + + Parameters: + + `id`: + : citation identifier (like a bibtex key) + + `mode`: + : citation mode + + `prefix`: + : citation prefix + + `suffix`: + : citation suffix + + `note_num`: + : note number + + `hash`: + : hash number + +## Constants + +[`AuthorInText`]{#AuthorInText} + +: Author name is mentioned in the text. + + See also: [Citation](#Citation) + +[`SuppressAuthor`]{#SuppressAuthor} + +: Author name is suppressed. + + See also: [Citation](#Citation) + +[`NormalCitation`]{#NormalCitation} + +: Default citation style is used. + + See also: [Citation](#Citation) + +[`AlignLeft`]{#AlignLeft} + +: Table cells aligned left. + + See also: [Table](#Table) + +[`AlignRight`]{#AlignRight} + +: Table cells right-aligned. + + See also: [Table](#Table) + +[`AlignCenter`]{#AlignCenter} + +: Table cell content is centered. + + See also: [Table](#Table) + +[`AlignDefault`]{#AlignDefault} + +: Table cells are alignment is unaltered. + + See also: [Table](#Table) + +[`DefaultDelim`]{#DefaultDelim} + +: Default list number delimiters are used. + + See also: [OrderedList](#OrderedList) + +[`Period`]{#Period} + +: List numbers are delimited by a period. + + See also: [OrderedList](#OrderedList) + +[`OneParen`]{#OneParen} + +: List numbers are delimited by a single parenthesis. + + See also: [OrderedList](#OrderedList) + +[`TwoParens`]{#TwoParens} + +: List numbers are delimited by a double parentheses. + + See also: [OrderedList](#OrderedList) + +[`DefaultStyle`]{#DefaultStyle} + +: List are numbered in the default style + + See also: [OrderedList](#OrderedList) + +[`Example`]{#Example} + +: List items are numbered as examples. + + See also: [OrderedList](#OrderedList) + +[`Decimal`]{#Decimal} + +: List are numbered using decimal integers. + + See also: [OrderedList](#OrderedList) + +[`LowerRoman`]{#LowerRoman} + +: List are numbered using lower-case roman numerals. + + See also: [OrderedList](#OrderedList) + +[`UpperRoman`]{#UpperRoman} + +: List are numbered using upper-case roman numerals + + See also: [OrderedList](#OrderedList) + +[`LowerAlpha`]{#LowerAlpha} + +: List are numbered using lower-case alphabetic characters. + + See also: [OrderedList](#OrderedList) + +[`UpperAlpha`]{#UpperAlpha} + +: List are numbered using upper-case alphabetic characters. + + See also: [OrderedList](#OrderedList) + +## Helper Functions + +[`read (markup[, format])`]{#read} + +: Parse the given string into a Pandoc document. + + Parameters: + + `markup`: + : the markup to be parsed + + `format`: + : format specification, defaults to \"markdown\". + + Returns: pandoc document + + Usage: + + local org_markup = "/emphasis/" -- Input to be read + local document = pandoc.read(org_markup, "org") + -- Get the first block of the document + local block = document.blocks[1] + -- The inline element in that block is an `Emph` + assert(block.content[1].t == "Emph") + +[`global_filter ()`]{#global_filter} + +: Use functions defined in the global namespace to create a + pandoc filter. + + Returns: A list of filter functions + + Usage: + + -- within a file defining a pandoc filter: + function Str(text) + return pandoc.Str(utf8.upper(text)) + end + + return {pandoc.global_filter()} + -- the above is equivallent to + -- return {{Str = Str}}