editing pass for the structure of a full mod

the sample code itself needs some adjustment to exemplify best pratices.

docs/guides/modding-guide.rst

@@ -137,8 +137,7 @@ First, we load the module::
     local repeatUtil = require('repeat-util')
 
 Both ``repeat-util`` and ``eventful`` require keys for registered callbacks.
-You should use something unique, like your mod name, perhaps with a suffix if you
+You should use something unique, like your mod name::
-are registering multiple keys::
 
     local modId = "callback-example-mod"
 
@@ -169,6 +168,12 @@ projectile::
 Check out the `full list of supported events <eventful-api>` to see what else
 you can react to with ``eventful``.
 
+Now, you may have noticed that you won't be able to register multiple callbacks
+with a single key named after your mod. You can, of course, call all the functions
+you want from a single registed callback. Alternately, you can create multiple
+callbacks using different keys, using your mod ID as a key name prefix. If you do
+register multiple callbacks, though, there are no guarantees about the call order.
+
 Custom raw tokens
 -----------------
 
@@ -322,45 +327,46 @@ Now, we will add up the effect of all speed-increasing gear and apply it::
 The structure of a full mod
 ---------------------------
 
-Now, you may have noticed that you won't be able to run multiple functions on
+Create a folder for mod projects somewhere outside your Dwarf Fortress
-tick/as event callbacks with that ``modId`` key alone. To solve that we can
+installation directory (e.g. ``/path/to/mymods``) and use your mod IDs as the names
-just define all the functions we want and call them from a single function.
+for the mod folders within it. In the example below, we'll use a mod ID of
-Alternatively you can create multiple callbacks with your mod ID being a prefix,
+``example-mod``. I'm sure your mods will have more creative names! The ``example-mod``
-though this way there is no guarantee about the call order (if that is important
+mod will be developed in the ``/path/to/mymods/example-mod`` directory and has a basic
-to you). You will have to use your mod ID as a prefix if you register multiple
+structure that looks like this::
-``repeat-util`` callbacks, though.
+
-
+    raw/init.d/example-mod.lua
-Create a folder for mod projects somewhere (e.g. ``hack/my-scripts/mods/``, or
+    raw/objects/...
-maybe somewhere outside your Dwarf Fortress installation) and use your mod ID
+    raw/scripts/example-mod/main.lua
-(in hyphen-case) as the name for the mod folders within it. The structure of and
+    raw/scripts/example-mod/...
-environment for fully-functioning modular mods are as follows:
+    README.md
-
+
-* The main content of the mod would be in the ``raw`` folder:
+Let's go through that line by line.
-
+
-  * A Lua file in ``raw/init.d/`` to initialise the mod by calling
+* You'll need a short script in ``raw/init.d/`` to initialise your mod when a save is
-    ``your-mod-id/main enable``.
+  loaded.
-  * Raw content (potentially with custom raw tokens) in ``raw/objects/``.
+* Modifications to the game raws (potentially with custom raw tokens) go in
-  * A subfolder for your mod in ``raw/scripts/`` containing a ``main.lua`` file
+  ``raw/objects/``.
-    (an example of which we will see) and all the modules containing the functions
+* A subfolder for your mod under ``raw/scripts/`` will contain all the scripts used by
-    used in callbacks to ``repeat-util`` and ``eventful``. Potentially a file
+  your mod, including the main initialization code in ``main.lua`` which registers all
-    containing constant definitions used by your mod (perhaps defined by the
+  your timer and event callbacks.
-    game, like the acceleration of parabolic projectiles due to gravity
+
-    (``4900``)) too.
+It is a good idea to use a version control system to organize changes to your mod code.
-
+You can create a separate Git repository for each of your mods. The ``README.md`` file
-* Using git within each mod folder is recommended, but not required.
+will be your mod help text when people browse to your online repository.
-* A ``readme.md`` markdown file is also recommended.
+
-* An ``addToEntity.txt`` file containing lines to add to entity definitions for
+Unless you want to install your ``raw`` folder into your DF game folder every time you
-  access to mod content would be needed if applicable.
+make a change to your scripts, you should add your development scripts directory to your
-* Unless you want to merge your ``raw`` folder with your worlds every time you
+script paths in ``dfhack-config/script-paths.txt``::
-  make a change to your scripts, you should add
+
-  ``path/to/your-mod/raw/scripts/`` to your script paths.
+    +/path/to/mymods/example-mod/raw/scripts
-
+
-Now, let's take a look at an example ``raw/scripts/main.lua`` file. ::
+Ok, you're all set up! Now, let's take a look at an example
-
+``raw/scripts/example-mod/main.lua`` file::
-    local repeatUtil = require("repeat-util")
+
-    local eventful = require("plugins.eventful")
+    local repeatUtil = require('repeat-util')
+    local eventful = require('plugins.eventful')
 
-    local modId = "example-mod"
+    local modId = 'example-mod'
     local args = {...}
 
     if args[1] == "enable" then