diff options
| -rw-r--r-- | doc/lua-filters.md | 109 | ||||
| -rw-r--r-- | pandoc-lua-engine/src/Text/Pandoc/Lua/Module/Structure.hs | 26 | ||||
| -rw-r--r-- | tools/update-lua-module-docs.lua | 29 |
3 files changed, 102 insertions, 62 deletions
diff --git a/doc/lua-filters.md b/doc/lua-filters.md index d3bea4cb4..e8a9a381a 100644 --- a/doc/lua-filters.md +++ b/doc/lua-filters.md @@ -4810,16 +4810,18 @@ objects. <!-- END: AUTOGENERATED CONTENT --> +<!-- BEGIN: AUTOGENERATED CONTENT for module pandoc.structure --> + # Module pandoc.structure -Access to the higher-level document structure, including -hierarchical sections and the table of contents. +Access to the higher-level document structure, +includinghierarchical sections and the table of contents. -## Functions +## Functions {#pandoc.structure-functions} -### make\_sections {#pandoc.structure.make_sections} +### make_sections {#pandoc.structure.make_sections} -`make_sections (blocks, opts)` +`make_sections (blocks[, opts])` Puts [Blocks] into a hierarchical structure: a list of sections (each a Div with class "section" and first element a Header). @@ -4832,32 +4834,32 @@ reorganized so that there are no gaps, with numbering levels shifted by the given value. Finally, an integer `slide_level` value triggers the creation of slides at that heading level. -Note that a [WriterOptions][] object can be passed as the opts +Note that a [WriterOptions] object can be passed as the opts table; this will set the `number_section` and `slide_level` values to those defined on the command line. +Usage: + + local blocks = { + pandoc.Header(2, pandoc.Str 'first'), + pandoc.Header(2, pandoc.Str 'second'), + } + local opts = PANDOC_WRITER_OPTIONS + local newblocks = pandoc.structure.make_sections(blocks, opts) + Parameters: `blocks` -: list of blocks to process ([Blocks][]|[Pandoc][]) +: document blocks to process ([Blocks]\|[Pandoc]) `opts` : options (table) Returns: -- [Blocks][]. +- processed blocks ([Blocks]) -Usage: - - local blocks = { - pandoc.Header(2, pandoc.Str 'first'), - pandoc.Header(2, pandoc.Str 'second'), - } - local opts = PANDOC_WRITER_OPTIONS - local newblocks = pandoc.structure.make_sections(blocks, opts) - -### slide\_level {#pandoc.structure.slide_level} +### slide_level {#pandoc.structure.slide_level} `slide_level (blocks)` @@ -4868,60 +4870,62 @@ blocks). Parameters: `blocks` -: document body ([Blocks][]|[Pandoc][]) +: document body ([Blocks]\|[Pandoc]) Returns: -- slide level (integer) +- slide level ([integer]{unknown-type="integer"}) -### split\_into\_chunks {#pandoc.structure.split_into_chunks} +### split_into_chunks {#pandoc.structure.split_into_chunks} -`split_into_chunks (doc, opts)` +`split_into_chunks (doc[, opts])` -Converts a [Pandoc][] document into a -[ChunkedDoc](#type-chunkeddoc). +Converts a [Pandoc] document into a [ChunkedDoc]. Parameters: `doc` -: document to split ([Pandoc][]) +: document to split ([Pandoc]) `opts` -: split options (table) + +: Splitting options. The following options are supported: - `path_template` - : template used to generate the chunks' filepaths - `%n` will be replaced with the chunk number (padded with - leading 0s to 3 digits), `%s` with the section number of - the heading, `%h` with the (stringified) heading text, - `%i` with the section identifier. For example, - `"section-%s-%i.html"` might be resolved to - `"section-1.2-introduction.html"`. + `path_template` + : template used to generate the chunks' filepaths + `%n` will be replaced with the chunk number (padded with + leading 0s to 3 digits), `%s` with the section number of + the heading, `%h` with the (stringified) heading text, + `%i` with the section identifier. For example, + `"section-%s-%i.html"` might be resolved to + `"section-1.2-introduction.html"`. - Default is `"chunk-%n"` (string) + Default is `"chunk-%n"` (string) - `number_sections` - : whether sections should be numbered; default is `false` - (boolean) + `number_sections` + : whether sections should be numbered; default is `false` + (boolean) - `chunk_level` - : The heading level the document should be split into - chunks. The default is to split at the top-level, i.e., - `1`. (integer) + `chunk_level` + : The heading level the document should be split into + chunks. The default is to split at the top-level, i.e., + `1`. (integer) - `base_heading_level` - : The base level to be used for numbering. Default is `nil` - (integer|nil) + `base_heading_level` + : The base level to be used for numbering. Default is `nil` + (integer|nil) + + (table) Returns: -- [ChunkedDoc](#type-chunkeddoc) +- ([ChunkedDoc]) -### table\_of\_contents {#pandoc.structure.table_of_contents} +### table_of_contents {#pandoc.structure.table_of_contents} -`table_of_contents (toc_source, opts)` +`table_of_contents (toc_source[, opts])` Generates a table of contents for the given object. @@ -4929,7 +4933,7 @@ Parameters: `toc_source` : list of command line arguments - ([Blocks]|[Pandoc]|[ChunkedDoc](#type-chunkeddoc)`) + ([Blocks]\|[Pandoc]\|[ChunkedDoc]) `opts` : options ([WriterOptions]) @@ -4938,6 +4942,8 @@ Returns: - Table of contents as a BulletList object ([Block]) +<!-- END: AUTOGENERATED CONTENT --> + # Module pandoc.system Access to system information and functionality. @@ -5985,5 +5991,10 @@ Returns: <!-- BEGIN: GENERATED REFERENCE LINKS --> [this blog post]: http://neilmitchell.blogspot.co.uk/2015/10/filepaths-are-subtle-symlinks-are-hard.html + [Blocks]: #type-blocks + [WriterOptions]: #type-writeroptions + [Pandoc]: #type-pandoc + [ChunkedDoc]: #type-chunkeddoc + [Block]: #type-block [zip.Entry]: #type-pandoc.zip.Entry [zip.Archive]: #type-pandoc.zip.Archive diff --git a/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/Structure.hs b/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/Structure.hs index d8894e103..73419633f 100644 --- a/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/Structure.hs +++ b/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/Structure.hs @@ -64,12 +64,13 @@ make_sections = defun "make_sections" Just sl -> prepSlides sl blks Nothing -> blks in pure $ Shared.makeSections numSects baseLevel blks') - <#> parameter peekBodyBlocks "Blocks" "blocks" "document blocks to process" + <#> parameter peekBodyBlocks "Blocks|Pandoc" "blocks" + "document blocks to process" <#> opt (parameter peekOpts "table" "opts" "options") - =#> functionResult pushBlocks "list of Blocks" + =#> functionResult pushBlocks "Blocks" "processed blocks" #? T.unlines - [ "Puts [Blocks] into a hierarchical structure: a list of sections" + [ "Puts [[Blocks]] into a hierarchical structure: a list of sections" , "(each a Div with class \"section\" and first element a Header)." , "" , "The optional `opts` argument can be a table; two settings are" @@ -80,9 +81,18 @@ make_sections = defun "make_sections" , "shifted by the given value. Finally, an integer `slide_level`" , "value triggers the creation of slides at that heading level." , "" - , "Note that a [WriterOptions][] object can be passed as the opts" + , "Note that a [[WriterOptions]] object can be passed as the opts" , "table; this will set the `number_section` and `slide_level` values" , "to those defined on the command line." + , "" + , "Usage:" + , "" + , " local blocks = {" + , " pandoc.Header(2, pandoc.Str 'first')," + , " pandoc.Header(2, pandoc.Str 'second')," + , " }" + , " local opts = PANDOC_WRITER_OPTIONS" + , " local newblocks = pandoc.structure.make_sections(blocks, opts)" ] where defNumSec = False @@ -101,7 +111,7 @@ make_sections = defun "make_sections" slide_level :: LuaError e => DocumentedFunction e slide_level = defun "slide_level" ### liftPure getSlideLevel - <#> parameter peekBodyBlocks "Pandoc|Blocks" "blocks" "document body" + <#> parameter peekBodyBlocks "Blocks|Pandoc" "blocks" "document body" =#> functionResult pushIntegral "integer" "slide level" #? T.unlines [ "Find level of header that starts slides (defined as the least" @@ -121,7 +131,7 @@ split_into_chunks = defun "split_into_chunks" <#> opt (parameter peekSplitOpts "table" "opts" optionsDescr) =#> functionResult pushChunkedDoc "ChunkedDoc" "" #? T.unlines - [ "Converts a `Pandoc` document into a `ChunkedDoc`." ] + [ "Converts a [[Pandoc]] document into a [[ChunkedDoc]]." ] where defPathTmpl = PathTemplate "chunk-%n" defNumSects = False @@ -136,7 +146,9 @@ split_into_chunks = defun "split_into_chunks" True -> pure defaultValue False -> p idx' optionsDescr = T.unlines - [ "The following options are supported:" + [ "Splitting options." + , "" + , "The following options are supported:" , "" , " `path_template`" , " : template used to generate the chunks' filepaths" diff --git a/tools/update-lua-module-docs.lua b/tools/update-lua-module-docs.lua index f8531b5c5..7ea6de3f6 100644 --- a/tools/update-lua-module-docs.lua +++ b/tools/update-lua-module-docs.lua @@ -37,14 +37,20 @@ local get = function (fieldname) end local function read_blocks (txt) - return read(txt, 'commonmark+smart').blocks + return read(txt, 'commonmark+smart+wikilinks_title_before_pipe').blocks end local function read_inlines (txt) return utils.blocks_to_inlines(read_blocks(txt)) end -local known_types = {} +local known_types = { + Block = 'type-block', + Blocks = 'type-blocks', + ChunkedDoc = 'type-chunkeddoc', + Pandoc = 'type-pandoc', + WriterOptions = 'type-writeroptions', +} local function render_typespec (typespec) if typespec.basic then @@ -136,11 +142,11 @@ local function render_function (doc, level, modulename) List(doc.parameters):map( function (p) return { - {Code(p.name)}, - append_inlines( + Inlines{Code(p.name)}, + {append_inlines( read_blocks(p.description), type_to_inlines(p.type) - ) + )} } end ) @@ -297,6 +303,17 @@ end function _G.Reader (inputs, opts) local blocks = foo(tostring(inputs), Blocks{}, 1) blocks = blocks:walk { + Link = function (link) + if link.title == 'wikilink' then + link.title = '' + if known_types[link.target] then + link.target = '#' .. known_types[link.target] + else + warn('Unknown type: ' .. link.target) + end + return link + end + end, Span = function (span) local unknown_type = span.attributes['unknown-type'] if unknown_type and known_types[unknown_type] then @@ -304,7 +321,7 @@ function _G.Reader (inputs, opts) elseif span.classes:includes 'builtin-lua-type' then return span.content -- unwrap end - end + end, } return Pandoc(blocks) end |