diff options
| -rw-r--r-- | doc/lua-filters.md | 45 | ||||
| -rw-r--r-- | pandoc-lua-engine/src/Text/Pandoc/Lua/Module/Template.hs | 40 | ||||
| -rw-r--r-- | pandoc-lua-engine/src/Text/Pandoc/Lua/Module/Utils.hs | 1 | ||||
| -rw-r--r-- | tools/update-lua-module-docs.lua | 19 |
4 files changed, 74 insertions, 31 deletions
diff --git a/doc/lua-filters.md b/doc/lua-filters.md index 5ca68bdb5..8ae6e3f8e 100644 --- a/doc/lua-filters.md +++ b/doc/lua-filters.md @@ -6126,10 +6126,14 @@ Returns: <!-- END: AUTOGENERATED CONTENT --> +<!-- BEGIN: AUTOGENERATED CONTENT for module pandoc.template --> + # Module pandoc.template Handle pandoc templates. +## Functions {#pandoc.template-functions} + ### apply {#pandoc.template.apply} `apply (template, context)` @@ -6143,7 +6147,7 @@ aforementioned types, or a nested context. Parameters: `template` -: template to apply ([Template]{#type-template}) +: template to apply ([Template]) `context` : variable values (table) @@ -6152,17 +6156,19 @@ Returns: - rendered template ([Doc]) +*Since: 3.0* + ### compile {#pandoc.template.compile} `compile (template[, templates_path])` -Compiles a template string into a [Template](#type-template) -object usable by pandoc. +Compiles a template string into a [Template] object usable by +pandoc. -If the `templates_path` parameter is specified, should be the -file path associated with the template. It is used when checking -for partials. Partials will be taken only from the default data -files if this parameter is omitted. +If the `templates_path` parameter is specified, then it should be +the file path associated with the template. It is used when +checking for partials. Partials will be taken only from the +default data files if this parameter is omitted. An error is raised if compilation fails. @@ -6178,32 +6184,36 @@ Parameters: Returns: -- compiled template (Template) +- compiled template ([Template]) + +*Since: 2.17* ### default {#pandoc.template.default} `default ([writer])` Returns the default template for a given writer as a string. An -error if no such template can be found. +error is thrown if no such template can be found. Parameters: `writer` -: name of the writer for which the template should be - retrieved; defaults to the global `FORMAT`. +: name of the writer for which the template should be retrieved; + defaults to the global `FORMAT`. (string) Returns: - raw template (string) +*Since: 2.17* + ### meta_to_context {#pandoc.template.meta_to_context} `meta_to_context (meta, blocks_writer, inlines_writer)` -Creates template context from the document's [Meta]{#type-meta} -data, using the given functions to convert [Blocks] and [Inlines] -to [Doc] values. +Creates template context from the document's [Meta] data, using +the given functions to convert [Blocks] and [Inlines] to [Doc] +values. Parameters: @@ -6220,6 +6230,10 @@ Returns: - template context (table) +*Since: 3.0* + +<!-- END: AUTOGENERATED CONTENT --> + <!-- BEGIN: AUTOGENERATED CONTENT for module pandoc.types --> # Module pandoc.types @@ -6468,5 +6482,8 @@ Returns: [null]: #pandoc.json.null [this blog post]: http://neilmitchell.blogspot.co.uk/2015/10/filepaths-are-subtle-symlinks-are-hard.html [ChunkedDoc]: #type-chunkeddoc + [Doc]: #type-doc + [Template]: #type-template + [Meta]: #type-meta [zip.Entry]: #type-pandoc.zip.Entry [zip.Archive]: #type-pandoc.zip.Archive diff --git a/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/Template.hs b/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/Template.hs index b5497a14d..69dc75955 100644 --- a/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/Template.hs +++ b/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/Template.hs @@ -31,7 +31,7 @@ documentedModule :: Module PandocError documentedModule = Module { moduleName = "pandoc.template" , moduleDescription = T.unlines - [ "Lua functions for pandoc templates." + [ "Handle pandoc templates." ] , moduleFields = [] , moduleOperations = [] @@ -50,7 +50,7 @@ functions = #? T.unlines [ "Applies a context with variable assignments to a template," , "returning the rendered template. The `context` parameter must be a" - , "table with variable names as keys and [Doc], string, boolean, or" + , "table with variable names as keys and [[Doc]], string, boolean, or" , "table as values, where the table can be either be a list of the" , "aforementioned types, or a nested context." ] @@ -63,9 +63,22 @@ functions = Nothing -> runWithDefaultPartials (compileTemplate "templates/default" template)) <#> parameter peekText "string" "template" "template string" - <#> opt (stringParam "templ_path" "template path") - =#> functionResult (either failLua pushTemplate) "pandoc Template" + <#> opt (stringParam "templates_path" + ("parameter to determine a default path and extension for " <> + "partials; uses the data files templates path by default.")) + =#> functionResult (either failLua pushTemplate) "Template" "compiled template" + #? T.unlines + [ "Compiles a template string into a [[Template]] object usable by" + , "pandoc." + , "" + , "If the `templates_path` parameter is specified, then it should be the" + , "file path associated with the template. It is used when checking" + , "for partials. Partials will be taken only from the default data" + , "files if this parameter is omitted." + , "" + , "An error is raised if compilation fails." + ] `since` makeVersion [2,17] , defun "default" @@ -76,9 +89,14 @@ functions = format <- maybe getFORMAT pure mformat getDefaultTemplate format) <#> opt (textParam "writer" - "writer for which the template should be returned.") + ("name of the writer for which the template should be " <> + "retrieved; defaults to the global `FORMAT`.")) =#> functionResult pushText "string" - "string representation of the writer's default template" + "raw template" + #? T.unlines + [ "Returns the default template for a given writer as a string. An" + , "error is thrown if no such template can be found." + ] `since` makeVersion [2,17] , defun "meta_to_context" @@ -96,14 +114,14 @@ functions = metaToContext' blockWriter inlineWriter meta) <#> parameter peekMeta "Meta" "meta" "document metadata" <#> parameter pure "function" "blocks_writer" - "converter from Blocks to Doc values" + "converter from [[Blocks]] to [[Doc]] values" <#> parameter pure "function" "inlines_writer" - "converter from Inlines to Doc values" + "converter from [[Inlines]] to [[Doc]] values" =#> functionResult pushContext "table" "template context" #? T.unlines - [ "Creates template context from the document's [Meta]{#type-meta}" - , "data, using the given functions to convert [Blocks] and [Inlines]" - , "to [Doc] values." + [ "Creates template context from the document's [[Meta]] data, using the" + , "given functions to convert [[Blocks]] and [[Inlines]] to [[Doc]]" + , "values." ] `since` makeVersion [3,0] ] diff --git a/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/Utils.hs b/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/Utils.hs index 8fe24fd6c..fd3006ba6 100644 --- a/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/Utils.hs +++ b/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/Utils.hs @@ -263,7 +263,6 @@ run_lua_filter = defun "run_lua_filter" "\n\nThe filter will be run in the current Lua process." <> "\n" ) - `since` makeVersion [3,2,1] where copynext :: LuaError e => StackIndex -> LuaE e StackIndex copynext to = diff --git a/tools/update-lua-module-docs.lua b/tools/update-lua-module-docs.lua index 12651f966..a13ffdadc 100644 --- a/tools/update-lua-module-docs.lua +++ b/tools/update-lua-module-docs.lua @@ -68,12 +68,15 @@ end local known_types = { Block = 'type-block', Blocks = 'type-blocks', + Doc = 'type-doc', ChunkedDoc = 'type-chunkeddoc', Inline = 'type-inline', Inlines = 'type-inlines', + Meta = 'type-meta', Pandoc = 'type-pandoc', SimpleTable = 'type-simpletable', Table = 'type-table', + Template = 'type-template', WriterOptions = 'type-writeroptions', Version = 'type-version', } @@ -221,6 +224,12 @@ end -- @param modulename name of the module that contains this function -- @return {Block,...} local function render_type (name, level, modulename) + -- FIXME: SPECIAL CASE + -- Ignore Template type in `pandoc.template` module, as the automatic + -- content doesn't describe it yet. + if name == 'pandoc Template' then + return {} + end -- We just want the modulename prefix, as the type names should already -- contain the module name to some extend. local nameprefix = modulename and @@ -285,11 +294,11 @@ local function render_module (doc) local typedocs = Blocks{} local types = type(doc.types) == 'function' and doc.types() or {} - if #types > 0 then - typedocs:insert(Header(2, 'Types', {doc.name .. '-' .. 'types'})) - for _, ty in ipairs(types) do - typedocs:extend(render_type(ty, 3, doc.name)) - end + for _, ty in ipairs(types) do + typedocs:extend(render_type(ty, 3, doc.name)) + end + if #typedocs > 0 then + typedocs:insert(1, Header(2, 'Types', {doc.name .. '-' .. 'types'})) end return Blocks{ |