Improve require() docs (#2553)

documentation/functions/global/require.md

@@ -8,17 +8,38 @@ ts_ignore: true
 `require(...)` loads the specified JavaScript or JSON file, allowing
 to split your configuration across multiple files.
 
+A better name for this function might be "include".
+
 If the supplied `path` string ends with `.js`, the file is interpreted
 as JavaScript code, almost as though its contents had been included in
 the currently-executing file.  If  the path string ends with `.json`,
 `require()` returns the `JSON.parse()` of the file's contents.
 
-If the path string begins with a `.`, it is interpreted relative to
+If the path string begins with a `./`, it is interpreted relative to
 the currently-loading file (which may not be the file where the
-`require()` statement is, if called within a function), otherwise it
+`require()` statement is, if called within a function). Otherwise it
 is interpreted relative to the program's working directory at the time
 of the call.
 
+### Example 1: Simple
+
+In this example, we separate our macros in one file, and put groups of domains
+in 3 other files. The result is a cleaner separation of code vs. domains.
+
+{% code title="dnsconfig.js" %}
+```javascript
+require("lib/macros.json");
+
+require("domains/main.json");
+require("domains/parked.json");
+require("domains/otherstuff.json");
+```
+{% endcode %}
+
+### Example 2: Complex
+
+Here's a more complex example:
+
 {% code title="dnsconfig.js" %}
 ```javascript
 require("kubernetes/clusters.js");
@@ -60,7 +81,9 @@ function includeK8Sdev() {
 ```
 {% endcode %}
 
-You can also use it to require JSON files and initialize variables with it:
+### Example 3: JSON
+
+Requiring JSON files initializes variables:
 
 {% code title="dnsconfig.js" %}
 ```javascript
@@ -83,16 +106,13 @@ for (var domain in domains) {
 ```
 {% endcode %}
 
-# Future
+# Notes
 
-It might be better to rename the function to something like
+`require()` is *much* closer to PHP's `include()` function than it
-`include()` instead, (leaving `require` as a deprecated alias) because
+is to node's `require()`.
-by analogy it is *much* closer to PHP's `include()` function than it
-is to node's `require()`.  After all, the reason node.js calls it
-"require" is because it's a declarative statement saying the file is
-needed, and so should be loaded if it hasn't already been loaded.
 
+Node's `require()` only includes a file once.
 In contrast, DNSControl's `require()` is actually an imperative command to
-load the file and execute the code or parse the data from it.  (So if
+load the file and execute the code or parse the data from it.  For example if
-two files both `require("./tools.js")`, for example, then it will be
+two files both `require("./tools.js")`, then it will be
-loaded twice, whereas in node.js it would only be loaded once.)
+loaded twice, whereas in node.js it would only be loaded once.

documentation/functions/global/require_glob.md

@@ -8,7 +8,7 @@ parameter_types:
   recursive: boolean
 ---
 
-`require_glob()` can recursively load `.js` files, optionally non-recursive as well.
+`require_glob()` recursively loads `.js` files that match a glob (wildcard). The recursion can be disabled.
 
 Possible parameters are:
 
@@ -31,8 +31,13 @@ require_glob("./domains/", false);
 ```
 {% endcode %}
 
-One more important thing to note: `require_glob()` is as smart as `require()` is. It loads files always relative to the JavaScript
+# Comparison to require()
-file where it's being executed in. Let's go with an example, as it describes it better:
+
+`require_glob()` and `require()` both use the same rules for determining which directory path is
+relative to.
+
+This will load files being present underneath `./domains/user1/` and **NOT** at below `./domains/`, as `require_glob()`
+is called in the subfolder `domains/`.
 
 {% code title="dnsconfig.js" %}
 ```javascript
@@ -45,6 +50,3 @@ require("domains/index.js");
 require_glob("./user1/");
 ```
 {% endcode %}
-
-This will now load files being present underneath `./domains/user1/` and **NOT** at below `./domains/`, as `require_glob()`
-is called in the subfolder `domains/`.