From 790abcf4147fa2a097b1f29c845182675d90ccc3 Mon Sep 17 00:00:00 2001 From: Albert Krewinkel Date: Tue, 11 Jun 2024 15:53:36 +0200 Subject: lua-filters.md: Partially autogenerate docs for module "pandoc" The documentation system isn't powerful enough to generate the full documentation automatically. --- .../src/Text/Pandoc/Lua/Module/Pandoc.hs | 109 ++++++++++++++++----- 1 file changed, 84 insertions(+), 25 deletions(-) (limited to 'pandoc-lua-engine') diff --git a/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/Pandoc.hs b/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/Pandoc.hs index 0b82d35d6..8fdfc3e20 100644 --- a/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/Pandoc.hs +++ b/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/Pandoc.hs @@ -6,12 +6,10 @@ {- | Module : Text.Pandoc.Lua.Module.Pandoc Copyright : Copyright © 2017-2024 Albert Krewinkel - License : GNU GPL, version 2 or above - + License : GPL-2.0-or-later Maintainer : Albert Krewinkel - Stability : alpha -Pandoc module for lua. +Main @pandoc@ module, containing element constructors and central functions. -} module Text.Pandoc.Lua.Module.Pandoc ( documentedModule @@ -61,19 +59,22 @@ documentedModule :: Module PandocError documentedModule = Module { moduleName = "pandoc" , moduleDescription = T.unlines - [ "Lua functions for pandoc scripts; includes constructors for" - , "document elements, functions to parse text in a given" + [ "Fields and functions for pandoc scripts; includes constructors for" + , "document tree elements, functions to parse text in a given" , "format, and functions to filter and modify a subtree." ] , moduleFields = readersField : writersField : stringConstants ++ [inlineField, blockField] , moduleOperations = [] , moduleFunctions = mconcat - [ functions - , otherConstructors + [ [mkPandoc, mkMeta] + , metaValueConstructors , blockConstructors + , [mkBlocks] , inlineConstructors - , metaValueConstructors + , [mkInlines] + , otherConstructors + , functions ] , moduleTypeInitializers = [ initType typePandoc @@ -144,30 +145,51 @@ pushWithConstructorsSubtable constructors = do otherConstructors :: [DocumentedFunction PandocError] otherConstructors = - [ mkPandoc - , mkMeta - , mkAttr + [ mkAttr + , mkCell , mkAttributeList - , mkBlocks , mkCitation - , mkCell + , mkListAttributes , mkRow - , mkTableHead , mkTableFoot - , mkInlines - , mkListAttributes + , mkTableHead , mkSimpleTable , defun "ReaderOptions" ### liftPure id - <#> parameter peekReaderOptions "ReaderOptions|table" "opts" "reader options" + <#> parameter peekReaderOptions "ReaderOptions|table" "opts" + (T.unlines + [ "Either a table with a subset of the properties of a" + , "[[ReaderOptions]] object, or another ReaderOptions object." + , "Uses the defaults specified in the manual for all" + , "properties that are not explicitly specified. Throws an" + , "error if a table contains properties which are not present" + , "in a ReaderOptions object." + ] + ) =#> functionResult pushReaderOptions "ReaderOptions" "new object" - #? "Creates a new ReaderOptions value." + #? T.unlines + [ "Creates a new ReaderOptions value." + , "" + , "Usage:" + , "" + , " -- copy of the reader options that were defined on the command line." + , " local cli_opts = pandoc.ReaderOptions(PANDOC_READER_OPTIONS)" + , " -- default reader options, but columns set to 66." + , " local short_colums_opts = pandoc.ReaderOptions {columns = 66}" + ] , defun "WriterOptions" ### liftPure id <#> parameter peekWriterOptions "WriterOptions|table" "opts" - "writer options" + (T.unlines + [ "Either a table with a subset of the properties of a" + , "[[WriterOptions]] object, or another WriterOptions object." + , "Uses the defaults specified in the manual for all" + , "properties that are not explicitly specified. Throws an" + , "error if a table contains properties which are not present" + , "in a WriterOptions object." + ]) =#> functionResult pushWriterOptions "WriterOptions" "new object" #? "Creates a new WriterOptions value." ] @@ -260,22 +282,59 @@ functions = (ByteStringWriter w, es) -> Left <$> w writerOpts{ writerExtensions = es } doc) <#> parameter peekPandoc "Pandoc" "doc" "document to convert" - <#> opt (parameter peekFlavoredFormat "string|table" - "formatspec" "format and extensions") - <#> opt (parameter peekWriterOptions "WriterOptions" "writer_options" - "writer options") + <#> opt (parameter peekFlavoredFormat "string|table" "formatspec" + (T.unlines + [ "format specification; defaults to `\"html\"`. See the" + , "documentation of [`pandoc.read`](#pandoc.read) for a complete" + , "description of this parameter." + ])) + <#> opt (parameter peekWriterOptions "WriterOptions|table" "writer_options" + (T.unlines + [ "options passed to the writer; may be a WriterOptions object" + , "or a table with a subset of the keys and values of a" + , "WriterOptions object; defaults to the default values" + , "documented in the manual." + ]) + ) =#> functionResult (either pushLazyByteString pushText) "string" "result document" + #? T.unlines + [ "Converts a document to the given target format." + , "" + , "Usage:" + , "" + , " local doc = pandoc.Pandoc(" + , " {pandoc.Para {pandoc.Strong 'Tea'}}" + , " )" + , " local html = pandoc.write(doc, 'html')" + , " assert(html == '

Tea

')" + ] , defun "write_classic" ### (\doc mwopts -> runCustom (fromMaybe def mwopts) doc) <#> parameter peekPandoc "Pandoc" "doc" "document to convert" <#> opt (parameter peekWriterOptions "WriterOptions" "writer_options" - "writer options") + (T.unlines + [ "options passed to the writer; may be a WriterOptions object" + , "or a table with a subset of the keys and values of a" + , "WriterOptions object; defaults to the default values" + , "documented in the manual." + ])) =#> functionResult pushText "string" "rendered document" #? (T.unlines [ "Runs a classic custom Lua writer, using the functions defined" , "in the current environment." + , "" + , "Usage:" + , "" + , " -- Adding this function converts a classic writer into a" + , " -- new-style custom writer." + , " function Writer (doc, opts)" + , " PANDOC_DOCUMENT = doc" + , " PANDOC_WRITER_OPTIONS = opts" + , " loadfile(PANDOC_SCRIPT_FILE)()" + , " return pandoc.write_classic(doc, opts)" + , " end" ]) ] where -- cgit v1.2.3