Fix `menu_lua_api.txt` formatting (#12971)

1 files changed, 203 insertions, 198 deletions

diff --git a/doc/menu_lua_api.txt b/doc/menu_lua_api.txt
index 661e378d5..ad07ea732 100644
--- a/doc/menu_lua_api.txt
+++ b/doc/menu_lua_api.txt
@@ -4,99 +4,100 @@ Minetest Lua Mainmenu API Reference 5.7.0
 Introduction
 -------------
 
-The main menu is defined as a formspec by Lua in builtin/mainmenu/
-Description of formspec language to show your menu is in lua_api.txt
+The main menu is defined as a formspec by Lua in `builtin/mainmenu/`
+Description of formspec language to show your menu is in `lua_api.txt`
 
 
 Callbacks
 ---------
 
-core.button_handler(fields): called when a button is pressed.
-^ fields = {name1 = value1, name2 = value2, ...}
-core.event_handler(event)
-^ event: "MenuQuit", "KeyEnter", "ExitButton" or "EditBoxEnter"
+* `core.button_handler(fields)`: called when a button is pressed.
+  * `fields` = `{name1 = value1, name2 = value2, ...}`
+* `core.event_handler(event)`
+  * `event`: `"MenuQuit"`, `"KeyEnter"`, `"ExitButton"` or `"EditBoxEnter"`
 
 
 Gamedata
 --------
 
-The "gamedata" table is read when calling core.start(). It should contain:
-{
-    playername     = <name>,
-    password       = <password>,
-    address        = <IP/address>,
-    port           = <port>,
-    selected_world = <index>, -- 0 for client mode
-    singleplayer   = <true/false>,
-}
+The "gamedata" table is read when calling `core.start()`. It should contain:
+
+    {
+        playername     = <name>,
+        password       = <password>,
+        address        = <IP/address>,
+        port           = <port>,
+        selected_world = <index>, -- 0 for client mode
+        singleplayer   = <true/false>,
+    }
 
 
 Functions
 ---------
 
-core.start()
-core.close()
-core.get_min_supp_proto()
-^ returns the minimum supported network protocol version
-core.get_max_supp_proto()
-^ returns the maximum supported network protocol version
-core.open_url(url)
-^ opens the URL in a web browser, returns false on failure.
-^ Must begin with http:// or https://
-core.open_dir(path)
-^ opens the path in the system file browser/explorer, returns false on failure.
-^ Must be an existing directory.
-core.share_file(path)
-^ Android only. Shares file using the share popup
-core.get_version() (possible in async calls)
-^ returns current core version
+* `core.start()`
+* `core.close()`
+* `core.get_min_supp_proto()`
+  * returns the minimum supported network protocol version
+* `core.get_max_supp_proto()`
+  * returns the maximum supported network protocol version
+* `core.open_url(url)`
+  * opens the URL in a web browser, returns false on failure.
+  * Must begin with http:// or https://
+* `core.open_dir(path)`
+  * opens the path in the system file browser/explorer, returns false on failure.
+  * Must be an existing directory.
+* `core.share_file(path)`
+  * Android only. Shares file using the share popup
+* `core.get_version()` (possible in async calls)
+  * returns current core version
 
 
 
 Filesystem
 ----------
 
-core.get_builtin_path()
-^ returns path to builtin root
-core.create_dir(absolute_path) (possible in async calls)
-^ absolute_path to directory to create (needs to be absolute)
-^ returns true/false
-core.delete_dir(absolute_path) (possible in async calls)
-^ absolute_path to directory to delete (needs to be absolute)
-^ returns true/false
-core.copy_dir(source,destination,keep_source) (possible in async calls)
-^ source folder
-^ destination folder
-^ keep_source DEFAULT true --> if set to false source is deleted after copying
-^ returns true/false
-core.is_dir(path) (possible in async calls)
-^ returns true if path is a valid dir
-core.extract_zip(zipfile,destination) [unzip within path required]
-^ zipfile to extract
-^ destination folder to extract to
-^ returns true/false
-core.sound_play(spec, looped) -> handle
-^ spec = SimpleSoundSpec (see lua_api.txt)
-^ looped = bool
-core.sound_stop(handle)
-core.get_video_drivers()
-^ get list of video drivers supported by engine (not all modes are guaranteed to work)
-^ returns list of available video drivers' settings name and 'friendly' display name
-^ e.g. { {name="opengl", friendly_name="OpenGL"}, {name="software", friendly_name="Software Renderer"} }
-^ first element of returned list is guaranteed to be the NULL driver
-core.get_mapgen_names([include_hidden=false]) -> table of map generator algorithms
+* `core.get_builtin_path()`
+  * returns path to builtin root
+* `core.create_dir(absolute_path)` (possible in async calls)
+  * `absolute_path` to directory to create (needs to be absolute)
+  * returns true/false
+* `core.delete_dir(absolute_path)` (possible in async calls)
+  * `absolute_path` to directory to delete (needs to be absolute)
+  * returns true/false
+* `core.copy_dir(source,destination,keep_source)` (possible in async calls)
+  * `source` folder
+  * `destination` folder
+  * `keep_source` DEFAULT true --> if set to false `source` is deleted after copying
+  * returns true/false
+* `core.is_dir(path)` (possible in async calls)
+  * returns true if `path` is a valid dir
+* `core.extract_zip(zipfile,destination)` [unzip within path required]
+  * `zipfile` to extract
+  * `destination` folder to extract to
+  * returns true/false
+* `core.sound_play(spec, looped)` -> handle
+  * `spec` = `SimpleSoundSpec` (see `lua_api.txt`)
+  * `looped` = bool
+* `core.sound_stop(handle)`
+* `core.get_video_drivers()`
+  * get list of video drivers supported by engine (not all modes are guaranteed to work)
+  * returns list of available video drivers' settings name and 'friendly' display name
+    e.g. `{ {name="opengl", friendly_name="OpenGL"}, {name="software", friendly_name="Software Renderer"} }`
+  * first element of returned list is guaranteed to be the NULL driver
+* `core.get_mapgen_names([include_hidden=false])` -> table of map generator algorithms
     registered in the core (possible in async calls)
-core.get_cache_path() -> path of cache
-core.get_temp_path([param]) (possible in async calls)
-^ param=true: returns path to a temporary file
-^ otherwise: returns path to the temporary folder
+* `core.get_cache_path()` -> path of cache
+* `core.get_temp_path([param])` (possible in async calls)
+  * `param`=true: returns path to a temporary file
+    otherwise: returns path to the temporary folder
 
 
 HTTP Requests
 -------------
 
-* core.download_file(url, target) (possible in async calls)
-    * url to download, and target to store to
+* `core.download_file(url, target)` (possible in async calls)
+    * `url` to download, and `target` to store to
     * returns true/false
 * `minetest.get_http_api()` (possible in async calls)
     * returns `HTTPApiTable` containing http functions.
@@ -108,7 +109,7 @@ HTTP Requests
 * `HTTPApiTable.fetch_async(HTTPRequest req)`: returns handle
     * Performs given request asynchronously and returns handle for
       `HTTPApiTable.fetch_async_get`
-* `HTTPApiTable.fetch_async_get(handle)`: returns HTTPRequestResult
+* `HTTPApiTable.fetch_async_get(handle)`: returns `HTTPRequestResult`
     * Return response data for given asynchronous HTTP request
 
 ### `HTTPRequest` definition
@@ -167,50 +168,52 @@ Passed to `HTTPApiTable.fetch` callback. Returned by
 Formspec
 --------
 
-core.update_formspec(formspec)
-core.get_table_index(tablename) -> index
-^ can also handle textlists
-core.formspec_escape(string) -> string
-^ escapes characters [ ] \ , ; that cannot be used in formspecs
-core.explode_table_event(string) -> table
-^ returns e.g. {type="CHG", row=1, column=2}
-^ type: "INV" (no row selected), "CHG" (selected) or "DCL" (double-click)
-core.explode_textlist_event(string) -> table
-^ returns e.g. {type="CHG", index=1}
-^ type: "INV" (no row selected), "CHG" (selected) or "DCL" (double-click)
-core.set_formspec_prepend(formspec)
-^ string to be added to every mainmenu formspec, to be used for theming.
+* `core.update_formspec(formspec)`
+* `core.get_table_index(tablename)` -> index
+  * can also handle textlists
+* `core.formspec_escape(string)` -> string
+  * escapes characters [ ] \ , ; that cannot be used in formspecs
+* `core.explode_table_event(string)` -> table
+  * returns e.g. `{type="CHG", row=1, column=2}`
+  * `type`: "INV" (no row selected), "CHG" (selected) or "DCL" (double-click)
+* `core.explode_textlist_event(string)` -> table
+  * returns e.g. `{type="CHG", index=1}`
+  * `type`: "INV" (no row selected), "CHG" (selected) or "DCL" (double-click)
+* `core.set_formspec_prepend(formspec)`
+  * `formspec`: string to be added to every mainmenu formspec, to be used for theming.
 
 
 GUI
 ---
 
-core.set_background(type, texturepath,[tile],[minsize])
-^ type: "background", "overlay", "header" or "footer"
-^ tile: tile the image instead of scaling (background only)
-^ minsize: minimum tile size, images are scaled to at least this size prior
-^   doing tiling (background only)
-core.set_clouds(<true/false>)
-core.set_topleft_text(text)
-core.show_keys_menu()
-core.show_path_select_dialog(formname, caption, is_file_select)
-^ shows a path select dialog
-^ formname is base name of dialog response returned in fields
-^     -if dialog was accepted "_accepted"
-^        will be added to fieldname containing the path
-^     -if dialog was canceled "_cancelled"
-^        will be added to fieldname value is set to formname itself
-^ if `is_file_select` is `true`, a file and not a folder will be selected
-^ returns nil or selected file/folder
-core.get_screen_info()
-^ returns {
-    density         = <screen density 0.75,1.0,2.0,3.0 ... (dpi)>,
-    display_width   = <width of display>,
-    display_height  = <height of display>,
-    window_width    = <current window width>,
-    window_height   = <current window height>,
-    render_info     = <active render information>
-    }
+* `core.set_background(type,texturepath,[tile],[minsize])`
+  * `type`: "background", "overlay", "header" or "footer"
+  * `tile`: tile the image instead of scaling (background only)
+  * `minsize`: minimum tile size, images are scaled to at least this size prior
+   doing tiling (background only)
+* `core.set_clouds(<true/false>)`
+* `core.set_topleft_text(text)`
+* `core.show_keys_menu()`
+* `core.show_path_select_dialog(formname, caption, is_file_select)`
+  * shows a path select dialog
+  * `formname` is base name of dialog response returned in fields
+     - if dialog was accepted `"_accepted"`
+        will be added to fieldname containing the path
+     - if dialog was canceled `"_cancelled"`
+        will be added to fieldname value is set to formname itself
+  * if `is_file_select` is `true`, a file and not a folder will be selected
+  * returns nil or selected file/folder
+* `core.get_screen_info()`
+  * returns
+
+        {
+          density         = <screen density 0.75,1.0,2.0,3.0 ... (dpi)>,
+          display_width   = <width of display>,
+          display_height  = <height of display>,
+          window_width    = <current window width>,
+          window_height   = <current window height>,
+          render_info     = <active render information>
+        }
 
 
 Content and Packages
@@ -219,14 +222,14 @@ Content and Packages
 Content - an installed mod, modpack, game, or texture pack (txt)
 Package - content which is downloadable from the content db, may or may not be installed.
 
-* core.get_user_path() (possible in async calls)
+* `core.get_user_path()` (possible in async calls)
     * returns path to global user data,
       the directory that contains user-provided mods, worlds, games, and texture packs.
-* core.get_modpath() (possible in async calls)
+* `core.get_modpath()` (possible in async calls)
     * returns path to global modpath in the user path, where mods can be installed
-* core.get_modpaths() (possible in async calls)
+* `core.get_modpaths()` (possible in async calls)
     * returns table of virtual path to global modpaths, where mods have been installed
-      The difference with "core.get_modpath" is that no mods should be installed in these
+      The difference with `core.get_modpath` is that no mods should be installed in these
       directories by Minetest -- they might be read-only.
 
       Ex:
@@ -241,133 +244,135 @@ Package - content which is downloadable from the content db, may or may not be i
       }
       ```
 
-* core.get_clientmodpath() (possible in async calls)
+* `core.get_clientmodpath()` (possible in async calls)
     * returns path to global client-side modpath
-* core.get_gamepath() (possible in async calls)
+* `core.get_gamepath()` (possible in async calls)
     * returns path to global gamepath
-* core.get_texturepath() (possible in async calls)
+* `core.get_texturepath()` (possible in async calls)
     * returns path to default textures
-* core.get_games() -> table of all games (possible in async calls)
+* `core.get_games()` -> table of all games (possible in async calls)
     * `name` in return value is deprecated, use `title` instead.
     * returns a table (ipairs) with values:
 
-        {
-            id               = <id>,
-            path             = <full path to game>,
-            gamemods_path    = <path>,
-            title            = <title of game>,
-            menuicon_path    = <full path to menuicon>,
-            author           = "author",
-            DEPRECATED:
-            addon_mods_paths = {[1] = <path>,},
-        }
-* core.get_content_info(path)
+          {
+              id               = <id>,
+              path             = <full path to game>,
+              gamemods_path    = <path>,
+              title            = <title of game>,
+              menuicon_path    = <full path to menuicon>,
+              author           = "author",
+              DEPRECATED:
+              addon_mods_paths = {[1] = <path>,},
+          }
+* `core.get_content_info(path)`
     * returns
 
-        {
-            name             = "technical_id",
-            type             = "mod" or "modpack" or "game" or "txp",
-            title            = "Human readable title",
-            description      = "description",
-            author           = "author",
-            path             = "path/to/content",
-            depends          = {"mod", "names"}, -- mods only
-            optional_depends = {"mod", "names"}, -- mods only
-        }
-* core.check_mod_configuration(world_path, mod_paths)
+          {
+              name             = "technical_id",
+              type             = "mod" or "modpack" or "game" or "txp",
+              title            = "Human readable title",
+              description      = "description",
+              author           = "author",
+              path             = "path/to/content",
+              depends          = {"mod", "names"}, -- mods only
+              optional_depends = {"mod", "names"}, -- mods only
+          }
+* `core.check_mod_configuration(world_path, mod_paths)`
     * Checks whether configuration is valid.
     * `world_path`: path to the world
     * `mod_paths`: list of enabled mod paths
     * returns:
 
-        {
-            is_consistent = true,  -- true is consistent, false otherwise
-            unsatisfied_mods = {},  -- list of mod specs
-            satisfied_mods = {}, -- list of mod specs
-            error_message = "",  -- message or nil
-        }
+          {
+              is_consistent = true,  -- true is consistent, false otherwise
+              unsatisfied_mods = {},  -- list of mod specs
+              satisfied_mods = {}, -- list of mod specs
+              error_message = "",  -- message or nil
+          }
 
 Logging
 -------
 
-core.debug(line) (possible in async calls)
-^ Always printed to stderr and logfile (print() is redirected here)
-core.log(line) (possible in async calls)
-core.log(loglevel, line) (possible in async calls)
-^ loglevel one of "error", "action", "info", "verbose"
+* `core.debug(line)` (possible in async calls)
+  * Always printed to `stderr` and logfile (`print()` is redirected here)
+* `core.log(line)` (possible in async calls)
+* `core.log(loglevel, line)` (possible in async calls)
+  * `loglevel` one of "error", "action", "info", "verbose"
 
 
 Settings
 --------
 
-core.settings:set(name, value)
-core.settings:get(name) -> string or nil (possible in async calls)
-core.settings:set_bool(name, value)
-core.settings:get_bool(name) -> bool or nil (possible in async calls)
-core.settings:save() -> nil, save all settings to config file
+* `core.settings:set(name, value)`
+* `core.settings:get(name)` -> string or nil (possible in async calls)
+* `core.settings:set_bool(name, value)`
+* `core.settings:get_bool(name)` -> bool or nil (possible in async calls)
+* `core.settings:save()` -> nil, save all settings to config file
 
-For a complete list of methods of the Settings object see
+For a complete list of methods of the `Settings` object see
 [lua_api.txt](https://github.com/minetest/minetest/blob/master/doc/lua_api.txt)
 
 
 Worlds
 ------
 
-core.get_worlds() -> list of worlds (possible in async calls)
-^ returns {
-    [1] = {
-    path   = <full path to world>,
-    name   = <name of world>,
-    gameid = <gameid of world>,
-    },
-}
-core.create_world(worldname, gameid, init_settings)
-core.delete_world(index)
+* `core.get_worlds()` -> list of worlds (possible in async calls)
+  * returns
+
+        {
+           [1] = {
+           path   = <full path to world>,
+           name   = <name of world>,
+           gameid = <gameid of world>,
+           },
+        }
+* `core.create_world(worldname, gameid, init_settings)`
+* `core.delete_world(index)`
 
 
 Helpers
 -------
 
-core.get_us_time()
-^ returns time with microsecond precision
-core.gettext(string) -> string
-^ look up the translation of a string in the gettext message catalog
-fgettext_ne(string, ...)
-^ call core.gettext(string), replace "$1"..."$9" with the given
-^ extra arguments and return the result
-fgettext(string, ...) -> string
-^ same as fgettext_ne(), but calls core.formspec_escape before returning result
-core.parse_json(string[, nullvalue]) -> something (possible in async calls)
-^ see core.parse_json (lua_api.txt)
-dump(obj, dumped={})
-^ Return object serialized as a string
-string:split(separator)
-^ eg. string:split("a,b", ",") == {"a","b"}
-string:trim()
-^ eg. string.trim("\n \t\tfoo bar\t ") == "foo bar"
-core.is_yes(arg) (possible in async calls)
-^ returns whether arg can be interpreted as yes
-minetest.encode_base64(string) (possible in async calls)
-^ Encodes a string in base64.
-minetest.decode_base64(string) (possible in async calls)
-^ Decodes a string encoded in base64.
+* `core.get_us_time()`
+  * returns time with microsecond precision
+* `core.gettext(string)` -> string
+  * look up the translation of a string in the gettext message catalog
+* `fgettext_ne(string, ...)`
+  * call `core.gettext(string)`, replace "$1"..."$9" with the given
+  extra arguments and return the result
+* `fgettext(string, ...)` -> string
+  * same as `fgettext_ne()`, but calls `core.formspec_escape` before returning result
+* `core.parse_json(string[, nullvalue])` -> something (possible in async calls)
+  * see `core.parse_json` (`lua_api.txt`)
+* `dump(obj, dumped={})`
+  * Return object serialized as a string
+* `string:split(separator)`
+  * eg. `string:split("a,b", ",")` == `{"a","b"}`
+* `string:trim()`
+  * eg. `string.trim("\n \t\tfoo bar\t ")` == `"foo bar"`
+* `core.is_yes(arg)` (possible in async calls)
+  * returns whether `arg` can be interpreted as yes
+* `minetest.encode_base64(string)` (possible in async calls)
+  * Encodes a string in base64.
+* `minetest.decode_base64(string)` (possible in async calls)
+  * Decodes a string encoded in base64.
 
 
 Async
 -----
 
-core.handle_async(async_job,parameters,finished)
-^ execute a function asynchronously
-^ async_job is a function receiving one parameter and returning one parameter
-^ parameters parameter table passed to async_job
-^ finished function to be called once async_job has finished
-^    the result of async_job is passed to this function
-
-Limitations of Async operations
- -No access to global lua variables, don't even try
- -Limited set of available functions
-    e.g. No access to functions modifying menu like core.start,core.close,
-    core.show_path_select_dialog
+* `core.handle_async(async_job,parameters,finished)`
+  * execute a function asynchronously
+  * `async_job` is a function receiving one parameter and returning one parameter
+  * `parameters` parameter table passed to `async_job`
+  * `finished` function to be called once `async_job` has finished
+    the result of `async_job` is passed to this function
+
+### Limitations of Async operations
+ * No access to global lua variables, don't even try
+ * Limited set of available functions
+    e.g. No access to functions modifying menu like `core.start`, `core.close`,
+    `core.show_path_select_dialog`
 
 
 Background music