More consistent formatting

Eg use of monospaced font, line length, internal links, added xml SYNTAX
to root table of contents.
develop
PeridexisErrant 2015-09-24 20:17:58 +10:00
parent 0307b0830f
commit 2c2406727f
5 changed files with 113 additions and 66 deletions

@ -8,8 +8,8 @@ and plugins implementing a wide variety of useful functions and tools.
For users, it provides a significant suite of bugfixes and interface For users, it provides a significant suite of bugfixes and interface
enhancements by default, and more can be enabled. There are also many tools enhancements by default, and more can be enabled. There are also many tools
(such as ``workflow`` or ``autodump``) which can make life easier. You can (such as `plugins/workflow` or `plugins/autodump`) which can make life easier.
even add third-party scripts and plugins to do almost anything! You can even add third-party scripts and plugins to do almost anything!
For modders, DFHack makes many things possible. Custom reactions, new For modders, DFHack makes many things possible. Custom reactions, new
interactions, magic creature abilities, and more can be set through scripts interactions, magic creature abilities, and more can be set through scripts
@ -54,3 +54,4 @@ For Developers:
docs/Contributing docs/Contributing
docs/Compile docs/Compile
docs/Lua API docs/Lua API
library/xml/SYNTAX

@ -1,6 +1,6 @@
List of Authors List of Authors
=============== ===============
The following is a list of people who have contributed to **DFHack**, in no The following is a list of people who have contributed to DFHack, in no
particular order. particular order.
If you should be here and aren't, please get in touch or make a pull request! If you should be here and aren't, please get in touch or make a pull request!

@ -16,13 +16,14 @@ DFHack doesn't have any kind of system of code snapshots in place, so you will h
get code from the github repository using git. get code from the github repository using git.
The code resides at https://github.com/DFHack/dfhack The code resides at https://github.com/DFHack/dfhack
On Linux and OS X, having a 'git' package installed is the minimal requirement (see below for OS X instructions), On Linux and OS X, having a ``git`` package installed is the minimal requirement (see below for OS X instructions),
but some sort of git gui or git integration for your favorite text editor/IDE will certainly help. but some sort of git gui or git integration for your favorite text editor/IDE will certainly help.
On Windows, you will need some sort of Windows port of git, or a GUI. Some examples: On Windows, you will need some sort of Windows port of git, or a GUI. Some examples:
* http://msysgit.github.io/ - this is a command line version of git for windows. Most tutorials on git usage will apply. * http://msysgit.github.io - this is a command line version of git for windows.
* http://code.google.com/p/tortoisegit/ - this puts a pretty, graphical face on top of msysgit Most tutorials on git usage will apply.
* http://code.google.com/p/tortoisegit - this puts a pretty, graphical face on top of msysgit
To get the code:: To get the code::
@ -75,15 +76,18 @@ Before you can build anything, you'll also need ``cmake``. It is advisable to al
``ccmake`` on distributions that split the cmake package into multiple parts. ``ccmake`` on distributions that split the cmake package into multiple parts.
You also need perl and the XML::LibXML and XML::LibXSLT perl packages (for the code generation parts). You also need perl and the XML::LibXML and XML::LibXSLT perl packages (for the code generation parts).
You should be able to find them in your distro repositories (on Arch linux 'perl-xml-libxml' and 'perl-xml-libxslt') or through ``cpan``. You should be able to find them in your distro repositories (on Arch linux
``perl-xml-libxml`` and ``perl-xml-libxslt``) or through ``cpan``.
To build Stonesense, you'll also need OpenGL headers. To build Stonesense, you'll also need OpenGL headers.
Some additional dependencies for other distros are listed on the `wiki <https://github.com/DFHack/dfhack/wiki/Linux-dependencies>`_. Some additional dependencies for other distros are listed on the
`wiki <https://github.com/DFHack/dfhack/wiki/Linux-dependencies>`_.
Build Build
===== =====
Building is fairly straightforward. Enter the ``build`` folder (or create an empty folder in the DFHack directory to use instead) and start the build like this:: Building is fairly straightforward. Enter the ``build`` folder (or create an
empty folder in the DFHack directory to use instead) and start the build like this::
cd build cd build
cmake .. -DCMAKE_BUILD_TYPE:string=Release -DCMAKE_INSTALL_PREFIX=/home/user/DF cmake .. -DCMAKE_BUILD_TYPE:string=Release -DCMAKE_INSTALL_PREFIX=/home/user/DF
@ -205,7 +209,8 @@ Snow Leopard Changes
Yosemite Changes Yosemite Changes
================ ================
If you have issues building on OS X Yosemite (or above), try definining the following environment variable:: If you have issues building on OS X Yosemite (or above), try definining the
following environment variable::
export MACOSX_DEPLOYMENT_TARGET=10.9 export MACOSX_DEPLOYMENT_TARGET=10.9
@ -227,9 +232,13 @@ Grab it from Microsoft's site.
You'll also need the Visual Studio 2010 SP1 update. You'll also need the Visual Studio 2010 SP1 update.
For the code generation parts, you'll need perl with XML::LibXML and XML::LibXSLT. Strawberry Perl works nicely for this: http://strawberryperl.com/ For the code generation parts, you'll need perl with XML::LibXML and XML::LibXSLT.
`Strawberry Perl <http://strawberryperl.com>`_ works nicely for this.
If you already have a different version of perl (for example the one from cygwin), you can run into some trouble. Either remove the other perl install from PATH, or install libxml and libxslt for it instead. Strawberry perl works though and has all the required packages. If you already have a different version of perl (for example the one from cygwin),
you can run into some trouble. Either remove the other perl install from PATH, or
install libxml and libxslt for it instead. Strawberry perl works though and has
all the required packages.
Build Build
===== =====

@ -130,34 +130,52 @@ Other than through plugins, it is possible to use DFHack via remote access inter
The most important parts of DFHack are the Core, Console, Modules and Plugins. The most important parts of DFHack are the Core, Console, Modules and Plugins.
* Core acts as the centerpiece of DFHack - it acts as a filter between DF and SDL and synchronizes the various plugins with DF. * Core acts as the centerpiece of DFHack - it acts as a filter between DF and
SDL and synchronizes the various plugins with DF.
* Console is a thread-safe console that can be used to invoke commands exported by Plugins. * Console is a thread-safe console that can be used to invoke commands exported by Plugins.
* Modules actually describe the way to access information in DF's memory. You can get them from the Core. Most modules are split into two parts: high-level and low-level. High-level is mostly method calls, low-level publicly visible pointers to DF's data structures. * Modules actually describe the way to access information in DF's memory. You
* Plugins are the tools that use all the other stuff to make things happen. A plugin can have a list of commands that it exports and an onupdate function that will be called each DF game tick. can get them from the Core. Most modules are split into two parts: high-level
and low-level. High-level is mostly method calls, low-level publicly visible
Rudimentary API documentation can be built using doxygen (see build options with ``ccmake`` or ``cmake-gui``). pointers to DF's data structures.
* Plugins are the tools that use all the other stuff to make things happen.
A plugin can have a list of commands that it exports and an onupdate function
that will be called each DF game tick.
Rudimentary API documentation can be built using doxygen (see build options
with ``ccmake`` or ``cmake-gui``). The full DFHack documentation is built
with Sphinx, which runs automatically at compile time.
DFHack consists of variously licensed code, but invariably weak copyleft. DFHack consists of variously licensed code, but invariably weak copyleft.
The main license is zlib/libpng, some bits are MIT licensed, and some are BSD licensed. The main license is zlib/libpng, some bits are MIT licensed, and some are
BSD licensed. See the `license` document for more information.
Feel free to add your own extensions and plugins. Contributing back to Feel free to add your own extensions and plugins. Contributing back to
the dfhack repository is welcome and the right thing to do :) the dfhack repository is welcome and the right thing to do :)
DF data structure definitions DF data structure definitions
----------------------------- -----------------------------
DFHack uses information about the game data structures, represented via xml files
in the ``library/xml/`` submodule.
DFHack uses information about the game data structures, represented via xml files in the library/xml/ submodule. See https://github.com/DFHack/df-structures, and the documentation linked in the index.
See https://github.com/DFHack/df-structures
Data structure layouts are described in files following the df.\*.xml name pattern. This information is transformed by a perl script into C++ headers describing the structures, and associated metadata for the Lua wrapper. These headers and data are then compiled into the DFHack libraries, thus necessitating a compatibility break every time layouts change; in return it significantly boosts the efficiency and capabilities of DFHack code. Data structure layouts are described in files following the ``df.\*.xml`` name pattern.
This information is transformed by a perl script into C++ headers describing the
structures, and associated metadata for the Lua wrapper. These headers and data
are then compiled into the DFHack libraries, thus necessitating a compatibility
break every time layouts change; in return it significantly boosts the efficiency
and capabilities of DFHack code.
Global object addresses are stored in symbols.xml, which is copied to the dfhack release package and loaded as data at runtime. Global object addresses are stored in ``symbols.xml``, which is copied to the dfhack
release package and loaded as data at runtime.
Remote access interface Remote access interface
----------------------- -----------------------
DFHack supports remote access by exchanging Google protobuf messages via a TCP socket. Both the core and plugins can define remotely accessible methods. The ``dfhack-run`` command uses this interface to invoke ordinary console commands. DFHack supports remote access by exchanging Google protobuf messages via a TCP
socket. Both the core and plugins can define remotely accessible methods. The
``dfhack-run`` command uses this interface to invoke ordinary console commands.
Currently the supported set of requests is limited, because the developers don't know what exactly is most useful. Currently the supported set of requests is limited, because the developers don't
``remotefortressreader`` provides a fairly comprehensive interface for visualisers such as Armok Vision. know what exactly is most useful. ``remotefortressreader`` provides a fairly
comprehensive interface for visualisers such as Armok Vision.

@ -48,18 +48,18 @@ Installation/Removal
Installing DFhack involves copying files into your DF folder. Installing DFhack involves copying files into your DF folder.
Copy the files from a release archive so that: Copy the files from a release archive so that:
* On Windows, SDL.dll is replaced * On Windows, ``SDL.dll`` is replaced
* On Linux, the 'dfhack' script is placed in the same folder as the 'df' script * On Linux or OSX, the ``dfhack`` script is placed in the same folder as the ``df`` script
Uninstalling is basically the same, in reverse: Uninstalling is basically the same, in reverse:
* On Windows, first delete SDL.dll and rename SDLreal.dll to SDL.dll. Then * On Windows, first delete ``SDL.dll`` and rename ``SDLreal.dll`` to ``SDL.dll``,
remove the other DFHack files then remove the other DFHack files
* On Linux, Remove the DFHack files. * On Linux, remove the DFHack files.
The stonesense plugin might require some additional libraries on Linux. The stonesense plugin might require some additional libraries on Linux.
If any of the plugins or dfhack itself refuses to load, check the stderr.log If any of the plugins or dfhack itself refuses to load, check the ``stderr.log``
file created in your DF folder. file created in your DF folder.
@ -71,7 +71,7 @@ window once DF is started as usual on windows. Linux and Mac OS X require
running the dfhack script from the terminal, and will use that terminal for running the dfhack script from the terminal, and will use that terminal for
the console. the console.
**NOTE**: The dfhack-run executable is there for calling DFHack commands in **NOTE**: The ``dfhack-run`` executable is there for calling DFHack commands in
an already running DF+DFHack instance from external OS scripts and programs, an already running DF+DFHack instance from external OS scripts and programs,
and is *not* the way how you use DFHack normally. and is *not* the way how you use DFHack normally.
@ -86,18 +86,16 @@ called ``dfhack.init``; the installation comes with an example version called
features and can be simply renamed to ``dfhack.init``. You are encouraged to look features and can be simply renamed to ``dfhack.init``. You are encouraged to look
through it to learn which features it makes available under which key combinations. through it to learn which features it makes available under which key combinations.
For more information, refer to the rest of this document.
Using DFHack Using DFHack
============ ============
DFHack basically extends what DF can do with something similar to the drop-down DFHack basically extends what DF can do with something similar to the drop-down
console found in Quake engine games. On Windows, this is a separate command line console found in Quake engine games. On Windows, this is a separate command line
window. On linux, the terminal used to launch the dfhack script is taken over window. On Linux, the terminal used to launch the dfhack script is taken over
(so, make sure you start from a terminal). Basic interaction with dfhack (so, make sure you start from a terminal). Basic interaction with dfhack
involves entering commands into the console. For some basic instructions, involves entering commands into the console. For some basic instructions,
use the 'help' command. To list all possible commands, use the 'ls' command. use the ``help`` command. To list all possible commands, use the ``ls`` command.
Many commands have their own help or detailed description. You can use Many commands have their own help or detailed description. You can use
'command help' or 'command ?' to show that. ``command help`` or ``command ?`` to show that.
The command line has some nice line editing capabilities, including history 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 that's preserved between different runs of DF (use up/down keys to go through
@ -105,17 +103,21 @@ the history).
The second way to interact with DFHack is to bind the available commands The second way to interact with DFHack is to bind the available commands
to in-game hotkeys. The old way to do this is via the hotkey/zoom menu (normally to in-game hotkeys. The old way to do this is via the hotkey/zoom menu (normally
opened with the 'h' key). Binding the commands is done by assigning a command as opened with the ``h`` key). Binding the commands is done by assigning a command as
a hotkey name (with 'n'). a hotkey name (with ``n``).
A new and more flexible way is the keybinding command in the dfhack console. A new and more flexible way is the keybinding command in the dfhack console.
However, bindings created this way are not automatically remembered between runs However, bindings created this way are not automatically remembered between runs
of the game, so it becomes necessary to use the dfhack.init file to ensure that of the game, so it becomes necessary to use the dfhack.init file to ensure that
they are re-created every time it is loaded. they are re-created every time it is loaded.
Interactive commands like 'liquids' cannot be used as hotkeys. Interactive commands like `plugins/liquids` cannot be used as hotkeys.
Most of the commands come from plugins. Those reside in 'hack/plugins/'. Many commands come from plugins, which are stored in ``hack/plugins/``
and must be compiled with the same version of DFHack. Others come
from scripts, which are stored in ``hack/scripts``. Scripts are much
more flexible about versions, and easier to distribute - so most third-party
DFHack addons are scripts.
Something doesn't work, help! Something doesn't work, help!
============================= =============================
@ -151,27 +153,44 @@ The following two command lines are exactly equivalent::
This is intended for commands like ``rb_eval`` that evaluate script language statements. This is intended for commands like ``rb_eval`` that evaluate script language statements.
Almost all the commands support using the 'help <command-name>' built-in command Almost all the commands support using the ``help <command-name>`` built-in command
to retrieve further help without having to look at this document. Alternatively, to retrieve further help without having to look at this document. Alternatively,
some accept a 'help'/'?' option on their command line. some accept a ``help`` or ``?`` as an option on their command line.
Init files
==========
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.
Init scripts function the same way they would if the user manually typed in their contents,
but are much more convenient. If your DF folder contains at least one file with a name
following the format ``dfhack*.init`` where ``*`` is a placeholder for any string (including
the empty string), then all such files are executed in alphabetical order as init scripts when
DF is first loaded.
If your DF folder does not contain any such files, then DFHack will execute ``dfhack.init-example``
as an example of useful commands to be run automatically. If you want DFHack to do nothing on
its own, then create an empty ``dfhack.init`` file in the main DF directory, or delete ``dfhack.init-example``.
The file ``dfhack.init-example`` is included as an example for users to follow if they need DFHack
command executed automatically. We recommend modifying or deleting ``dfhack.init-example`` as
its settings will not be optimal for all players.
In order to facilitate savegave portability, mod merging, and general organization of init files,
DFHack supports multiple init files both in the main DF directory and save-specific init files in
the save folders.
The init file
=============
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.
Init scripts function the same way they would if the user manually typed in their contents, but are much more convenient.
If your DF folder contains at least one file with a name following the format ``dfhack*.init`` where ``*`` is a placeholder for any string (including the empty string), then all such files are executed in alphabetical order as init scripts when DF is first loaded.
If your DF folder does not contain any such files, then DFHack will execute ``dfhack.init-example`` as an example of useful commands to be run automatically.
If you want DFHack to do nothing on its own, then create an empty ``dfhack.init`` file in the main DF directory, or delete ``dfhack.init-example``.
The file ``dfhack.init-example`` is included as an example for users to follow if they need DFHack command executed automatically.
We highly recommend modifying or deleting ``dfhack.init-example`` as its settings will not be optimal for all players.
In order to facilitate savegave portability, mod merging, and general organization of init files, DFHack supports multiple init files both in the main DF directory and save-specific init files in the save folders.
DFHack looks for init files in three places. DFHack looks for init files in three places.
It will look for them in the main DF directory, and in ``data/save/_____/raw`` and ``data/save/_____/raw/objects`` where ``_____`` is the name of the current savegame.
When a game is loaded, DFHack looks for files of the form ``onLoad*.init``, where ``*`` can be any string, including the empty string. It will look for them in the main DF directory, and in ``data/save/_____/raw`` and
When a game is unloaded, DFHack looks for files of the form ``onUnload*.init``. ``data/save/_____/raw/objects`` where ``_____`` is the name of the current savegame.
Again, these files may be in any of the above three places.
All matching init files will be sorted and executed in alphebetical order. When a game is loaded, DFHack looks for files of the form ``onLoad*.init``, where
``*`` can be any string, including the empty string.
When a game is unloaded, DFHack looks for files of the form ``onUnload*.init``. Again,
these files may be in any of the above three places. All matching init files will be
executed in alphebetical order.
Setting keybindings Setting keybindings
=================== ===================
@ -192,22 +211,22 @@ Possible ways to call the command:
``keybinding set <key> "cmdline" "cmdline"...`` ``keybinding set <key> "cmdline" "cmdline"...``
Clear, and then add bindings for the specified key. Clear, and then add bindings for the specified key.
The *<key>* parameter above has the following *case-sensitive* syntax:: The ``<key>`` parameter above has the following *case-sensitive* syntax::
[Ctrl-][Alt-][Shift-]KEY[@context[|context...]] [Ctrl-][Alt-][Shift-]KEY[@context[|context...]]
where the *KEY* part can be any recognized key and [] denote optional parts. where the *KEY* part can be any recognized key and [] denote optional parts.
When multiple commands are bound to the same key combination, DFHack selects When multiple commands are bound to the same key combination, DFHack selects
the first applicable one. Later 'add' commands, and earlier entries within one the first applicable one. Later ``add`` commands, and earlier entries within one
'add' command have priority. Commands that are not specifically intended for use ``add`` command have priority. Commands that are not specifically intended for use
as a hotkey are always considered applicable. as a hotkey are always considered applicable.
The *context* part in the key specifier above can be used to explicitly restrict The ``context`` part in the key specifier above can be used to explicitly restrict
the UI state where the binding would be applicable. If called without parameters, the UI state where the binding would be applicable. If called without parameters,
the ``keybinding`` command among other things prints the current context string. the ``keybinding`` command among other things prints the current context string.
Only bindings with a *context* tag that either matches the current context fully, Only bindings with a ``context`` tag that either matches the current context fully,
or is a prefix ending at a '/' boundary would be considered for execution, i.e. or is a prefix ending at a ``/`` boundary would be considered for execution, i.e.
for context ``foo/bar/baz``, possible matches are any of ``@foo/bar/baz``, ``@foo/bar``, for context ``foo/bar/baz``, possible matches are any of ``@foo/bar/baz``, ``@foo/bar``,
``@foo`` or none. Multiple contexts can be specified by separating them with a ``@foo`` or none. Multiple contexts can be specified by separating them with a
pipe (``|``) - for example, ``@foo|bar|baz/foo``. pipe (``|``) - for example, ``@foo|bar|baz/foo``.