Copy-editing in API.md

1 files changed, 77 insertions, 91 deletions

diff --git a/API.md b/API.md
index b7af03f..cae75ad 100644
--- a/API.md
+++ b/API.md
@@ -9,44 +9,49 @@ In the documentation system, everything is built on categories and entries.
 An entry is a single piece of documentation and is the basis of all actual
 documentation. Categories group multiple entries of the same topic together.
 
-Categories also define a template which is used to determine how the final
-result in the Entry tab looks like. Entries themselves have a data field
-attached to them, this is a table containing arbitrary metadata which is
-used to construct the final formspec which is used on the Entry tab.
+Categories also define a template function which is used to determine how the
+final result in the tab “Entry list” looks like. Entries themselves have
+a data field attached to them, this is a table containing arbitrary metadata
+which is used to construct the final formspec which is used on the Entry tab.
 
 ## Advanced concepts
 ### Viewed and hidden entries
-The mod keeps track of which entries have been viewed by any player.
+The mod keeps track of which entries have been viewed on a per-player basis.
 Any entry which has been accessed by a player is instantly marked as “viewed”.
 
 It also allows entries to be hidden. Hidden entries are not visible or
-normally accessible to players until they become revealed by function calls.
+otherwise accessible to players until they become revealed by function calls.
 
 Marking an entry as viewed or revealed is not reversible with this API.
 The viewed and hidden states are stored in the file `doc.mt` inside the
-world directory.
+world directory. You can safely delete this file if you want to reset
+the player states.
 
 ### Entry aliases
 Entry aliases are alternative identifiers for entry identifiers. With the
-exception of the alias functions themselves, When a function demands an
+exception of the alias functions themselves, for function demanding an
 `entry_id` you can either supply the original `entry_id` or any alias of the
 `entry_id`.
 
 ## Possible use cases
-I present to you some possible use cases to give you a rough idea what
+Here are some possible use cases to give you a rough idea what
 this mod is capable of and how certain use cases should be implemented.
 
 ### Simple use case: Minetest basics
-I want to write in free form short help texts about the basic concepts of
-Minetest or my subgame. First I define a category called “Basics”, the data
-for each of its entry is just a free form text. The template function simply
-creates a formspec where this free form text is displayed.
+Let's say you want to write in free form short help texts about the basic
+concepts of Minetest or your subgame. First you could define a category
+called “Basics”, the data for each of its entry is just a free form text.
+The template function simply creates a formspec where this free form
+text is displayed.
+
+This is one of the most simple use cases and the mod `doc_basics` does
+exactly that.
 
 ### Complex use case: Blocks
-I could create a category called “Blocks”, and this category is supposed to
-contain entries for every single block in the game. For this case, a free form
-approach would be very inefficient and error-prone, as a lot of data can be
-reused.
+You could create a category called “Blocks”, and this category is supposed to
+contain entries for every single block (i.e. node) in the game. For this use
+case, a free form approach would be very inefficient and error-prone, as a
+lot of data can be reused.
 
 Here the template function comes in handy: The internal entry data
 contain a lot of different things about a block, like block name, identifier,
@@ -81,34 +86,36 @@ These functions are available:
 * `doc.mark_all_entries_as_revealed`: Make all hidden entries visible and accessible to a player
 * `doc.add_entry_alias`: Add an alternative name which can be used to access an entry
 * `doc.add_entry_aliases`: Add multiple alternative names which can be used to access an entry
-* `doc.get_category_count`: Returns the total number categories
+* `doc.get_category_count`: Returns the total number of categories
 * `doc.get_entry_count`: Returns the total number of entries in a category
 * `doc.get_viewed_count`: Returns the number of entries a player has viewed in a category
 * `doc.get_revealed_count`: Returns the number of entries a player has access to in a category
 * `doc.get_hidden_count`: Returns the number of entries which are hidden from a player in a category
-* `doc.get_selection`: Returns the current viewed entry/category of a player
+* `doc.get_selection`: Returns the currently viewed entry/category of a player
+
+If not mentioned otherwise, the return value of all functions is `nil`.
 
-#### Special widgets
-This API provides an experimental convenience function for creating a special
-widget to be used in formspecs. This function may be deprecated in later versions.
+#### Special widget
+This API provides a convenience function `doc.widgets.text` for creating a
+special widget to create multi-line text.
 
 ### `doc.new_category(id, def)`
 Adds a new category. You have to define an unique identifier, a name
 and a template function to build the entry formspec from the entry
 data.
 
-**Important**: You must call this function before any player joins, but not later.
+**Important**: You must call this function *before* any player joins.
 
 #### Parameters
 * `id`: Unique category identifier as a string
-* `def`: Definition table, it has the following fields:
+* `def`: Definition table with the following fields:
     * `name`: Category name to be shown in the interface
     * `description`: (optional) Short description of the category,
        will be shown as tooltip. Recommended style (in English):
-       First letter capitalized, no punctuation at end of sentence,
+       First letter capitalized, no punctuation at the end,
        max. 100 characters
-    * `build_formspec`: The template function. Takes entry data as its
-      only parameter (has the data type of the entry data) and must
+    * `build_formspec`: The template function (see below). Takes entry data
+      as its only parameter (has the data type of the entry data) and must
       return a formspec which is inserted in the Entry tab.
     * `sorting`: (optional) Sorting algorithm for display order of entries
         * `"abc"`: Alphabetical (default)
@@ -123,21 +130,18 @@ data.
         * If `sorting=="function"`, this field is a compare function to be used as
           the `comp` parameter of `table.sort`. The parameters given are two entries.
         * This field is not required if `sorting` has any other value
-    * `hide_entries_by_default` (optional, experimental): If `true`, all entries
+    * `hide_entries_by_default` (optional): If `true`, all entries
       added to this category will start as hidden, unless explicitly specified otherwise
       (default: `false`)
 
-Note: For function-based sorting, the entries provided in the compare function have the
-following format:
+Note: For function-based sorting, the entries provided to the compare function
+will have the following format:
 
     {
         name = n, -- entry name
         data = d, -- arbitrary entry data
     }
 
-#### Return value
-Always `nil`.
-
 #### Using `build_formspec`
 For `build_formspec` you can either define your own function which
 procedurally generates the entry formspec or you use one of the
@@ -184,7 +188,7 @@ data which defines the entry. Note you do not directly define here how the
 end result of an entry looks like, this is done by `build_formspec` from
 the category definition.
 
-**Important**: You must call this function before any player joins, but not later.
+**Important**: You must call this function *before* any player joins.
 
 #### Parameters
 * `category_id`: Identifier of the category to add the entry into
@@ -197,9 +201,6 @@ the category definition.
       The data in this field will be used to create the actual formspec
       with `build_formspec` from the category definition
 
-#### Return value
-Always `nil`.
-
 ### `doc.set_category_order(category_list)`
 Sets the order of categories in the category list.
 The Documentation System starts with this default order:
@@ -216,30 +217,24 @@ second time by any mod, a warning is written into the log.
   in the category list. All unspecified categories will be appended to
   the end
 
-#### Return value
-Always `nil`.
-
 
 ### `doc.show_doc(playername)`
-Opens the main documentation formspec for the player (Main tab).
+Opens the main documentation formspec for the player (“Category list” tab).
 
 #### Parameters
 * `playername`: Name of the player to show the formspec to
 
 ### `doc.show_category(playername, category_id)`
 Opens the documentation formspec for the player at the specified category
-(Category tab).
+(“Entry list” tab).
 
 #### Parameters
 * `playername`: Name of the player to show the formspec to
 * `category_id`: Category identifier of the selected category
 
-#### Return value
-Always `nil`.
-
 ### `doc.show_entry(playername, category_id, entry_id, ignore_hidden)`
 Opens the documentation formspec for the player showing the specified entry
-of a category (Entry tab). If the entry is hidden, an error message
+of a category (“Entry” tab). If the entry is hidden, an error message
 is displayed unless `ignore_hidden==true`.
 
 #### Parameters
@@ -250,9 +245,6 @@ is displayed unless `ignore_hidden==true`.
   to the player; this will automatically reveal the entry to this player for the
   rest of the game
 
-#### Return value
-Always `nil`.
-
 ### `doc.get_category_definition(category_id)`
 Returns the definition of the specified category.
 
@@ -276,7 +268,7 @@ The entry's definition table as specified in the `def` argument of
 `doc.new_entry`. The table fields are the same.
 
 ### `doc.entry_exists(category_id, entry_id)`
-Checks if the specified entry exists and returns `true` or `false`.
+Checks whether the specified entry exists and returns `true` or `false`.
 
 #### Parameters
 * `category_id`: Category identifier of the category to check
@@ -286,7 +278,7 @@ Checks if the specified entry exists and returns `true` or `false`.
 Returns `true` if and only if:
 
 * The specified category exists
-* This category contains the specified entry
+* It contains the specified entry
 
 Otherwise, returns `false`.
 
@@ -304,7 +296,7 @@ the player.
 
 ### `doc.entry_revealed(playername, category_id, entry_id)`
 Tells whether the specified entry is marked as “revealed” to the player
-and thus visible and generally accessible.
+and thus visible and accessible to the player.
 
 #### Parameters
 * `playername`: Name of the player to check
@@ -316,21 +308,19 @@ and thus visible and generally accessible.
 
 ### `doc.mark_entry_as_viewed(playername, category_id, entry_id)`
 Marks a particular entry as “viewed” (or read) by a player. This will
-also automatically reveal the entry to the player permanently.
+also automatically reveal the entry to the player for the rest of
+the game.
 
 #### Parameters
 * `playername`: Name of the player for whom to mark an entry as “viewed”
 * `category_id`: Category identifier of the category of the entry to mark
 * `entry_id`: Entry identifier of the entry to mark
 
-#### Returns
-Always `nil`.
-
 ### `doc.mark_entry_as_revealed(playername, category_id, entry_id)`
 Marks a particular entry as “revealed” to a player. If the entry is
 declared as hidden, it will become visible in the list of entries for
 this player and will always be accessible with `doc.show_entry`. This
-change is permanent.
+change remains for the rest of the game.
 
 For entries which are not normally hidden, this function has no direct
 effect.
@@ -340,22 +330,18 @@ effect.
 * `category_id`: Category identifier of the category of the entry to reveal
 * `entry_id`: Entry identifier of the entry to reveal
 
-#### Returns
-Always `nil`.
-
-### `doc.mark_entry_as_revealed(playername)`
-Marks all entries as “revealed” to a player. This change is permanent.
+### `doc.mark_all_entries_as_revealed(playername)`
+Marks all entries as “revealed” to a player. This change remains for the
+rest of the game.
 
 #### Parameters
 * `playername`: Name of the player for whom to reveal the entries
 
-#### Returns
-Always `nil`.
-
 ### `doc.add_entry_alias(category_id, entry_id, alias)`
-Adds a single alias for an entry. When an entry has an alias, supplying the
+Adds a single alias for an entry. If an entry has an alias, supplying the
 alias to a function which demands an `entry_id` will work as if the original
-`entry_id` has been supplied. Aliases are true within one category only.
+`entry_id` has been supplied. The scope of an alias is the category in which
+it has been created.
 When using this function, you must make sure the category already exists.
 
 #### Parameters
@@ -364,9 +350,6 @@ When using this function, you must make sure the category already exists.
   for
 * `alias`: Alias (string) for `entry_id`
 
-#### Return value
-Always `nil`.
-
 ### `doc.add_entry_aliases(category_id, entry_id, aliases)`
 Adds an arbitrary amount of aliases for an entry at once. Apart from that, this
 function has the same effect as `doc.add_entry_alias`.
@@ -378,12 +361,12 @@ When using this function, you must make sure the category already exists.
   for
 * `aliases`: Table/list of aliases (strings) for `entry_id`
 
-#### Return value
-Always `nil`.
-
 ### `doc.get_category_count()`
 Returns the number of registered categories.
 
+#### Return value
+Number of registered categories.
+
 ### `doc.get_entry_count(category_id)`
 Returns the number of entries in a category.
 
@@ -430,12 +413,27 @@ Returns how many entries are hidden from the player in this category.
 Amount of entries hidden from the player. If the player does not exist,
 this function returns `nil`.
 
+### `doc.get_selection(playername)`
+Returns the currently or last viewed entry and/or category of a player.
+
+#### Parameter
+* `playername`: Name of the player to query
+
+#### Return value
+It returns up to 2 values. The first one is the category ID, the second one
+is the entry ID of the entry/category which the player is currently viewing
+or is the last entry the player viewed in this session. If the player only
+viewed a category so far, the second value is `nil`. If the player has not
+viewed a category as well, both returned values are `nil`.
+
+
 ### `doc.widgets.text(data, x, y, width, height)`
 This is a convenience function for creating a special formspec widget. It creates
 a widget in which you can insert scrollable multi-line text.
 
-This function is provided because Minetest lacks native support for such a widget;
-this function may be deprecated if it isn't needed anymore.
+As of Minetest 0.4.14, this function is only provided because Minetest lacks
+native support for such a widget. When Minetest supports such a widget natively,
+this function may become just a simple wrapper.
 
 #### Parameters
 * `data`: Text to be written inside the widget
@@ -454,30 +452,18 @@ Two values are returned, in this order:
 * String: Formspec element ID of the created widget
 
 #### Note
-When you use this function to build a formspec string, do not use identifiers
+If you use this function to build a formspec string, do not use identifiers
 beginning with `doc_widget_text` to avoid naming collisions, as this function
 makes use of such identifiers internally.
 
 
-### `doc.get_selection(playername)`
-Returns the currently or last viewed entry and/or category of a player.
-
-#### Parameter
-* `playername`: Name of the player to query
-
-#### Return value
-It returns up to 2 values. The first one is the category ID, the second one
-is the entry ID of the entry/category which the player is currently viewing
-or is the last entry the player viewed in this session. If the player only
-viewed a category so far, the second value is `nil`. If the player has not
-viewed a category as well, both returned values are `nil`.
-
 
 ## Extending this mod (naming conventions)
 If you want to extend this mod with your own functionality, it is recommended
 that you put all API functions into `doc.sub.<name>`.
-As a naming convention, if your mod depends on `doc`, your mod name should also start
-with “`doc_`”, like `doc_items`, `doc_minetest_game`, `doc_identifier`.
+As a naming convention, if you mod *primarily* depends on `doc`, it is recommended
+to use a short mod name which starts with “`doc_`”, like `doc_items`,
+`doc_minetest_game`, or `doc_identifier`.
 
 One mod which uses this convention is `doc_items` which uses the `doc.sub.items`
 table.