Improve various chapters

_en/basics/getting_started.md

@@ -17,13 +17,11 @@ creating mods.
 - [What are Games and Mods?](#what-are-games-and-mods)
 - [Where are mods stored?](#where-are-mods-stored)
 - [Mod Directory](#mod-directory)
-- [Dependencies](#dependencies)
+- [mod.conf](#modconf)
-  - [mod.conf](#modconf)
+	- [Dependencies](#dependencies)
-  - [depends.txt](#dependstxt)
 - [Mod Packs](#mod-packs)
 - [Example](#example)
 	- [Mod Folder](#mod-folder)
-  - [depends.txt](#dependstxt-1)
 	- [init.lua](#initlua)
 	- [mod.conf](#modconf-1)
 
@@ -119,8 +117,18 @@ Only the init.lua file is required in a mod for it to run on game load;
 however, mod.conf is recommended and other components may be needed
 depending on the mod's functionality.
 
+## mod.conf
 
-## Dependencies
+This file is used for mod metadata including the mod's name, description, and other
+information.
+
+For example:
+
+    name = mymod
+    description = Adds foo, bar, and bo.
+    depends = modone, modtwo
+
+### Dependencies
 
 A dependency occurs when a mod requires another mod to be loaded before itself.
 One mod may require another mod's code, items, or other resources to be available
@@ -134,34 +142,14 @@ dependency might lead to fewer features being enabled.
 An optional dependency is useful if you want to optionally support another mod; it can
 enable extra content if the user wishes to use both the mods at the same time.
 
-Dependencies should be listed in mod.conf.
+Dependencies are specified in a comma-separated list in mod.conf.
 
-### mod.conf
-
-This file is used for mod metadata including the mod's name, description, and other
-information. For example:
-
-    name = mymod
-    description = Adds foo, bar, and bo.
     depends = modone, modtwo
     optional_depends = modthree
 
-### depends.txt
-
-For compatibility with 0.4.x versions of Minetest, instead of only specifying
-dependencies in mod.conf, you need to provide a depends.txt file in which
-you list all dependencies:
-
-    modone
-    modtwo
-    modthree?
-
-Each mod name is on its own line, and mod names with a question mark
-following them are optional dependencies.
-
 ## Mod Packs
 
-Mods can be grouped into mod packs which allow multiple mods to be packaged
+Mods can be grouped into mod packs, which allow multiple mods to be packaged
 and moved together. They are useful if you want to supply multiple mods to
 a player, but don't want to make them download each one individually.
 
@@ -184,13 +172,9 @@ Here is an example which puts all of this together:
     mymod
     ├── textures
     │   └── mymod_node.png files
-    ├── depends.txt
     ├── init.lua
     └── mod.conf
 
-### depends.txt
-    default
-
 ### init.lua
 ```lua
 print("This file will be run at load time!")
@@ -207,8 +191,7 @@ minetest.register_node("mymod:node", {
     descriptions = Adds a node
     depends = default
 
-This mod has the name "mymod". It has three text files: init.lua, mod.conf,
+This mod has the name "mymod". It has two text files: init.lua and mod.conf.\\
-and depends.txt.\\
 The script prints a message and then registers a node –
 which will be explained in the next chapter.\\
 There's a single dependency, the

_en/games/games.md

@@ -57,7 +57,7 @@ convenient, as it'll make porting mods to another game much easier.
 
 The best way to keep compatibility with another game is to keep API compatibility
 with any mods which have the same name.
-That is, if a mod uses the same name as another mod, even if third party,
+That is, if a mod uses the same name as another mod, even if third-party,
 it should have a compatible API.
 For example, if a game includes a mod called `doors`, then it should have the
 same API as `doors` in Minetest Game.

_en/map/objects.md

@@ -103,28 +103,6 @@ An Entity has a definition table that resembles an item definition table.
 This table can contain callback methods, initial object properties, and custom
 members.
 
-However, entities differ in one very important way from items. When an entity is
-emerged (ie: loaded or created), a new table is created for that entity that
-*inherits* from the definition table using metatables.
-This new table is commonly referred to as a Lua Entity table.
-
-Metatables are an important Lua feature that you will need
-to be aware of, as it is an essential part of the Lua language.
-
-In layman's terms, a metatable allows you to control how the table behaves when
-using certain Lua syntax. The most common use of metatables is the ability to use
-another table as a prototype, defaulting to the other table's properties and methods when
-they do not exist in the current table.
-
-Say you want to access member X on table A. If table A has that member, then
-it will be returned as normal. However, if the table doesn't have that member but
-it does have a metatable could table B, then table B will be checked to see if it
-has that member.
-
-<!--table A is a metatable of table B, then table
-B will have all the properties and methods of table A if the derived table doesn't
-have any itself.-->
-
 ```lua
 local MyEntity = {
     initial_properties = {
@@ -147,9 +125,22 @@ function MyEntity:set_message(msg)
 end
 ```
 
-When an entity has emerged, a table is created for it by copying everything from
+Entity definitions differ in one very important way from Item definitions.
-its type table.
+When an entity is emerged (ie: loaded or created), a new table is created for
-This table can be used to store variables for that particular entity.
+that entity that *inherits* from the definition table.
+
+<!--
+This inheritance is done using a Metatables are an important Lua feature that you will need
+to be aware of, as it is an essential part of the Lua language.
+In layman's terms, a metatable allows you to control how the table behaves when
+using certain Lua syntax. The most common use of metatables is the ability to use
+another table as a prototype, defaulting to the other table's properties and methods when
+they do not exist in the current table.
+Say you want to access `a.x`. If the table `a` has that member, then it will be
+returned as normal. However, if the table doesn't have that member and the
+metatable lists a table `b` as a prototype, then table `b` will be checked to see
+if it has that member.
+-->
 
 Both an ObjectRef and an entity table provide ways to get the counterpart:
 

_en/map/storage.md

@@ -111,7 +111,7 @@ Minetest offers two formats for doing this: Lua and JSON.
 
 The Lua method tends to be a lot faster and matches the format Lua
 uses for tables, while JSON is a more standard format, is better
-structured, and is well suited when you need to exchange information
+structured, and is well suited for when you need to exchange information
 with another program.
 
 ```lua
@@ -123,8 +123,8 @@ data = minetest.deserialize(minetest:get_string("foo"))
 
 ### Private Metadata
 
-Entries in Node Metadata can be marked as private, and not sent to the client.
+By default, all node metadata is sent to the client.
-Entries not marked as private will be sent to the client.
+You can mark keys as private to prevent this.
 
 ```lua
 meta:set_string("secret", "asd34dn")

_en/players/formspecs.md

@@ -56,6 +56,8 @@ called real coordinates which aims to rectify this by introducing a consistent
 coordinate system. The use of real coordinates is highly recommended, and so
 this chapter will use them exclusively.
 
+Using a formspec_version of 2 or above will enable real coordinates.
+
 ## Anatomy of a Formspec
 
 ### Elements
@@ -93,7 +95,7 @@ The size is in formspec slots - a unit of measurement which is roughly
 around 64 pixels, but varies based on the screen density and scaling
 settings of the client. Here's a formspec which is `2,2` in size:
 
-    formspec_version[3]
+    formspec_version[4]
     size[2,2]
 
 Notice how we explicitly defined the formspec language version.
@@ -106,9 +108,8 @@ the center (`0.5,0.5`). The anchor sets where on the formspec the position is,
 allowing you to line the formspec up with the edge of the screen. The formspec
 can be placed to the left of the screen like so:
 
-    formspec_version[3]
+    formspec_version[4]
     size[2,2]
-    real_coordinates[true]
     position[0,0.5]
     anchor[0,0.5]
 
@@ -143,7 +144,7 @@ function guessing.get_formspec(name)
     local text = "I'm thinking of a number... Make a guess!"
 
     local formspec = {
-        "formspec_version[3]",
+        "formspec_version[4]",
         "size[6,3.476]",
         "label[0.375,0.5;", minetest.formspec_escape(text), "]",
         "field[0.375,1.25;5.25,0.8;number;Number;]",
@@ -334,7 +335,7 @@ minetest.register_node("mymod:rightclick", {
 
         local meta = minetest.get_meta(pos)
         meta:set_string("formspec",
-                "formspec_version[3]" ..
+                "formspec_version[4]" ..
                 "size[5,5]" ..
                 "label[1,1;This is shown on right click]" ..
                 "field[1,2;2,1;x;x;]")

_en/quality/common_mistakes.md

@@ -10,54 +10,27 @@ redirect_from: /en/chapters/common_mistakes.html
 
 This chapter details common mistakes, and how to avoid them.
 
-- [Never Store ObjectRefs (ie: players or entities)](#never-store-objectrefs-ie-players-or-entities)
+- [Be Careful When Storing ObjectRefs (ie: players or entities)](#be-careful-when-storing-objectrefs-ie-players-or-entities)
 - [Don't Trust Formspec Submissions](#dont-trust-formspec-submissions)
 - [Set ItemStacks After Changing Them](#set-itemstacks-after-changing-them)
 
-## Never Store ObjectRefs (ie: players or entities)
+## Be Careful When Storing ObjectRefs (ie: players or entities)
 
-If the object an ObjectRef represents is deleted - for example, if the player goes
+An ObjectRef is invalidated when the player or entity it represents leaves
-offline or the entity is unloaded - then calling methods on that object
+the game. This may happen when the player goes offline, or the entity is unloaded
-will result in a crash.
+or removed.
 
-For example, don't do this:
+The methods of ObjectRefs will always return nil when invalid, since Minetest 5.2.
+Any call will essentially be ignored.
+
+You should avoid storing ObjectRefs where possible. If you do to store an
+ObjectRef, you should make you check it before use, like so:
 
 ```lua
-minetest.register_on_joinplayer(function(player)
+-- This only works in Minetest 5.2+
-    local function func()
+if obj:get_pos() then
-        local pos = player:get_pos() -- BAD!
+	-- is valid!
-        -- `player` is stored then accessed later.
+end
-        -- If the player leaves in that second, the server *will* crash.
-    end
-
-    minetest.after(1, func)
-
-    foobar[player:get_player_name()] = player
-    -- RISKY
-    -- It's not recommended to do this.
-    -- Use minetest.get_connected_players() and
-    -- minetest.get_player_by_name() instead.
-end)
-```
-
-Do this instead:
-
-```lua
-minetest.register_on_joinplayer(function(player)
-    local function func(name)
-        -- Attempt to get the ref again
-        local player = minetest.get_player_by_name(name)
-
-        -- Check that the player is still online
-        if player then
-            -- Yay! This is fine
-            local pos = player:get_pos()
-        end
-    end
-
-    -- Pass the name into the function
-    minetest.after(1, func, player:get_player_name())
-end)
 ```
 
 ## Don't Trust Formspec Submissions

_en/quality/releasing.md

@@ -11,21 +11,20 @@ redirect_from: /en/chapters/releasing.html
 Releasing, or publishing, a mod allows other people to make use of it. Once a mod has been
 released it might be used in singleplayer games or on servers, including public servers.
 
-- [License Choices](#license-choices)
+- [Choosing a License](#choosing-a-license)
 	- [LGPL and CC-BY-SA](#lgpl-and-cc-by-sa)
 	- [CC0](#cc0)
 	- [MIT](#mit)
 - [Packaging](#packaging)
 	- [README.txt](#readmetxt)
-  - [description.txt](#descriptiontxt)
+	- [mod.conf / game.conf](#modconf--gameconf)
 	- [screenshot.png](#screenshotpng)
 - [Uploading](#uploading)
 	- [Version Control Systems](#version-control-systems)
-  - [Forum Attachments](#forum-attachments)
+- [Releasing on ContentDB](#releasing-on-contentdb)
 - [Forum Topic](#forum-topic)
-  - [Subject](#subject)
 
-## License Choices
+## Choosing a License
 
 You need to specify a license for your mod. This is important because it tells other
 people the ways in which they are allowed to use your work. If your mod doesn't have
@@ -85,19 +84,19 @@ The README file should state:
 * Current version of the mod.
 * Optionally, the where to report problems or get help.
 
-### description.txt
+### mod.conf / game.conf
 
-This should explain what your mod does. Be concise without being vague.
+Make sure you add a description key to explain what your mod does. Be concise without being vague.
 It should be short because it will be displayed in the content installer which has
 limited space.
 
 Good example:
 
-    Adds soup, cakes, bakes and juices.
+    description = Adds soup, cakes, bakes and juices.
 
 Avoid this:
 
-    (BAD)  The food mod for Minetest.
+    description = The food mod for Minetest. (<-- BAD! It's vague)
 
 ### screenshot.png
 
@@ -114,54 +113,41 @@ approach that works best for you, as long as it meets these requirements, and an
 others which may be added by forum moderators:
 
 * **Stable**      - The hosting website should be unlikely to shut down without warning.
-* **Direct link** - You should be able to click a link on the forum and download the file
+* **Direct link** - You should be able to click a link and download the file
                    without having to view another page.
 * **Virus Free**  - Mods with malicious content will be removed from the forum.
 
+ContentDB allows you to upload zip files, and meets these criteria.
+
 ### Version Control Systems
 
-It is recommended that you use a version control system which:
+A Version Control System (VCS) is software that manages changes to software,
+often making it easier to distribute and receive contributed changes.
 
-* Allows other developers to easily submit changes.
+The majority of Minetest modders use Git and a website like GitHub to distribute
-* Allows the code to be previewed before downloading.
+their code.
-* Allows users to submit bug reports.
 
-The majority of Minetest modders use GitHub as a website to host their code,
+Using git can be difficult at first. If you need help with this please see:
-but alternatives are possible.
-
-Using a GitHub can be difficult at first. If you need help with this, for
-information on using GitHub, please see:
 
 * [Pro Git book](http://git-scm.com/book/en/v1/Getting-Started) - Free to read online.
 * [GitHub for Windows app](https://help.github.com/articles/getting-started-with-github-for-windows/) -
 Using a graphical interface on Windows to upload your code.
 
-### Forum Attachments
+## Releasing on ContentDB
 
-As an alternative to using a version management system, you can use forum attachments to share
+ContentDB is the official place to find and distribute mods and games. Users can
-your mods. This can be done when creating a mod's forum topic (covered below).
+find content using the website, or download and install using the integration
+built into the Minetest main menu.
 
-You need to zip the files for the mod into a single file. How to do this varies from
+Sign up to [ContentDB](https://content.minetest.net) and add your mod or game.
-operating system to operating system.
+Make sure to read the guidance given in the Help section.
-This is nearly always done using the right click menu after selecting all files.
-
-When making a forum topic, on the "Create a Topic" page (see below), go to the
-"Upload Attachment" tab at the bottom.
-Click "Browse" and select the zipped file. It is recommended that you
-enter the version of your mod in the comment field.
-
-<figure>
-    <img src="{{ page.root }}/static/releasing_attachments.png" alt="Upload Attachment">
-    <figcaption>
-        Upload Attachment tab.
-    </figcaption>
-</figure>
 
 ## Forum Topic
 
-You can now create a forum topic. You should create it in
+You can also create a forum topic to let users discuss your mod or game.
-the ["WIP Mods"](https://forum.minetest.net/viewforum.php?f=9) (Work In Progress)
+
-forum.\\
+Mod topics should be created in ["WIP Mods"](https://forum.minetest.net/viewforum.php?f=9) (Work In Progress)
+forum, and Game topics in the ["WIP Games"](https://forum.minetest.net/viewforum.php?f=50) forum.
 When you no longer consider your mod a work in progress, you can
 [request that it be moved](https://forum.minetest.net/viewtopic.php?f=11&t=10418)
 to "Mod Releases."
@@ -170,40 +156,6 @@ The forum topic should contain similar content to the README, but should
 be more promotional and also include a link to download the mod.
 It's a good idea to include screenshots of your mod in action, if possible.
 
-The Minetest forum uses bbcode for formatting. Here is an example for a
-mod named superspecial:
-
-
-    Adds magic, rainbows and other special things.
-
-    See download attached.
-
-    [b]Version:[/b] 1.1
-    [b]License:[/b] LGPL 2.1 or later
-
-    Dependencies: default mod (found in minetest_game)
-
-    Report bugs or request help on the forum topic.
-
-    [h]Installation[/h]
-
-    Unzip the archive, rename the folder to superspecial and
-    place it in minetest/mods/
-
-    (  GNU/Linux: If you use a system-wide installation place
-        it in ~/.minetest/mods/.  )
-
-    (  If you only want this to be used in a single world, place
-        the folder in worldmods/ in your world directory.  )
-
-    For further information or help see:
-    [url]https://wiki.minetest.net/Installing_Mods[/url]
-
-If you modify the above example for your mod topic, remember to
-change "superspecial" to the name of your mod.
-
-### Subject
-
 The subject of topic must be in one of these formats:
 
 * [Mod] Mod Title [modname]