From b5fcac7ed53d14bf3bbf8e6ef9795ef4de0ed6db Mon Sep 17 00:00:00 2001
From: rubenwardy <rw@rubenwardy.com>
Date: Sun, 31 Jul 2022 17:39:25 +0100
Subject: [PATCH] Lua Scripting: Update chapter

---
 _en/basics/lua.md | 64 +++++++++++++++++++++++++----------------------
 1 file changed, 34 insertions(+), 30 deletions(-)

diff --git a/_en/basics/lua.md b/_en/basics/lua.md
index 52bc164..71f17c4 100644
--- a/_en/basics/lua.md
+++ b/_en/basics/lua.md
@@ -9,8 +9,8 @@ redirect_from: /en/chapters/lua.html
 
 ## Introduction  <!-- omit in toc -->
 
-In this chapter we'll talk about scripting in Lua, the tools required
-to assist with this, and some techniques which you may find useful.
+In this chapter, you'll learn about scripting in Lua, the tools required
+to help with this, and some techniques that you may find useful.
 
 - [Programming](#programming)
   - [Coding in Lua](#coding-in-lua)
@@ -24,23 +24,21 @@ to assist with this, and some techniques which you may find useful.
 
 Programming is the action of taking a problem, such as sorting a list
 of items, and 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](http://www.codecademy.com/) is one of the best resources for
   learning to write code. It provides an interactive tutorial experience.
 * [Scratch](https://scratch.mit.edu) is a good resource for starting from
-  absolute basics, and learning the problem-solving techniques required to program.\\
-  Scratch is *designed to teach children* how to program and isn't a serious
-  programming language.
+  absolute basics, and learning the problem-solving techniques required to program.
+  It's great for children and teenagers.
 * [Programming with Mosh](https://www.youtube.com/user/programmingwithmosh) is
   a good YouTube series to learn programming.
 
 ### Coding in Lua
 
 It's also beyond the scope of this book to teach Lua coding.
-The [Programming in Lua](https://www.lua.org/pil/contents.html) book is an
+The [Programming in Lua (PiL)](https://www.lua.org/pil/contents.html) book is an
 excellent introduction to Lua programming.
 
 
@@ -74,10 +72,10 @@ Functions which come with Lua by default, such as `table.insert`, are also highl
 
 Commonly used editors which are well-suited for Lua include:
 
-* [VSCode](https://code.visualstudio.com/) -
+* [VSCode](https://code.visualstudio.com/):
     open source (as Code-OSS or VSCodium), popular, and has
-    [plugins for Minetest modding](https://marketplace.visualstudio.com/items?itemName=GreenXenith.minetest-tools).
-* [Notepad++](http://notepad-plus-plus.org/) - Windows-only
+    [plugins for Minetest](https://marketplace.visualstudio.com/items?itemName=GreenXenith.minetest-tools).
+* [Notepad++](http://notepad-plus-plus.org/): simple, Windows-only
 
 Other suitable editors are also available.
 
@@ -85,8 +83,25 @@ Other suitable editors are also available.
 ## Local and Global Scope
 
 Whether a variable is local or global determines where it can be written to or
-read from. A local variable is only accessible from where it is defined. Here
-are some examples:
+read from. Global variables can be accessed from anywhere in the script file,
+and from any other mod:
+
+```lua
+function one()
+    foo = "bar"
+end
+
+function two()
+    print(dump(foo))  -- Output: "bar"
+end
+
+one()
+two()
+```
+
+In constrast, a local variable is only accessible from where it is defined.
+Lua defaults to variables being global, so you need to explicitly use the
+`local` keyword:
 
 ```lua
 -- Accessible from within this script file
@@ -103,22 +118,6 @@ function myfunc()
 end
 ```
 
-In contrast, global variables can be accessed from anywhere in the script file, and
-from any other mod.
-
-```lua
-function one()
-    foo = "bar"
-end
-
-function two()
-    print(dump(foo))  -- Output: "bar"
-end
-
-one()
-two()
-```
-
 
 ### Locals should be used as much as possible
 
@@ -170,6 +169,9 @@ end
 mymod.foo("foobar")
 ```
 
+`function mymod.foo()` is equivalent to `mymod.foo = function()`, it's just a
+nicer way to write it.
+
 ## Including other Lua Scripts
 
 The recommended way to include other Lua scripts in a mod is to use *dofile*.
@@ -182,11 +184,13 @@ A script can return a value, which is useful for sharing private locals:
 
 ```lua
 -- script.lua
-return "Hello world!"
+local module = {}
+module.message = "Hello World!"
+return module
 
 -- init.lua
 local ret = dofile(minetest.get_modpath("modname") .. "/script.lua")
-print(ret) -- Hello world!
+print(ret.message) -- Hello world!
 ```
 
 [Later chapters](../quality/clean_arch.html) will discuss how best to split up