Improve chapters in basics section

_en/basics/getting_started.md

@@ -1,10 +1,12 @@
 ---
-title: Folder Structure
+title: Getting Started
 layout: default
 root: ../..
 idx: 1.1
 description: Learn how to make a mod folder, including init.lua, depends.txt and more.
-redirect_from: /en/chapters/folders.html
+redirect_from:
+- /en/chapters/folders.html
+- /en/basics/folders.html
 ---
 
 ## Introduction
@@ -29,32 +31,51 @@ A "mod name" is used to refer to a mod. Each mod should have a unique mod name.
 Mod names can include letters, numbers, and underscores. A good mod name should
 describe what the mod does, and the folder which contains the components of a mod
 needs to be given the same name as the mod name.
+To find out if a mod name is available, try searching for it on
+[content.minetest.net](https://content.minetest.net).
 
-### Mod Folder Structure
     Mod name (eg: "mymod")
     -    init.lua - the main scripting code file, which runs when the game loads.
-    -    (optional) depends.txt - a list of mods that need to be loaded before this mod.
+    -    mod.conf - a list of mods that need to be loaded before this mod.
     -    (optional) textures/ - images used by the mod, commonly in the format modname_itemname.png.
     -    (optional) sounds/ - sounds used by the mod.
     -    (optional) models/ - 3d models used by the mod.
     ...and any other Lua files to be included.
 
-Only the init.lua file is required in a mod for it to run on game load; however,
+Only the init.lua file is actually required in a mod for it to run on game load;
-the other items are needed by some mods to perform their functionality.
+however, mod.conf is recommended and other components may be needed
+to perform a mod's functionality.
 
 ## Dependencies
 
-The depends text file allows you to specify which mods this mod requires to run and what
+A dependency is another mod which the mod requires to be loaded before itself.
-needs to be loaded before this mod.
+The mod may require the other's mods code, items, or other resources to be available.
+There are two types of dependencies: hard and optional dependencies.
+Both require the mod to be loaded first, but a hard dependency will cause the mod to
+fail to load if the required mod isn't available.
+An optional dependency is useful if you want to optionally support another mod if the
+user wishes to use it.
 
-**depends.txt**
+### mod.conf
+
+Dependencies should be listed in mod.conf.
+The file is used for mod metadata such as the mod's name, description, and other information.
+
+    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, you'll need to also provide
+a depends.txt file:
 
     modone
     modtwo
     modthree?
 
-As you can see, each modname is on its own line.
+Each modname is on its own line.
-
 Mod names with a question mark following them are optional dependencies.
 If an optional dependency is installed, it is loaded before the mod;
 however, if the dependency is not installed, the mod still loads.
@@ -67,7 +88,6 @@ 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.
 
-### Mod Pack Folder Structure
     modpackfolder/
     -    modone/
     -    modtwo/
@@ -83,8 +103,9 @@ Are you confused? Don't worry, here is an example which puts all of this togethe
     mymod/
     -    textures/
     -    -    mymod_node.png
-    -    init.lua
     -    depends.txt
+    -    init.lua
+    -    mod.conf
 
 
 ### depends.txt
@@ -108,7 +129,20 @@ minetest.register_node("mymod:node", {
 })
 {% endhighlight %}
 
-This mod has the name "mymod". It has two text files: init.lua and depends.txt.\\
+### mod.conf
-The script prints a message and then registers a node – which will be explained in the next chapter.\\
+    name = mymod
-The depends text file adds a dependency on the default mod which is in minetest_game.\\
+    descriptions = Adds a node
+    depends = default
+
+This mod has the name "mymod". It has three text files: init.lua, 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
+[default mod](https://content.minetest.net/metapackages/default/) which is
+usually found in Minetest Game.\\
 There is also a texture in textures/ for the node.
+
+Please note that a *game* is not a modpack.
+Games have their own organisational structure which will be explained in the
+Games chapter.

_en/basics/lua.md

@@ -1,5 +1,5 @@
 ---
-title: Lua Scripts
+title: Lua Scripting
 layout: default
 root: ../..
 idx: 1.2
@@ -12,19 +12,22 @@ redirect_from: /en/chapters/lua.html
 In this chapter we will talk about scripting in Lua, the tools required,
 and go over some techniques which you will probably find useful.
 
-* Tools
+* [Code Editors](#code-editors)
-    * Recommended Editors
+    * [Integrated Programming Environments](#integrated-programming-environments)
-    * Integrated Programming Environments
+* [Coding in Lua](#coding-in-lua)
-* Coding in Lua
+    * [Program Flow](#program-flow)
-    * Selection
+    * [Variable Types](#variable-types)
-* Programming
+    * [Arithmetic Operators](#arithmetic-operators)
-* Local and Global
+    * [Selection](#selection)
-* Including other Lua Scripts
+    * [Logical Operators](#logical-operators)
+* [Programming](#programming)
+* [Local and Global Scope](#local-and-global-scope)
+* [Including other Lua Scripts](#including-other-lua-scripts)
 
-## Tools
+## Code Editors
 
-A text editor with code highlighting is sufficient for writing scripts in Lua.
+A code editor with code highlighting is sufficient for writing scripts in Lua.
-Code highlighting gives different colors to different words and characters
+Code highlighting gives different colours to different words and characters
 depending on what they mean. This allows you to spot mistakes.
 
 {% highlight lua %}
@@ -46,13 +49,12 @@ end
 For example, keywords in the above snippet are highlighted such as if, then, end, return.
 table.insert is a function which comes with Lua by default.
 
-### Recommended Editors
+Here is a list of common editors well suited for Lua.
-
 Other editors are available, of course.
 
-* Windows: [Notepad++](http://notepad-plus-plus.org/), [Atom](http://atom.io/)
+* Windows: [Notepad++](http://notepad-plus-plus.org/), [Atom](http://atom.io/), [VS Code](https://code.visualstudio.com/)
-* Linux: Kate, Gedit, [Atom](http://atom.io/)
+* Linux: Kate, Gedit, [Atom](http://atom.io/), [VS Code](https://code.visualstudio.com/)
-* OSX: [Atom](http://atom.io/)
+* OSX: [Atom](http://atom.io/), [VS Code](https://code.visualstudio.com/)
 
 ### Integrated Programming Environments
 
@@ -71,14 +73,16 @@ One such IDE is Eclipse with the Koneki Lua plugin:
 
 ## Coding in Lua
 
+### Program Flow
+
 Programs are a series of commands that run one after another.
 We call these commands "statements."
-
+Program flow is how these statements are executed.
-Program flow is important, it allows you to direct or skip over
+Different types of flow allow you to skip or jump over sets of commands.
-statements. There are three main types of flow:
+There are three main types of flow:
 
 * Sequence: Just run one statement after another, no skipping.
-* Selected: Skip over statements depending on conditions.
+* Selection: Skip over sequences depending on conditions.
 * Iteration: Repeating, looping. Keep running the same
   statements until a condition is met.
 
@@ -92,30 +96,37 @@ a = a + 10
 print("Sum is "..result)
 {% endhighlight %}
 
-Whoa, what happened there? a, b, and result are **variables**. They're like what
+Whoa, what happened there?
-you get in mathematics, A = w * h. The equals signs are **assignments**, so
-"result" is set to a + b. Variable names can be longer than one character
-unlike in mathematics, as seen with the "result" variable. Lua is **case sensitive**.
-A is a different variable than a.
 
-The word "local" before they are first used means that they have local scope,
+a, b, and result are *variables*. Local variables are declared
-I'll discuss that shortly.
+by using the local keyword, and then given an initial value.
+Local will be discussed in a bit, as it's part of a very important concept called
+*scope*.
+
+The `=` means *assignment*, so `result = a + b` means set "result" to a + b.
+Variable names can be longer than one character unlike in mathematics, as seen with the "result" variable.
+It's also worth noting that Lua is *case-sensitive*; A is a different variable than a.
 
 ### Variable Types
 
+A variable will be only one of the following types and can change type after an
+assignment.
+It's good practice to make sure a variable is only ever nil or a single non-nil type.
+
 | Type     | Description                                        | Example                                   |
 |----------|----------------------------------------------------|-------------------------------------------|
-| Integer  | Whole number                                       | local A = 4                               |
+| Nil      | Not initialised. The variable is empty, it has no value | `local A`, `D = nil` |
-| Float    | Decimal                                            | local B = 3.2, local C = 5 / 2            |
-| String   | A piece of text                                    | local D = "one two three"                 |
-| Boolean  | True or False                                      | local is_true = false, local E = (1 == 1) |
-| Table    | Lists                                              | Explained below                           |
-| Function | Can run. May require inputs and may return a value | local result = func(1, 2, 3)              |
 
-Not an exhaustive list. Doesn't contain every possible type.
+| Number   | A whole or decimal number.                         | `local A = 4` |
+| String   | A piece of text                                    | `local D = "one two three" |
+| Boolean  | True or False                                      | `local is_true = false`, `local E = (1 == 1)`` |
+| Table    | Lists                                              | Explained below                           |
+| Function | Can run. May require inputs and may return a value | `local result = func(1, 2, 3)` |
 
 ### Arithmetic Operators
 
+Not an exhaustive list. Doesn't contain every possible operator.
+
 | Symbol | Purpose        | Example                   |
 |--------|----------------|---------------------------|
 | A + B  | Addition       | 2 + 2 = 4                 |
@@ -125,17 +136,12 @@ Not an exhaustive list. Doesn't contain every possible type.
 | A ^ B  | Powers         | 2 ^ 2 = 2<sup>2</sup> = 4 |
 | A .. B | Join strings   | "foo" .. "bar" = "foobar" |
 
-A string in programming terms is a piece of text.
-
-Not an exhaustive list. Doesn't contain every possible operator.
-
 ### Selection
 
 The most basic selection is the if statement. It looks like this:
 
 {% highlight lua %}
 local random_number = math.random(1, 100) -- Between 1 and 100.
-
 if random_number > 50 then
     print("Woohoo!")
 else
@@ -177,7 +183,6 @@ and return a value which can be stored.
 {% highlight lua %}
 local A = 5
 local is_equal = (A == 5)
-
 if is_equal then
     print("Is equal!")
 end
@@ -191,16 +196,14 @@ of items, and then turning it into steps that a computer can understand.
 Teaching you the logical process of programming is beyond the scope of this book;
 however, the following websites are quite useful in developing this:
 
-### Codecademy
+* [Codecademy](http://www.codecademy.com/) is one of the best resources for
-[Codecademy](http://www.codecademy.com/) is one of the best resources for learning to 'code',
+  learning to 'code', it provides an interactive tutorial experience.
-it provides an interactive tutorial experience.
+* [Scratch](https://scratch.mit.edu) is a good resource when starting from
+  absolute basics, learning the problem solving techniques required to program.\\
+  Scratch is **designed to teach children** how to program, it isn't a serious
+  programming language.
 
-### Scratch
+## Local and Global Scope
-[Scratch](https://scratch.mit.edu) is a good resource when starting from absolute basics,
-learning the problem solving techniques required to program.\\
-Scratch is **designed to teach children** how to program, it isn't a serious programming language.
-
-## Local and Global
 
 Whether a variable is local or global determines where it can be written to or read to.
 A local variable is only accessible from where it is defined. Here are some examples:
@@ -257,7 +260,7 @@ dump() is a function that can turn any variable into a string so the programmer
 see what it is. The foo variable will be printed as "bar", including the quotes
 which show it is a string.
 
-This is sloppy coding, and Minetest will in fact warn you about this:
+This is sloppy coding, and Minetest will in fact warn about this:
 
     [WARNING] Assigment to undeclared global 'foo' inside function at init.lua:2
 
@@ -276,12 +279,12 @@ one()
 two()
 {% endhighlight %}
 
-Nil means **not initialised**. The variable hasn't been assigned a value yet,
+Remember that nil means **not initialised**.
-doesn't exist, or has been uninitialised. (ie: set to nil)
+The variable hasn't been assigned a value yet,
+doesn't exist, or has been uninitialised (ie: set to nil).
 
-The same goes for functions. Functions are variables of a special type.
+The same goes for functions. Functions are variables of a special type, and
-You should make functions as local as much as possible,
+should be made local, as other mods could have functions of the same name.
-as other mods could have functions of the same name.
 
 {% highlight lua %}
 local function foo(bar)
@@ -289,8 +292,7 @@ local function foo(bar)
 end
 {% endhighlight %}
 
-If you want your functions to be accessible from other scripts or mods, it is recommended that
+API tables should be used to allow other mods to call the functions, like so:
-you add them all into a table with the same name as the mod:
 
 {% highlight lua %}
 mymod = {}
@@ -305,15 +307,24 @@ mymod.foo("foobar")
 
 ## Including other Lua Scripts
 
-You can include Lua scripts from your mod or another mod like this:
+The recommended way to include other Lua scripts in a mod is to use *dofile*.
 
 {% highlight lua %}
 dofile(minetest.get_modpath("modname") .. "/script.lua")
 {% endhighlight %}
 
 "local" variables declared outside of any functions in a script file will be local to that script.
-You won't be able to access them from any other scripts.
+A script can return a value, which is useful for sharing private locals:
 
-As for how you divide code up into files, it doesn't matter that much.
+{% highlight lua %}
-The most important thing is that your code is easy to read and edit.
+-- script.lua
-You won't need to use it for smaller projects.
+return "Hello world!"
+
+-- init.lua
+local ret = dofile(minetest.get_modpath("modname") .. "/script.lua")
+print(ret) -- Hello world!
+{% endhighlight %}
+
+Later chapters will discuss how to split up the code of a mod in a lot of detail.
+However, the simplistic approach for now is to have different files for different
+types of things - nodes.lua, crafts.lua, craftitems.lua, etc.