lua-filters: auto-generate docs for `pandoc.system` module.

4 files changed, 77 insertions, 48 deletions

diff --git a/cabal.project b/cabal.project
index 0c8050cbc..00736f005 100644
--- a/cabal.project
+++ b/cabal.project
@@ -10,5 +10,10 @@ constraints: skylighting-format-blaze-html >= 0.1.1,
 source-repository-package
   type: git
   location: https://github.com/hslua/hslua
-  tag: dd06f7b54440ba2e8f5ddd4afd7fde85abdf4bc0
+  tag: c500f19847982e11f3aff1c2077d31e5b109e2bb
+  subdir: hslua-module-system
+source-repository-package
+  type: git
+  location: https://github.com/hslua/hslua
+  tag: c500f19847982e11f3aff1c2077d31e5b109e2bb
   subdir: hslua-module-text
diff --git a/doc/lua-filters.md b/doc/lua-filters.md
index 60fb96ab3..bc99fce27 100644
--- a/doc/lua-filters.md
+++ b/doc/lua-filters.md
@@ -5016,21 +5016,23 @@ Returns:
 
 <!-- END: AUTOGENERATED CONTENT -->
 
+<!-- BEGIN: AUTOGENERATED CONTENT for module pandoc.system -->
+
 # Module pandoc.system
 
-Access to system information and functionality.
+Access to the system's information and file functionality.
 
-## Static Fields
+## Fields {#pandoc.system-fields}
 
 ### arch {#pandoc.system.arch}
 
-The machine architecture on which the program is running.
+The machine architecture on which the program is running. (string)
 
 ### os {#pandoc.system.os}
 
-The operating system on which the program is running.
+The operating system on which the program is running. (string)
 
-## Functions
+## Functions {#pandoc.system-functions}
 
 ### cputime {#pandoc.system.cputime}
 
@@ -5040,20 +5042,26 @@ Returns the number of picoseconds CPU time used by the current
 program. The precision of this result may vary in different
 versions and on different platforms.
 
-*Since*: 3.1.1
+Returns:
+
+-   CPU time in picoseconds ([integer]{unknown-type="integer"})
+
+*Since: 3.1.1*
 
 ### environment {#pandoc.system.environment}
 
 `environment ()`
 
-Retrieve the entire environment as a string-indexed table.
+Retrieves the entire environment as a string-indexed table.
 
 Returns:
 
--   A table mapping environment variables names to their string
-    value (table).
+-   A table mapping environment variable names to their value.
+    (table)
 
-### get\_working\_directory {#pandoc.system.get_working_directory}
+*Since: 2.7.3*
+
+### get_working_directory {#pandoc.system.get_working_directory}
 
 `get_working_directory ()`
 
@@ -5061,9 +5069,11 @@ Obtain the current working directory as an absolute path.
 
 Returns:
 
--   The current working directory (string).
+-   The current working directory. (string)
+
+*Since: 2.8*
 
-### list\_directory {#pandoc.system.list_directory}
+### list_directory {#pandoc.system.list_directory}
 
 `list_directory ([directory])`
 
@@ -5072,23 +5082,25 @@ List the contents of a directory.
 Parameters:
 
 `directory`
-:   Path of the directory whose contents should be listed
-    (string). Defaults to `.`.
+:   Path of the directory whose contents should be listed.
+    Defaults to `.`. (string)
 
 Returns:
 
--   A table of all entries in `directory` without the special
-    entries `.` and `..`. (list of strings)
+-   A table of all entries in `directory`, except for the special
+    entries (`.` and `..`). (table)
 
-### make\_directory {#pandoc.system.make_directory}
+*Since: 2.19*
+
+### make_directory {#pandoc.system.make_directory}
 
-`make_directory (dirname [, create_parent])`
+`make_directory (dirname[, create_parent])`
 
 Create a new directory which is initially empty, or as near to
-empty as the operating system allows. The function throws an
-error if the directory cannot be created, e.g., if the parent
-directory does not exist or if a directory of the same name is
-already present.
+empty as the operating system allows. The function throws an error
+if the directory cannot be created, e.g., if the parent directory
+does not exist or if a directory of the same name is already
+present.
 
 If the optional second parameter is provided and truthy, then all
 directories, including parent directories, are created as
@@ -5100,14 +5112,16 @@ Parameters:
 :   name of the new directory (string)
 
 `create_parent`
-:   create parent directories if necessary (boolean)
+:   create parent directory if necessary (boolean)
 
-### remove\_directory {#pandoc.system.remove_directory}
+*Since: 2.19*
 
-`remove_directory (dirname [, recursive])`
+### remove_directory {#pandoc.system.remove_directory}
 
-Remove an existing, empty directory. If `recursive` is given,
-then delete the directory and its contents recursively.
+`remove_directory (dirname[, recursive])`
+
+Remove an existing, empty directory. If `recursive` is given, then
+delete the directory and its contents recursively.
 
 Parameters:
 
@@ -5117,7 +5131,9 @@ Parameters:
 `recursive`
 :   delete content recursively (boolean)
 
-### with\_environment {#pandoc.system.with_environment}
+*Since: 2.19*
+
+### with_environment {#pandoc.system.with_environment}
 
 `with_environment (environment, callback)`
 
@@ -5131,19 +5147,20 @@ Parameters:
 
 `environment`
 :   Environment variables and their values to be set before
-    running `callback`. (table with string keys and string
-    values)
+    running `callback` (table)
 
 `callback`
 :   Action to execute in the custom environment (function)
 
 Returns:
 
--   The result(s) of the call to `callback`
+The results of the call to `callback`.
 
-### with\_temporary\_directory {#pandoc.system.with_temporary_directory}
+*Since: 2.7.3*
+
+### with_temporary_directory {#pandoc.system.with_temporary_directory}
 
-`with_temporary_directory ([parent_dir,] templ, callback)`
+`with_temporary_directory (parent_dir, templ, callback)`
 
 Create and use a temporary directory inside the given directory.
 The directory is deleted after the callback returns.
@@ -5151,22 +5168,24 @@ The directory is deleted after the callback returns.
 Parameters:
 
 `parent_dir`
-:   Parent directory to create the directory in (string). If
-    this parameter is omitted, the system's canonical temporary
-    directory is used.
+:   Parent directory to create the directory in. If this parameter
+    is omitted, the system's canonical temporary directory is
+    used. (string)
 
 `templ`
-:   Directory name template (string).
+:   Directory name template. (string)
 
 `callback`
 :   Function which takes the name of the temporary directory as
-    its first argument (function).
+    its first argument. (function)
 
 Returns:
 
--   The result of the call to `callback`.
+The results of the call to `callback`.
+
+*Since: 2.8*
 
-### with\_working\_directory {#pandoc.system.with_working_directory}
+### with_working_directory {#pandoc.system.with_working_directory}
 
 `with_working_directory (directory, callback)`
 
@@ -5186,7 +5205,11 @@ Parameters:
 
 Returns:
 
--   The result(s) of the call to `callback`
+The results of the call to `callback`.
+
+*Since: 2.7.3*
+
+<!-- END: AUTOGENERATED CONTENT -->
 
 # Module pandoc.layout
 
@@ -5760,7 +5783,6 @@ Scaffolding for custom writers.
 An object to be used as a `Writer` function; the construct handles
 most of the boilerplate, expecting only render functions for all
 AST elements (table)
-
 <!-- END: AUTOGENERATED CONTENT -->
 
 <!-- BEGIN: AUTOGENERATED CONTENT for module pandoc.text -->
diff --git a/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/System.hs b/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/System.hs
index 367b74a33..aaed54b48 100644
--- a/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/System.hs
+++ b/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/System.hs
@@ -1,5 +1,6 @@
 {-# LANGUAGE OverloadedStrings #-}
 {-# LANGUAGE ScopedTypeVariables #-}
+{-# LANGUAGE TypeApplications    #-}
 {- |
    Module      : Text.Pandoc.Lua.Module.System
    Copyright   : © 2019-2023 Albert Krewinkel
@@ -19,18 +20,19 @@ import HsLua
 import HsLua.Module.System
   ( arch, cputime, env, getwd, ls, mkdir, os, rmdir
   , with_env, with_tmpdir, with_wd)
+import qualified HsLua.Module.System as MSys
 
 -- | Push the pandoc.system module on the Lua stack.
-documentedModule :: LuaError e => Module e
+documentedModule :: forall e. LuaError e => Module e
 documentedModule = Module
   { moduleName = "pandoc.system"
-  , moduleDescription = "system functions"
+  , moduleDescription = moduleDescription @e MSys.documentedModule
   , moduleFields =
       [ arch
       , os
       ]
   , moduleFunctions =
-      [ cputime `since` makeVersion [3, 1, 1]
+      [ cputime                                        `since` v[3,1,1]
       , setName "environment" env                      `since` v[2,7,3]
       , setName "get_working_directory" getwd          `since` v[2,8]
       , setName "list_directory" ls                    `since` v[2,19]
diff --git a/tools/update-lua-module-docs.lua b/tools/update-lua-module-docs.lua
index 21044b9d6..c951d8668 100644
--- a/tools/update-lua-module-docs.lua
+++ b/tools/update-lua-module-docs.lua
@@ -280,9 +280,9 @@ if arg and arg[1] then
 end
 
 local autogen_start =
-  '<!%-%- BEGIN: AUTOGENERATED CONTENT for module ([a-z%.]+) %-%->\n'
+  '\n<!%-%- BEGIN: AUTOGENERATED CONTENT for module ([a-z%.]+) %-%->'
 local autogen_end =
-  '\n<!%-%- END: AUTOGENERATED CONTENT %-%->\n'
+  '<!%-%- END: AUTOGENERATED CONTENT %-%->\n'
 local reflinks_marker =
   '<!%-%- BEGIN: GENERATED REFERENCE LINKS %-%->\n'