Merge pull request #979 from PeridexisErrant/core-commands

Core.rst: document how commands work and are used

docs/Core.rst

@@ -4,6 +4,12 @@
 DFHack Core
 ###########
 
+.. contents::
+   :depth: 2
+
+
+Command Implementation
+======================
 DFHack commands can be implemented in three ways, all of which
 are used in the same way:
 
@@ -21,7 +27,73 @@ are used in the same way:
             Most third-party DFHack addons are scripts.
 
 
-.. contents::
+Using DFHack Commands
+=====================
+DFHack commands can be executed in a number of ways:
+
+#. Typing the command into the DFHack console (see below)
+#. From the OS terminal (see below)
+#. Pressing a key combination set up with `keybinding`
+#. From one of several `init-files`, automatically
+#. Using `script` to run a batch of commands from a file
+
+The DFHack Console
+------------------
+The command line has some nice line editing capabilities, including history
+that's preserved between different runs of DF - use :kbd:`↑` and :kbd:`↓`
+to go through the history.
+
+To include whitespace in the argument/s to some command, quote it in
+double quotes.  To include a double quote character, use ``\"``.
+
+If the first non-whitespace character is ``:``, the command is parsed in
+an alternative mode.  The non-whitespace characters following the ``:`` are
+the command name, and the remaining part of the line is used verbatim as
+the first argument.  This is very useful for the `lua` and `rb` commands.
+As an example, the following two command lines are exactly equivalent::
+
+  :foo a b "c d" e f
+  foo "a b \"c d\" e f"
+
+Using an OS terminal
+--------------------
+DFHack commands can be run from an OS terminal at startup, using '+ args',
+or at any other time using the ``dfhack-run`` executable.
+
+If DF/DFHack is started with arguments beginning with ``+``, the remaining
+text is treated as a command in the DFHack console.  It is possible to use
+multiple such commands, which are split on ``+``.  For example::
+
+    ./dfhack +load-save region1
+    "Dwarf Fortress.exe" +devel/print-args Hello! +enable workflow
+
+The first example (\*nix), `load-save`, skips the main menu and loads
+``region1`` immediately.  The second (Windows) example prints
+:guilabel:`Hello!` in the DFHack console, and `enables <enable>` `workflow`.
+Note that the ``:foo`` syntax for whitespace in arguments is not compatible \
+with '+ args'.
+
+
+If DF and DFHack are already running, calling ``dfhack-run my command``
+in an external terminal is equivalent to calling ``my command`` in the
+DFHack console.  Direct use of the DFhack console is generally easier,
+but ``dfhack-run`` can be useful in a variety of circumstances:
+
+- if the console is unavailable
+
+  - with the init setting ``PRINT_MODE:TEXT``
+  - while running an interactive command (eg. `liquids` or `tiletypes`)
+
+- from external programs or scripts
+- if DF or DFHack are not responding
+
+Examples::
+
+    ./dfhack-run cursecheck
+    dfhack-run multicmd kill-lua; die
+
+The first (\*nix) example `checks for vampires <cursecheck>`; the
+second (Windows) example uses `kill-lua` to cancel a script and exits.
 
 
 Built-in Commands
@@ -29,6 +101,8 @@ Built-in Commands
 The following commands are provided by the 'core' components
 of DFhack, rather than plugins or scripts.
 
+.. contents::
+   :local:
 
 .. _cls:
 
@@ -245,6 +319,10 @@ The following commands are *not* built-in, but offer similarly useful functions.
 
 Init Files
 ==========
+
+.. contents::
+   :local:
+
 DFHack allows users to automatically run commonly-used DFHack commands
 when DF is first loaded, when a game is loaded, and when a game is unloaded.
 
@@ -329,34 +407,14 @@ Miscellaneous Notes
 ===================
 This section is for odd but important notes that don't fit anywhere else.
 
-* The ``dfhack-run`` executable is there for calling DFHack commands in
-  an already running DF+DFHack instance from external OS scripts and programs,
-  and is *not* the way how you use DFHack normally.
-
 * If a DF :kbd:`H` hotkey is named with a DFHack command, pressing
   the corresponding :kbd:`Fx` button will run that command, instead of
   zooming to the set location.
-
+  *This feature will be removed in a future version.*  (see :issue:`731`)
-* The command line has some nice line editing capabilities, including history
-  that's preserved between different runs of DF (use up/down keys to go through
-  the history).
 
 * The binaries for 0.40.15-r1 to 0.34.11-r4 are on DFFD_.
   Older versions are available here_.
+  *These files will eventually be migrated to GitHub.*  (see :issue:`473`)
 
   .. _DFFD: http://dffd.bay12games.com/search.php?string=DFHack&id=15&limit=1000
   .. _here: http://dethware.org/dfhack/download
-
-* To include whitespace in the argument/s to some command, quote it in
-  double quotes.  To include a double quote character, use ``\"``.
-
-* If the first non-whitespace character is ``:``, the command is parsed in
-  an alternative mode which is very useful for the `lua` and `rb` commands.
-  The following two command lines are exactly equivalent::
-
-    :foo a b "c d" e f
-    foo "a b \"c d\" e f"
-
-  * non-whitespace characters following the ``:`` are the command name
-  * the remaining part of the line is used verbatim as the first argument
-

docs/Plugins.rst

@@ -57,6 +57,8 @@ An in-development plugin for realtime fortress visualisation.
 See :forums:`Armok Vision <146473>`.
 
 
+.. _cursecheck:
+
 cursecheck
 ==========
 Checks a single map tile or the whole map/world for cursed creatures (ghosts,
@@ -2208,7 +2210,8 @@ createitem
 Allows creating new items of arbitrary types and made of arbitrary materials.
 By default, items created are spawned at the feet of the selected unit.
 
-Specify the item and material information as you would indicate them in custom reaction raws, with the following differences:
+Specify the item and material information as you would indicate them in
+custom reaction raws, with the following differences:
 
 * Separate the item and material with a space rather than a colon
 * If the item has no subtype, omit the :NONE
@@ -2224,7 +2227,10 @@ Examples::
     createitem WOOD PLANT_MAT:TOWER_CAP:WOOD
             Create tower-cap logs.
 
-To change where new items are placed, first run the command with a destination type while an appropriate destination is selected.
+For more examples, :wiki:`see this wiki page <Utility:DFHack/createitem>`.
+
+To change where new items are placed, first run the command with a
+destination type while an appropriate destination is selected.
 
 Options: