lua-filters.md: Partially autogenerate docs for module "pandoc"

The documentation system isn't powerful enough to generate the full
documentation automatically.

1 files changed, 84 insertions, 25 deletions

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 <[email protected]>
-   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 == '<p><strong>Tea</strong></p>')"
+    ]
 
   , 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