Merge pull request #979 from PeridexisErrant/core-commands

Core.rst: document how commands work and are used
2016-08-22 19:29:37 -04:00 · 2016-08-22 19:29:37 -04:00 · 5d87a10511
parent 93ac937cb9 570ac8d719
commit 5d87a10511
2 changed files with 89 additions and 25 deletions
--- a/docs/Core.rst
+++ b/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.
-
-* 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).
+  *This feature will be removed in a future version.*  (see :issue:`731`)

 * 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
-
--- a/docs/Plugins.rst
+++ b/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: