From c7297e552be9c265eba77e58dbd8f69be23b4131 Mon Sep 17 00:00:00 2001
From: paramat <mat.gregory@virginmedia.com>
Date: Tue, 7 Jun 2016 03:23:23 +0100
Subject: [PATCH] Lua_api.txt: Split long lines. Capitalise 'Biome API'. Minor
 edits

---
 doc/lua_api.txt | 129 ++++++++++++++++++++++++++++--------------------
 1 file changed, 76 insertions(+), 53 deletions(-)

diff --git a/doc/lua_api.txt b/doc/lua_api.txt
index 30f4d87df..ea47d0044 100644
--- a/doc/lua_api.txt
+++ b/doc/lua_api.txt
@@ -65,15 +65,19 @@ e.g.
 The game directory can contain the file minetest.conf, which will be used
 to set default settings when running the particular game.
 It can also contain a settingtypes.txt in the same format as the one in builtin.
-This settingtypes.txt will be parsed by the menu and the settings will be displayed in the "Games" category in the settings tab.
+This settingtypes.txt will be parsed by the menu and the settings will be displayed
+in the "Games" category in the settings tab.
 
 ### Menu images
 
-Games can provide custom main menu images. They are put inside a `menu` directory inside the game directory.
+Games can provide custom main menu images. They are put inside a `menu` directory
+inside the game directory.
 
-The images are named `$identifier.png`, where `$identifier` is one of `overlay,background,footer,header`.
-If you want to specify multiple images for one identifier, add additional images named like `$identifier.$n.png`, with an ascending number $n starting with 1,
-and a random image will be chosen from the provided ones.
+The images are named `$identifier.png`, where `$identifier` is
+one of `overlay,background,footer,header`.
+If you want to specify multiple images for one identifier, add additional images named
+like `$identifier.$n.png`, with an ascending number $n starting with 1, and a random
+image will be chosen from the provided ones.
 
 
 Mod load path
@@ -243,7 +247,8 @@ Example:
     default_dirt.png^default_grass_side.png
 
 `default_grass_side.png` is overlayed over `default_dirt.png`.
-The texture with the lower resolution will be automatically upscaled to the higher resolution texture.
+The texture with the lower resolution will be automatically upscaled to
+the higher resolution texture.
 
 ### Texture grouping
 Textures can be grouped together by enclosing them in `(` and `)`.
@@ -468,8 +473,8 @@ the global `minetest.registered_*` tables.
     * added to `minetest.registered_schematic` with the key of `schematic.name`
     * if `schematic.name` is nil, the key is the returned ID
     * if the schematic is loaded from a file, schematic.name is set to the filename
-    * if the function is called when loading the mod, and schematic.name is a relative path,
-    * then the current mod path will be prepended to the schematic filename
+    * if the function is called when loading the mod, and schematic.name is a relative
+      path, then the current mod path will be prepended to the schematic filename
 
 * `minetest.clear_registered_biomes()`
     * clears all biomes currently registered
@@ -1416,13 +1421,13 @@ examples.
 #### `listring[<inventory location>;<list name>]`
 * Allows to create a ring of inventory lists
 * Shift-clicking on items in one element of the ring
-* will send them to the next inventory list inside the ring
+  will send them to the next inventory list inside the ring
 * The first occurrence of an element inside the ring will
-* determine the inventory where items will be sent to
+  determine the inventory where items will be sent to
 
 #### `listring[]`
 * Shorthand for doing `listring[<inventory location>;<list name>]`
-* for the last two inventory lists added by list[...]
+  for the last two inventory lists added by list[...]
 
 #### `listcolors[<slot_bg_normal>;<slot_bg_hover>]`
 * Sets background color of slots as `ColorString`
@@ -1475,7 +1480,7 @@ examples.
 * Textual password style field; will be sent to server when a button is clicked
 * `x` and `y` position the field relative to the top left of the menu
 * `w` and `h` are the size of the field
-* fields are a set height, but will be vertically centred on `h`
+* Fields are a set height, but will be vertically centred on `h`
 * Position and size units are inventory slots
 * `name` is the name of the field as returned in fields to `on_receive_fields`
 * `label`, if not blank, will be text printed on the top left above the field
@@ -1484,7 +1489,7 @@ examples.
 * Textual field; will be sent to server when a button is clicked
 * `x` and `y` position the field relative to the top left of the menu
 * `w` and `h` are the size of the field
-* fields are a set height, but will be vertically centred on `h`
+* Fields are a set height, but will be vertically centred on `h`
 * Position and size units are inventory slots
 * `name` is the name of the field as returned in fields to `on_receive_fields`
 * `label`, if not blank, will be text printed on the top left above the field
@@ -1494,13 +1499,13 @@ examples.
     * **Note**: no extra text or more than a single variable is supported ATM.
 
 #### `field[<name>;<label>;<default>]`
-* as above, but without position/size units
-* special field for creating simple forms, such as sign text input
-* must be used without a `size[]` element
-* a "Proceed" button will be added automatically
+* As above, but without position/size units
+* Special field for creating simple forms, such as sign text input
+* Must be used without a `size[]` element
+* A "Proceed" button will be added automatically
 
 #### `textarea[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]`
-* same as fields above, but with multi-line input
+* Same as fields above, but with multi-line input
 
 #### `label[<X>,<Y>;<label>]`
 * `x` and `y` work as per field
@@ -1561,12 +1566,12 @@ examples.
 * `name` fieldname sent to server on doubleclick value is current selected element
 * `listelements` can be prepended by #RRGGBB (only) in hexadecimal format
      * if you want a listelement to start with "#" write "##"
-* index to be selected within textlist
+* Index to be selected within textlist
 * `true`/`false`: draw transparent background
-* see also `minetest.explode_textlist_event` (main menu: `engine.explode_textlist_event`)
+* See also `minetest.explode_textlist_event` (main menu: `engine.explode_textlist_event`)
 
 #### `tabheader[<X>,<Y>;<name>;<caption 1>,<caption 2>,...,<caption n>;<current_tab>;<transparent>;<draw_border>]`
-* show a tab**header** at specific position (ignores formsize)
+* Show a tab**header** at specific position (ignores formsize)
 * `x` and `y` position the itemlist relative to the top left of the menu
 * `name` fieldname data is transferred to Lua
 * `caption 1`...: name shown on top of tab
@@ -1575,24 +1580,24 @@ examples.
 * `draw_border` (optional): draw border
 
 #### `box[<X>,<Y>;<W>,<H>;<color>]`
-* simple colored semitransparent box
+* Simple colored semitransparent box
 * `x` and `y` position the box relative to the top left of the menu
 * `w` and `h` are the size of box
 * `color` is color specified as a `ColorString`
 
 #### `dropdown[<X>,<Y>;<W>;<name>;<item 1>,<item 2>, ...,<item n>;<selected idx>]`
-* show a dropdown field
+* Show a dropdown field
 * **Important note**: There are two different operation modes:
      1. handle directly on change (only changed dropdown is submitted)
      2. read the value on pressing a button (all dropdown values are available)
 * `x` and `y` position of dropdown
-* width of dropdown
-* fieldname data is transferred to Lua
-* items to be shown in dropdown
-* index of currently selected dropdown item
+* Width of dropdown
+* Fieldname data is transferred to Lua
+* Items to be shown in dropdown
+* Index of currently selected dropdown item
 
 #### `checkbox[<X>,<Y>;<name>;<label>;<selected>;<tooltip>]`
-* show a checkbox
+* Show a checkbox
 * `x` and `y`: position of checkbox
 * `name` fieldname data is transferred to Lua
 * `label` to be shown left of checkbox
@@ -1600,29 +1605,29 @@ examples.
 * `tooltip` (optional)
 
 #### `scrollbar[<X>,<Y>;<W>,<H>;<orientation>;<name>;<value>]`
-* show a scrollbar
-* there are two ways to use it:
+* Show a scrollbar
+* There are two ways to use it:
      1. handle the changed event (only changed scrollbar is available)
      2. read the value on pressing a button (all scrollbars are available)
 * `x` and `y`: position of trackbar
 * `w` and `h`: width and height
 * `orientation`:  `vertical`/`horizontal`
-* fieldname data is transferred to Lua
-* value this trackbar is set to (`0`-`1000`)
-* see also `minetest.explode_scrollbar_event` (main menu: `engine.explode_scrollbar_event`)
+* Fieldname data is transferred to Lua
+* Value this trackbar is set to (`0`-`1000`)
+* See also `minetest.explode_scrollbar_event` (main menu: `engine.explode_scrollbar_event`)
 
 #### `table[<X>,<Y>;<W>,<H>;<name>;<cell 1>,<cell 2>,...,<cell n>;<selected idx>]`
-* show scrollable table using options defined by the previous `tableoptions[]`
-* displays cells as defined by the previous `tablecolumns[]`
+* Show scrollable table using options defined by the previous `tableoptions[]`
+* Displays cells as defined by the previous `tablecolumns[]`
 * `x` and `y`: position the itemlist relative to the top left of the menu
 * `w` and `h` are the size of the itemlist
 * `name`: fieldname sent to server on row select or doubleclick
 * `cell 1`...`cell n`: cell contents given in row-major order
 * `selected idx`: index of row to be selected within table (first row = `1`)
-* see also `minetest.explode_table_event` (main menu: `engine.explode_table_event`)
+* See also `minetest.explode_table_event` (main menu: `engine.explode_table_event`)
 
 #### `tableoptions[<opt 1>;<opt 2>;...]`
-* sets options for `table[]`
+* Sets options for `table[]`
 * `color=#RRGGBB`
      * default text color (`ColorString`), defaults to `#FFFFFF`
 * `background=#RRGGBB`
@@ -1638,14 +1643,14 @@ examples.
      * only useful when there is a column of type "tree"
 
 #### `tablecolumns[<type 1>,<opt 1a>,<opt 1b>,...;<type 2>,<opt 2a>,<opt 2b>;...]`
-* sets columns for `table[]`
-* types: `text`, `image`, `color`, `indent`, `tree`
+* Sets columns for `table[]`
+* Types: `text`, `image`, `color`, `indent`, `tree`
     * `text`:   show cell contents as text
     * `image`:  cell contents are an image index, use column options to define images
     * `color`:   cell contents are a ColorString and define color of following cell
     * `indent`: cell contents are a number and define indentation of following cell
     * `tree`:   same as indent, but user can open and close subtrees (treeview-like)
-* column options:
+* Column options:
     * `align=<value>`
         * for `text` and `image`: content alignment within cells.
           Available values: `left` (default), `center`, `right`, `inline`
@@ -1948,7 +1953,8 @@ Call these functions only at load time!
 * `minetest.register_chatcommand(cmd, chatcommand definition)`
 * `minetest.register_privilege(name, definition)`
     * `definition`: `"description text"`
-    * `definition`: `{ description = "description text", give_to_singleplayer = boolean, -- default: true }`
+    * `definition`: `{ description = "description text", give_to_singleplayer = boolean}`
+      the default of `give_to_singleplayer` is true 
     * To allow players with basic_privs to grant, see basic_privs minetest.conf setting.
 * `minetest.register_authentication_handler(handler)`
     * See `minetest.builtin_auth_handler` in `builtin.lua` for reference
@@ -2669,7 +2675,8 @@ This is basically a reference to a C++ `ServerActiveObject`
 
 ##### Player-only (no-op for other objects)
 * `get_player_name()`: returns `""` if is not a player
-* `get_player_velocity()`: returns `nil` if is not a player otherwise a table {x, y, z} representing the player's instantaneous velocity in nodes/s
+* `get_player_velocity()`: returns `nil` if is not a player, otherwise a
+  table {x, y, z} representing the player's instantaneous velocity in nodes/s
 * `get_look_dir()`: get camera direction as a unit vector
 * `get_look_pitch()`: pitch in radians
 * `get_look_yaw()`: yaw in radians (wraps around pretty randomly as of now)
@@ -2783,25 +2790,40 @@ An `InvRef` is a reference to an inventory.
 A fast access data structure to store areas, and find areas near a given position or area.
 Every area has a `data` string attribute to store additional information.
 You can create an empty `AreaStore` by calling `AreaStore()`, or `AreaStore(type_name)`.
-If you chose the parameter-less constructor, a fast implementation will be automatically chosen for you.
+If you chose the parameter-less constructor, a fast implementation will be automatically
+chosen for you.
 
 #### Methods
-* `get_area(id, include_borders, include_data)`: returns the area with the id `id`. (optional) Boolean values `include_borders` and `include_data` control what's copied.
-* `get_areas_for_pos(pos, include_borders, include_data)`: returns all areas that contain the position `pos`. (optional) Boolean values `include_borders` and `include_data` control what's copied.
-* `get_areas_in_area(edge1, edge2, accept_overlap, include_borders, include_data)`: returns all areas that contain all nodes inside the area specified by `edge1` and `edge2` (inclusive). If `accept_overlap` is true, also areas are returned that have nodes in common with the specified area. (optional) Boolean values `include_borders` and `include_data` control what's copied.
-* `insert_area(edge1, edge2, data, [id])`: inserts an area into the store. Returns the new area's ID, or nil if the insertion failed. The (inclusive) positions `edge1` and `edge2` describe the area. `data` is a string stored with the area.  If passed, `id` will be used as the internal area ID, it must be a unique number between 0 and 2^32-2. If you use the `id` parameter you must always use it, or insertions are likely to fail due to conflicts.
-* `reserve(count)`: reserves resources for at most `count` many contained areas. Only needed for efficiency, and only some implementations profit.
+* `get_area(id, include_borders, include_data)`: returns the area with the id `id`.
+  (optional) Boolean values `include_borders` and `include_data` control what's copied.
+* `get_areas_for_pos(pos, include_borders, include_data)`: returns all areas that contain
+  the position `pos`. (optional) Boolean values `include_borders` and `include_data` control
+  what's copied.
+* `get_areas_in_area(edge1, edge2, accept_overlap, include_borders, include_data)`:
+  returns all areas that contain all nodes inside the area specified by `edge1` and `edge2` (inclusive).
+  If `accept_overlap` is true, also areas are returned that have nodes in common with the specified area.
+  (optional) Boolean values `include_borders` and `include_data` control what's copied.
+* `insert_area(edge1, edge2, data, [id])`: inserts an area into the store. Returns the new area's ID,
+  or nil if the insertion failed. The (inclusive) positions `edge1` and `edge2` describe the area.
+  `data` is a string stored with the area.  If passed, `id` will be used as the internal area ID,
+  it must be a unique number between 0 and 2^32-2. If you use the `id` parameter you must always use it,
+  or insertions are likely to fail due to conflicts.
+* `reserve(count)`: reserves resources for at most `count` many contained areas.
+  Only needed for efficiency, and only some implementations profit.
 * `remove_area(id)`: removes the area with the given id from the store, returns success.
-* `set_cache_params(params)`: sets params for the included prefiltering cache. Calling invalidates the cache, so that its elements have to be newly generated.
+* `set_cache_params(params)`: sets params for the included prefiltering cache.
+  Calling invalidates the cache, so that its elements have to be newly generated.
     * `params`:
       {
         enabled = boolean, -- whether to enable, default true
-        block_radius = number, -- the radius (in nodes) of the areas the cache generates prefiltered lists for, minimum 16, default 64
+        block_radius = number, -- the radius (in nodes) of the areas the cache generates
+                                  prefiltered lists for, minimum 16, default 64
         limit = number, -- the cache's size, minimum 20, default 1000
       }
 * `to_string()`: Experimental. Returns area store serialized as a (binary) string.
 * `to_file(filename)`: Experimental. Like `to_string()`, but writes the data to a file.
-* `from_string(str)`: Experimental. Deserializes string and loads it into the AreaStore.  Returns success and, optionally, an error message.
+* `from_string(str)`: Experimental. Deserializes string and loads it into the AreaStore.
+  Returns success and, optionally, an error message.
 * `from_file(filename)`: Experimental. Like `from_string()`, but reads the data from a file.
 
 ### `ItemStack`
@@ -3517,7 +3539,8 @@ Definition tables
         liquid_alternative_flowing = "", -- Flowing version of source liquid
         liquid_alternative_source = "", -- Source version of flowing liquid
         liquid_viscosity = 0, -- Higher viscosity = slower flow (max. 7)
-        liquid_renewable = true, -- Can new liquid source be created by placing two or more sources nearby?
+        liquid_renewable = true, --[[
+        ^ If true, a new liquid source can be created by placing two or more sources nearby ]]
         leveled = 0, --[[
         ^ Block contains level in param2. Value is default level, used for snow.
         ^ Don't forget to use "leveled" type nodebox. ]]
@@ -3724,7 +3747,7 @@ Definition tables
 ### Biome definition (`register_biome`)
 
 **Note**
-The biome API is still in an experimental phase and subject to change.
+The Biome API is still in an experimental phase and subject to change.
 
     {
         name = "tundra",