Document script paths

Ref #1690

docs/Core.rst

@@ -454,9 +454,55 @@ Other init files
   directory, will be run when any world or that save is loaded.
 
 
+.. _dfhack-config:
+
+Configuration Files
+===================
+
+Some DFHack settings can be changed by modifying files in the ``dfhack-config``
+folder (which is in the DF folder). The default versions of these files, if they
+exist, are in ``dfhack-config/default`` and are installed when DFHack starts if
+necessary.
+
+.. _script-paths:
+
+Script paths
+------------
+
+Script paths are folders that DFHack searches to find a script when a command is
+run. By default, the following folders are searched, in order (relative to the
+root DF folder):
+
+1. :file:`data/save/{<region folder>}/raw/scripts` (only if a save is loaded)
+2. :file:`raw/scripts`
+3. :file:`hack/scripts`
+
+For example, if ``teleport`` is run, these folders are searched in order for
+``teleport.lua`` or ``teleport.rb``, and the first matching file is run.
+
+Script paths can be added by modifying :file:`dfhack-config/script-paths.txt`.
+Each line should start with one of these characters:
+
+- ``+``: adds a script path that is searched *before* the default paths (above)
+- ``-``: adds a script path that is searched *after* the default paths
+- ``#``: a comment (the line is ignored)
+
+Paths can be absolute or relative - relative paths are interpreted relative to
+the root DF folder.
+
+.. admonition:: Tip
+
+    When developing scripts in the :source:scripts:`dfhack/scripts repo <>`,
+    it may be useful to add the path to your local copy of the repo with ``+``.
+    This will allow you to make changes in the repo and have them take effect
+    immediately, without needing to re-install or copy scripts over manually.
+
+
+Script paths can also be modified programmatically through the `Lua API <lua-api-internal>`.
+
 .. _env-vars:
 
-Environment variables
+Environment Variables
 =====================
 
 DFHack's behavior can be adjusted with some environment variables. For example,

docs/Lua API.rst

@@ -2213,6 +2213,8 @@ Console API
   Flushes all output to the console. This can be useful when printing text that
   does not end in a newline but should still be displayed.
 
+.. _lua-api-internal:
+
 Internal API
 ------------
 
@@ -2311,7 +2313,7 @@ and are only documented here for completeness:
 
 * ``dfhack.internal.addScriptPath(path, search_before)``
 
-  Adds ``path`` to the list of paths searched for scripts (both in Lua and Ruby).
+  Registers ``path`` as a `script path <script-paths>`.
   If ``search_before`` is passed and ``true``, the path will be searched before
   the default paths (e.g. ``raw/scripts``, ``hack/scripts``); otherwise, it will
   be searched after.
@@ -2321,17 +2323,18 @@ and are only documented here for completeness:
 
 * ``dfhack.internal.removeScriptPath(path)``
 
-  Removes ``path`` from the script search paths and returns ``true`` if successful.
+  Removes ``path`` from the list of `script paths <script-paths>` and returns
+  ``true`` if successful.
 
 * ``dfhack.internal.getScriptPaths()``
 
-  Returns the list of script paths in the order they are searched, including defaults.
+  Returns the list of `script paths <script-paths>` in the order they are
-  (This can change if a world is loaded.)
+  searched, including defaults. (This can change if a world is loaded.)
 
 * ``dfhack.internal.findScript(name)``
 
-  Searches script paths for the script ``name`` and returns the path of the first
+  Searches `script paths <script-paths>` for the script ``name`` and returns the
-  file found, or ``nil`` on failure.
+  path of the first file found, or ``nil`` on failure.
 
   .. note::
     This requires an extension to be specified (``.lua`` or ``.rb``) - use
@@ -4280,35 +4283,54 @@ Scripts
 .. contents::
    :local:
 
-Any files with the .lua extension placed into :file:`hack/scripts/*`
+Any files with the ``.lua`` extension placed into the :file:`hack/scripts` folder
-are automatically used by the DFHack core as commands. The
+are automatically made avaiable as DFHack commands. The command corresponding to
-matching command name consists of the name of the file without
+a script is simply the script's filename, relative to the scripts folder, with
-the extension. First DFHack searches for the script in the :file:`<save_folder>/raw/scripts/` folder. If it is not found there, it searches in the :file:`<DF>/raw/scripts/` folder. If it is not there, it searches in
+the extension omitted. For example:
-:file:`<DF>/hack/scripts/`. If it is not there, it gives up.
 
-If the first line of the script is a one-line comment, it is
+* :file:`hack/scripts/add-thought.lua` is invoked as ``add-thought``
-used by the built-in ``ls`` and ``help`` commands.
+* :file:`hack/scripts/gui/teleport.lua` is invoked as ``gui/teleport``
-Such a comment is required for every script in the official DFHack repository.
 
 .. note::
-    Scripts placed in subdirectories still can be accessed, but
+    Scripts placed in subdirectories can be run as described above, but are not
-    do not clutter the `ls` command list (unless ``ls -a``; thus it is preferred
+    listed by the `ls` command unless ``-a`` is specified. In general, scripts
-    for obscure developer-oriented scripts and scripts used by tools.
+    should be placed in subfolders in the following situations:
-    When calling such scripts, always use '/' as the separator for
+
-    directories, e.g. ``devel/lua-example``.
+    * ``devel``: scripts that are intended exclusively for DFHack development,
-
+      including examples, or scripts that are experimental and unstable
-Scripts are re-read from disk if they have changed since the last time they were read.
+    * ``fix``: fixes for specific DF issues
-Global variable values persist in memory between calls, unless the file has changed.
+    * ``gui``: GUI front-ends for existing tools (for example, see the
-Every script gets its own separate environment for global
+      relationship between `teleport` and `gui/teleport`)
-variables.
+    * ``modtools``: scripts that are intended to be run exclusively as part of
-
+      mods, not directly by end-users (as a rule of thumb: if someone other than
-Arguments are passed in to the scripts via the **...** built-in
+      a mod developer would want to run a script from the console, it should
-quasi-variable; when the script is called by the DFHack core,
+      not be placed in this folder)
-they are all guaranteed to be non-nil strings.
+
-
+Scripts can also be placed in other folders - by default, these include
-DFHack core invokes the scripts in the `core context <lua-core-context>`;
+:file:`raw/scripts` and :file:`data/save/{region}/raw/scripts`, but additional
-however it is possible to call them from any lua code (including
+folders can be added (for example, a copy of the
-from other scripts) in any context, via the same function the core uses:
+:source:scripts:`scripts repository <>` for local development). See
+`script-paths` for more information on how to configure this behavior.
+
+If the first line of the script is a one-line comment (starting with ``--``),
+the content of the comment is used by the built-in ``ls`` and ``help`` commands.
+Such a comment is required for every script in the official DFHack repository.
+
+Scripts are read from disk when run for the first time, or if they have changed
+since the last time they were run.
+
+Each script has an isolated environment where global variables set by the script
+are stored. Values of globals persist across script runs in the same DF session.
+See `devel/lua-example` for an example of this behavior. Note that local
+variables do *not* persist.
+
+Arguments are passed in to the scripts via the ``...`` built-in quasi-variable;
+when the script is called by the DFHack core, they are all guaranteed to be
+non-nil strings.
+
+DFHack invokes the scripts in the `core context <lua-core-context>`; however it
+is possible to call them from any lua code (including from other scripts) in any
+context, via the same function the core uses:
 
 * ``dfhack.run_script(name[,args...])``