Lua_api.txt: Split long lines part 3

1 files changed, 128 insertions, 86 deletions

diff --git a/doc/lua_api.txt b/doc/lua_api.txt
index 9e9356be6..1c8766de8 100644
--- a/doc/lua_api.txt
+++ b/doc/lua_api.txt
@@ -2854,19 +2854,20 @@ handler.
     * Set node on all positions set in the first argument.
     * e.g. `minetest.bulk_set_node({{x=0, y=1, z=1}, {x=1, y=2, z=2}}, {name="default:stone"})`
     * For node specification or position syntax see `minetest.set_node` call
-    * Faster than set_node due to single call, but still considerably slower than
-      Voxel Manipulators (LVM) for large numbers of nodes.
-      Unlike LVMs, this will call node callbacks. It also allows setting nodes in spread out
-      positions which would cause LVMs to waste memory.
-      For setting a cube, this is 1.3x faster than set_node whereas LVM is 20x faster.
+    * Faster than set_node due to single call, but still considerably slower
+      than Lua Voxel Manipulators (LVM) for large numbers of nodes.
+      Unlike LVMs, this will call node callbacks. It also allows setting nodes
+      in spread out positions which would cause LVMs to waste memory.
+      For setting a cube, this is 1.3x faster than set_node whereas LVM is 20
+      times faster.
 * `minetest.swap_node(pos, node)`
     * Set node at position, but don't remove metadata
 * `minetest.remove_node(pos)`
     * By default it does the same as `minetest.set_node(pos, {name="air"})`
 * `minetest.get_node(pos)`
     * Returns the node at the given position as table in the format
-      `{name="node_name", param1=0, param2=0}`, returns `{name="ignore", param1=0, param2=0}`
-      for unloaded areas.
+      `{name="node_name", param1=0, param2=0}`,
+      returns `{name="ignore", param1=0, param2=0}` for unloaded areas.
 * `minetest.get_node_or_nil(pos)`
     * Same as `get_node` but returns `nil` for unloaded areas.
 * `minetest.get_node_light(pos, timeofday)`
@@ -2888,36 +2889,45 @@ handler.
     * Returns `true` if successful, `false` on failure
 
 * `minetest.find_nodes_with_meta(pos1, pos2)`
-    * Get a table of positions of nodes that have metadata within a region {pos1, pos2}
+    * Get a table of positions of nodes that have metadata within a region
+      {pos1, pos2}.
 * `minetest.get_meta(pos)`
     * Get a `NodeMetaRef` at that position
 * `minetest.get_node_timer(pos)`
     * Get `NodeTimerRef`
 
-* `minetest.add_entity(pos, name, [staticdata])`: Spawn Lua-defined entity at position
+* `minetest.add_entity(pos, name, [staticdata])`: Spawn Lua-defined entity at
+  position.
     * Returns `ObjectRef`, or `nil` if failed
 * `minetest.add_item(pos, item)`: Spawn item
     * Returns `ObjectRef`, or `nil` if failed
 * `minetest.get_player_by_name(name)`: Get an `ObjectRef` to a player
-* `minetest.get_objects_inside_radius(pos, radius)`: returns a list of ObjectRefs
+* `minetest.get_objects_inside_radius(pos, radius)`: returns a list of
+  ObjectRefs.
     * `radius`: using an euclidean metric
 * `minetest.set_timeofday(val)`
     * `val` is between `0` and `1`; `0` for midnight, `0.5` for midday
 * `minetest.get_timeofday()`
-* `minetest.get_gametime()`: returns the time, in seconds, since the world was created
-* `minetest.get_day_count()`: returns number days elapsed since world was created,
-    * accounting for time changes.
-* `minetest.find_node_near(pos, radius, nodenames, [search_center])`: returns pos or `nil`
+* `minetest.get_gametime()`: returns the time, in seconds, since the world was
+  created.
+* `minetest.get_day_count()`: returns number days elapsed since world was
+  created.
+    * accounts for time changes.
+* `minetest.find_node_near(pos, radius, nodenames, [search_center])`: returns
+  pos or `nil`.
     * `radius`: using a maximum metric
     * `nodenames`: e.g. `{"ignore", "group:tree"}` or `"default:dirt"`
     * `search_center` is an optional boolean (default: `false`)
       If true `pos` is also checked for the nodes
-* `minetest.find_nodes_in_area(pos1, pos2, nodenames)`: returns a list of positions
+* `minetest.find_nodes_in_area(pos1, pos2, nodenames)`: returns a list of
+  positions.
     * `nodenames`: e.g. `{"ignore", "group:tree"}` or `"default:dirt"`
     * First return value: Table with all node positions
-    * Second return value: Table with the count of each node with the node name as index
+    * Second return value: Table with the count of each node with the node name
+      as index.
     * Area volume is limited to 4,096,000 nodes
-* `minetest.find_nodes_in_area_under_air(pos1, pos2, nodenames)`: returns a list of positions
+* `minetest.find_nodes_in_area_under_air(pos1, pos2, nodenames)`: returns a
+  list of positions.
     * `nodenames`: e.g. `{"ignore", "group:tree"}` or `"default:dirt"`
     * Return value: Table with all node positions with a node air above
     * Area volume is limited to 4,096,000 nodes
@@ -2991,7 +3001,8 @@ handler.
 * `minetest.get_mapgen_setting(name)`
     * Gets the *active* mapgen setting (or nil if none exists) in string
       format with the following order of precedence:
-        1) Settings loaded from map_meta.txt or overrides set during mod execution
+        1) Settings loaded from map_meta.txt or overrides set during mod
+           execution.
         2) Settings set by mods without a metafile override
         3) Settings explicitly set in the user config file, minetest.conf
         4) Settings set as the user config default
@@ -3026,25 +3037,31 @@ handler.
 * `minetest.clear_objects([options])`
     * Clear all objects in the environment
     * Takes an optional table as an argument with the field `mode`.
-        * mode = `"full"`: Load and go through every mapblock, clearing objects (default).
-        * mode = `"quick"`: Clear objects immediately in loaded mapblocks;
-          clear objects in unloaded mapblocks only when the mapblocks are next activated.
+        * mode = `"full"` : Load and go through every mapblock, clearing
+                            objects (default).
+        * mode = `"quick"`: Clear objects immediately in loaded mapblocks,
+                            clear objects in unloaded mapblocks only when the
+                            mapblocks are next activated.
 * `minetest.emerge_area(pos1, pos2, [callback], [param])`
-    * Queue all blocks in the area from `pos1` to `pos2`, inclusive, to be asynchronously
-      fetched from memory, loaded from disk, or if inexistent, generates them.
-    * If `callback` is a valid Lua function, this will be called for each block emerged.
+    * Queue all blocks in the area from `pos1` to `pos2`, inclusive, to be
+      asynchronously fetched from memory, loaded from disk, or if inexistent,
+      generates them.
+    * If `callback` is a valid Lua function, this will be called for each block
+      emerged.
     * The function signature of callback is:
         * `function EmergeAreaCallback(blockpos, action, calls_remaining, param)`
-            * `blockpos` is the *block* coordinates of the block that had been emerged
+            * `blockpos` is the *block* coordinates of the block that had been
+              emerged.
             * `action` could be one of the following constant values:
                 * `minetest.EMERGE_CANCELLED`
                 * `minetest.EMERGE_ERRORED`
                 * `minetest.EMERGE_FROM_MEMORY`
                 * `minetest.EMERGE_FROM_DISK`
                 * `minetest.EMERGE_GENERATED`
-            * `calls_remaining` is the number of callbacks to be expected after this one
-            * `param` is the user-defined parameter passed to emerge_area (or nil if the
-              parameter was absent)
+            * `calls_remaining` is the number of callbacks to be expected after
+              this one.
+            * `param` is the user-defined parameter passed to emerge_area (or
+              nil if the parameter was absent).
 * `minetest.delete_area(pos1, pos2)`
     * delete all mapblocks in the area from pos1 to pos2, inclusive
 * `minetest.line_of_sight(pos1, pos2)`: returns `boolean, pos`
@@ -3061,10 +3078,12 @@ handler.
     * `liquids' : if false, liquid nodes won't be returned. Default is `false`.
 * `minetest.find_path(pos1,pos2,searchdistance,max_jump,max_drop,algorithm)`
     * returns table containing path
-    * returns a table of 3D points representing a path from `pos1` to `pos2` or `nil`
+    * returns a table of 3D points representing a path from `pos1` to `pos2` or
+      `nil`.
     * `pos1`: start position
     * `pos2`: end position
-    * `searchdistance`: number of blocks to search in each direction using a maximum metric
+    * `searchdistance`: number of blocks to search in each direction using a
+      maximum metric.
     * `max_jump`: maximum height difference to consider walkable
     * `max_drop`: maximum height difference to consider droppable
     * `algorithm`: One of `"A*_noprefetch"` (default), `"A*"`, `"Dijkstra"`
@@ -3109,22 +3128,23 @@ handler.
     * spread these updates to neighbours and can cause a cascade
       of nodes to fall.
 * `minetest.get_spawn_level(x, z)`
-    * Returns a player spawn y co-ordinate for the provided (x, z) co-ordinates,
-      or `nil` for an unsuitable spawn point.
+    * Returns a player spawn y co-ordinate for the provided (x, z)
+      co-ordinates, or `nil` for an unsuitable spawn point.
     * For most mapgens a 'suitable spawn point' is one with y between
       `water_level` and `water_level + 16`, and in mgv7 well away from rivers,
       so `nil` will be returned for many (x, z) co-ordinates.
     * The spawn level returned is for a player spawn in unmodified terrain.
-    * The spawn level is intentionally above terrain level to cope with full-node
-      biome 'dust' nodes.
+    * The spawn level is intentionally above terrain level to cope with
+      full-node biome 'dust' nodes.
 
 ### Mod channels
 You can find mod channels communication scheme in `docs/mod_channels.png`.
 
 * `minetest.mod_channel_join(channel_name)`
     * Server joins channel `channel_name`, and creates it if necessary. You
-      should listen from incoming messages with `minetest.register_on_modchannel_message`
-      call to receive incoming messages
+      should listen from incoming messages with
+      `minetest.register_on_modchannel_message` call to receive incoming
+      messages.
 
 ### Inventory
 `minetest.get_inventory(location)`: returns an `InvRef`
@@ -3133,14 +3153,17 @@ You can find mod channels communication scheme in `docs/mod_channels.png`.
     * `{type="player", name="celeron55"}`
     * `{type="node", pos={x=, y=, z=}}`
     * `{type="detached", name="creative"}`
-* `minetest.create_detached_inventory(name, callbacks, [player_name])`: returns an `InvRef`
+* `minetest.create_detached_inventory(name, callbacks, [player_name])`: returns
+  an `InvRef`.
     * callbacks: See "Detached inventory callbacks"
-    * `player_name`: Make detached inventory available to one player exclusively,
-      by default they will be sent to every player (even if not used).
-      Note that this parameter is mostly just a workaround and will be removed in future releases.
+    * `player_name`: Make detached inventory available to one player
+      exclusively, by default they will be sent to every player (even if not
+      used).
+      Note that this parameter is mostly just a workaround and will be removed
+      in future releases.
     * Creates a detached inventory. If it already exists, it is cleared.
 * `minetest.do_item_eat(hp_change, replace_with_item, itemstack, user, pointed_thing)`:
-  returns left over ItemStack
+  returns left over ItemStack.
     * See `minetest.item_eat` and `minetest.register_on_item_eat`
 
 ### Formspec
@@ -3151,13 +3174,16 @@ You can find mod channels communication scheme in `docs/mod_channels.png`.
     * `formspec`: formspec to display
 * `minetest.close_formspec(playername, formname)`
     * `playername`: name of player to close formspec
-    * `formname`: has to exactly match the one given in `show_formspec`, or the formspec will
-      not close.
-    * calling `show_formspec(playername, formname, "")` is equal to this expression
+    * `formname`: has to exactly match the one given in `show_formspec`, or the
+      formspec will not close.
+    * calling `show_formspec(playername, formname, "")` is equal to this
+      expression.
     * to close a formspec regardless of the formname, call
-      `minetest.close_formspec(playername, "")`. **USE THIS ONLY WHEN ABSOLUTELY NECESSARY!**
+      `minetest.close_formspec(playername, "")`.
+      **USE THIS ONLY WHEN ABSOLUTELY NECESSARY!**
 * `minetest.formspec_escape(string)`: returns a string
-    * escapes the characters "[", "]", "\", "," and ";", which can not be used in formspecs
+    * escapes the characters "[", "]", "\", "," and ";", which can not be used
+      in formspecs.
 * `minetest.explode_table_event(string)`: returns a table
     * returns e.g. `{type="CHG", row=1, column=2}`
     * `type` is one of:
@@ -3183,26 +3209,31 @@ You can find mod channels communication scheme in `docs/mod_channels.png`.
 * `minetest.get_pointed_thing_position(pointed_thing, above)`
     * Get position of a `pointed_thing` (that you can get from somewhere)
 * `minetest.dir_to_facedir(dir, is6d)`
-    * Convert a vector to a facedir value, used in `param2` for `paramtype2="facedir"`;
-    * passing something non-`nil`/`false` for the optional second parameter causes it to
-      take the y component into account
+    * Convert a vector to a facedir value, used in `param2` for
+      `paramtype2="facedir"`.
+    * passing something non-`nil`/`false` for the optional second parameter
+      causes it to take the y component into account.
 * `minetest.facedir_to_dir(facedir)`
-    * Convert a facedir back into a vector aimed directly out the "back" of a node
+    * Convert a facedir back into a vector aimed directly out the "back" of a
+      node.
 * `minetest.dir_to_wallmounted(dir)`
-    * Convert a vector to a wallmounted value, used for `paramtype2="wallmounted"`
+    * Convert a vector to a wallmounted value, used for
+      `paramtype2="wallmounted"`.
 * `minetest.wallmounted_to_dir(wallmounted)`
-    * Convert a wallmounted value back into a vector aimed directly out the "back" of a node
+    * Convert a wallmounted value back into a vector aimed directly out the
+      "back" of a node.
 * `minetest.dir_to_yaw(dir)`
     * Convert a vector into a yaw (angle)
 * `minetest.yaw_to_dir(yaw)`
     * Convert yaw (angle) to a vector
 * `minetest.is_colored_paramtype(ptype)`
-    * Returns a boolean. Returns `true` if the given `paramtype2` contains color
-      information (`color`, `colorwallmounted` or `colorfacedir`).
+    * Returns a boolean. Returns `true` if the given `paramtype2` contains
+      color information (`color`, `colorwallmounted` or `colorfacedir`).
 * `minetest.strip_param2_color(param2, paramtype2)`
     * Removes everything but the color information from the
       given `param2` value.
-    * Returns `nil` if the given `paramtype2` does not contain color information
+    * Returns `nil` if the given `paramtype2` does not contain color
+      information.
 * `minetest.get_node_drops(nodename, toolname)`
     * Returns list of item names.
     * **Note**: This will be removed or modified in a future version.
@@ -3210,7 +3241,7 @@ You can find mod channels communication scheme in `docs/mod_channels.png`.
     * `input.method` = `"normal"` or `"cooking"` or `"fuel"`
     * `input.width` = for example `3`
     * `input.items` = for example
-      `{ stack1, stack2, stack3, stack4, stack 5, stack 6, stack 7, stack 8, stack 9 }`
+      `{stack1, stack2, stack3, stack4, stack 5, stack 6, stack 7, stack 8, stack 9}`
     * `output.item` = `ItemStack`, if unsuccessful: empty `ItemStack`
     * `output.time` = a number, if unsuccessful: `0`
     * `output.replacements` = list of `ItemStack`s that couldn't be placed in
@@ -3222,34 +3253,35 @@ You can find mod channels communication scheme in `docs/mod_channels.png`.
     * `input.method` = `"normal"` or `"cooking"` or `"fuel"`
     * `input.width` = for example `3`
     * `input.items` = for example
-      `{ stack1, stack2, stack3, stack4, stack 5, stack 6, stack 7, stack 8, stack 9 }`
+      `{stack1, stack2, stack3, stack4, stack 5, stack 6, stack 7, stack 8, stack 9}`
         * `input.items` = `nil` if no recipe found
 * `minetest.get_all_craft_recipes(query item)`: returns a table or `nil`
     * returns indexed table with all registered recipes for query item (node)
-      or `nil` if no recipe was found
+      or `nil` if no recipe was found.
     * recipe entry table:
 
-            {
-                method = 'normal' or 'cooking' or 'fuel'
-                width = 0-3, 0 means shapeless recipe
-                items = indexed [1-9] table with recipe items
-                output = string with item name and quantity
-            }
+          {
+              method = 'normal' or 'cooking' or 'fuel'
+              width = 0-3, 0 means shapeless recipe
+              items = indexed [1-9] table with recipe items
+              output = string with item name and quantity
+          }
     * Example query for `"default:gold_ingot"` will return table:
 
-            {
-                [1]={method = "cooking", width = 3, output = "default:gold_ingot",
-                items = {1 = "default:gold_lump"}},
-                [2]={method = "normal", width = 1, output = "default:gold_ingot 9",
-                items = {1 = "default:goldblock"}}
-            }
+          {
+              [1]={method = "cooking", width = 3, output = "default:gold_ingot",
+              items = {1 = "default:gold_lump"}},
+              [2]={method = "normal", width = 1, output = "default:gold_ingot 9",
+              items = {1 = "default:goldblock"}}
+          }
 * `minetest.handle_node_drops(pos, drops, digger)`
     * `drops`: list of itemstrings
-    * Handles drops from nodes after digging: Default action is to put them into
-      digger's inventory
+    * Handles drops from nodes after digging: Default action is to put them
+      into digger's inventory.
     * Can be overridden to get different functionality (e.g. dropping items on
       ground)
-* `minetest.itemstring_with_palette(item, palette_index)`: returns an item string
+* `minetest.itemstring_with_palette(item, palette_index)`: returns an item
+  string.
     * Creates an item string which contains palette index information
       for hardware colorization. You can use the returned string
       as an output in a craft recipe.
@@ -3270,7 +3302,8 @@ You can find mod channels communication scheme in `docs/mod_channels.png`.
   returns `{{actor, pos, time, oldnode, newnode}, ...}`
     * Find who has done something to a node, or near a node
     * `actor`: `"player:<name>"`, also `"liquid"`.
-* `minetest.rollback_revert_actions_by(actor, seconds)`: returns `boolean, log_messages`
+* `minetest.rollback_revert_actions_by(actor, seconds)`: returns
+  `boolean, log_messages`.
     * Revert latest actions of someone
     * `actor`: `"player:<name>"`, also `"liquid"`.
 
@@ -3313,7 +3346,8 @@ These functions return the leftover itemstack.
 * `minetest.sound_fade(handle, step, gain)`
     * `handle` is a handle returned by `minetest.sound_play`
     * `step` determines how fast a sound will fade.
-      Negative step will lower the sound volume, positive step will increase the sound volume
+      Negative step will lower the sound volume, positive step will increase
+      the sound volume.
     * `gain` the target gain for the fade.
 
 ### Timing
@@ -3322,7 +3356,8 @@ These functions return the leftover itemstack.
     * Optional: Variable number of arguments that are passed to `func`
 
 ### Server
-* `minetest.request_shutdown([message],[reconnect],[delay])`: request for server shutdown. Will display `message` to clients.
+* `minetest.request_shutdown([message],[reconnect],[delay])`: request for
+  server shutdown. Will display `message` to clients.
     * `reconnect` == true displays a reconnect button
     * `delay` adds an optional delay (in seconds) before shutdown.
       Negative delay cancels the current active shutdown.
@@ -3330,27 +3365,32 @@ These functions return the leftover itemstack.
 * `minetest.cancel_shutdown_requests()`: cancel current delayed shutdown
 * `minetest.get_server_status()`: returns server status string
 * `minetest.get_server_uptime()`: returns the server uptime in seconds
-* `minetest.remove_player(name)`: remove player from database (if he is not connected).
-    * As auth data is not removed, minetest.player_exists will continue to return true.
-      Call the below method as well if you want to remove auth data too.
+* `minetest.remove_player(name)`: remove player from database (if they are not
+  connected).
+    * As auth data is not removed, minetest.player_exists will continue to
+      return true. Call the below method as well if you want to remove auth
+      data too.
     * Returns a code (0: successful, 1: no such player, 2: player is connected)
 * `minetest.remove_player_auth(name)`: remove player authentication data
     * Returns boolean indicating success (false if player nonexistant)
 
 ### Bans
-* `minetest.get_ban_list()`: returns the ban list (same as `minetest.get_ban_description("")`)
+* `minetest.get_ban_list()`: returns the ban list
+  (same as `minetest.get_ban_description("")`).
 * `minetest.get_ban_description(ip_or_name)`: returns ban description (string)
 * `minetest.ban_player(name)`: ban a player
 * `minetest.unban_player_or_ip(name)`: unban player or IP address
-* `minetest.kick_player(name, [reason])`: disconnect a player with a optional reason
+* `minetest.kick_player(name, [reason])`: disconnect a player with a optional
+  reason.
 
 ### Particles
 * `minetest.add_particle(particle definition)`
-    * Deprecated: `minetest.add_particle(pos, velocity, acceleration, expirationtime,
-      size, collisiondetection, texture, playername)`
+    * Deprecated: `minetest.add_particle(pos, velocity, acceleration,
+      expirationtime, size, collisiondetection, texture, playername)`
 
 * `minetest.add_particlespawner(particlespawner definition)`
-    * Add a `ParticleSpawner`, an object that spawns an amount of particles over `time` seconds
+    * Add a `ParticleSpawner`, an object that spawns an amount of particles
+      over `time` seconds.
     * Returns an `id`, and -1 if adding didn't succeed
     * `Deprecated: minetest.add_particlespawner(amount, time,
       minpos, maxpos,
@@ -3361,8 +3401,10 @@ These functions return the leftover itemstack.
       collisiondetection, texture, playername)`
 
 * `minetest.delete_particlespawner(id, player)`
-    * Delete `ParticleSpawner` with `id` (return value from `minetest.add_particlespawner`)
-    * If playername is specified, only deletes on the player's client, otherwise on all clients
+    * Delete `ParticleSpawner` with `id` (return value from
+      `minetest.add_particlespawner`).
+    * If playername is specified, only deletes on the player's client,
+      otherwise on all clients.
 
 ### Schematics
 * `minetest.create_schematic(p1, p2, probability_list, filename, slice_prob_list)`