Chat and Commands: Improve readability and grammar

en/chapters/chat.md

@@ -6,56 +6,59 @@ root: ../../
 
 ## Introduction
 
-In this chapter we will learn how to interact with player chat, including
+Mods can interact with player chat, including
 sending messages, intercepting messages and registering chat commands.
 
-* Send a message to all players.
+* [Sending messages to all players](#sending-messages-to-all-players)
-* Send a message to a certain player.
+* [Sending messages to specific players](sending-messages-to-specific-players)
-* Chat commands.
+* [Chat commands](#chat-commands)
-* Complex subcommands.
+* [Complex subcommands](#complex-subcommands)
-* Intercepting messages.
+* [Intercepting messages](#intercepting-messages)
 
-## Send a message to all players
+## Sending messages to all players
 
-It's as simple as calling the chat_send_all function, as so:
+To send a message to every player in the game, call the chat_send_all function.
 
 {% highlight lua %}
 minetest.chat_send_all("This is a chat message to all players")
 {% endhighlight %}
 
-Here is an example of how it would appear ingame (there are other messages
+Here is an example of how this appears in-game:
-around it).
 
     <player1> Look at this entrance
     This is a chat message to all players
     <player2> What about it?
 
-## Send a message to a certain player
+The message appears on a separate line to distinguish it from in-game player chat.
 
-It's as simple as calling the chat_send_player function, as so:
+## Sending messages to specific players
+
+To send a message to a specific player, call the chat_send_player function:
 
 {% highlight lua %}
 minetest.chat_send_player("player1", "This is a chat message for player1")
 {% endhighlight %}
 
-Only player1 can see this message, and it's displayed the same as above.
+This message displays in the same manner as messages to all players, but is
+only visible to the named player, in this case player1.
 
 ### Older mods
 
-Occasionally you'll see mods with code like this:
+Occasionally you'll see mods where the chat_send_player function includes a
+boolean:
 
 {% highlight lua %}
 minetest.chat_send_player("player1", "This is a server message", true)
 minetest.chat_send_player("player1", "This is a server message", false)
 {% endhighlight %}
 
-The boolean at is no longer used, and has no affect
+The boolean is no longer used, and has no affect
 <sup>[[commit]](https://github.com/minetest/minetest/commit/9a3b7715e2c2390a3a549d4e105ed8c18defb228)</sup>.
 
 
 ## Chat commands
 
-In order to register a chat command, such as /foo, use register_chatcommand:
+To register a chat command, for example /foo, use register_chatcommand:
 
 {% highlight lua %}
 minetest.register_chatcommand("foo", {
@@ -68,9 +71,9 @@ minetest.register_chatcommand("foo", {
 })
 {% endhighlight %}
 
-Calling /foo bar will result in `You said bar!` in the chat console.
+Calling /foo bar will display `You said bar!` in the chat console.
 
-Let's do a break down:
+You can restrict which players are able to run commands:
 
 {% highlight lua %}
 privs = {
@@ -78,23 +81,26 @@ privs = {
 },
 {% endhighlight %}
 
-This makes it so that only players with the `interact` [privilege](privileges.html) can run the
+This means only players with the `interact` [privilege](privileges.html) can run the
-command. Other players will see an error message informing them which
+command. Other players will see an error message informing them of which
-privilege they're missing.
+privilege they're missing. If the player has the necessary privileges, the command
+will run and the message will be sent:
 
 {% highlight lua %}
 return true, "You said " .. param .. "!"
 {% endhighlight %}
 
-This returns two values, firstly a boolean which says that the command succeeded
+This returns two values, a boolean which shows the command succeeded
-and secondly the chat message to send to the player.
+and the chat message to send to the player.
 
-The reason that a player name rather than a player object is passed is because
+A player name, instead of a player object, is passed because
-**the player might not actually be online, but may be running commands from IRC**.
+**the player might not actually be in-game, but may be running commands from IRC**.
-So don't assume that `minetest.get_player_by_name` will work in a chat command call back,
+Due to this, you should not assume `minetest.get_player_by_name`, or any other
-or any other function that requires an ingame player. `minetest.show_formspec` will also
+function that requires an in-game player, will work in a chat command call back.
-not work for IRC players, so you should provide a text only version. For example, the
+
-email mod allows both `/inbox` to show the formspec, and `/inbox text` to send to chat.
+`minetest.show_formspec` also won't work when a command is run from IRC, so you
+should provide a text only version. For example, the email mod allows both `/inbox`
+to show a formspec, and `/inbox text` to send information to chat.
 
 ## Complex subcommands
 
@@ -105,14 +111,14 @@ It is often required to make complex chat commands, such as:
 * /team leave <teamname>
 * /team list
 
-Traditionally mods implemented this using Lua patterns. However, a much easier
+Many mods implement this using Lua patterns; however, a much easier
-way is to use a mod library that I wrote to do this for you.
+approach is to use a mod library. See rubenwardy's
-See [Complex Chat Commands](chat_complex.html).
+[Complex Chat Commands](chat_complex.html).
 
 
 ## Intercepting messages
 
-You can use register_on_chat_message, like so:
+To intercept a message, use register_on_chat_message:
 
 {% highlight lua %}
 minetest.register_on_chat_message(function(name, message)
@@ -121,8 +127,8 @@ minetest.register_on_chat_message(function(name, message)
 end)
 {% endhighlight %}
 
-By returning false, we're allowing the chat message to be sent by the default
+By returning false, you allow the chat message to be sent by the default
-handler. You can actually miss out the line `return false`, and it would still
+handler. You can actually remove the line `return false`, and it would still
 work the same.
 
 **WARNING: CHAT COMMANDS ARE ALSO INTERCEPTED.** If you only want to catch