Use command name only for internal hyperlinks

Because it's not actually that important to the user how a command is
implemented, and the docs should reflect that.  This also makes them
easier to write!
develop
PeridexisErrant 2015-10-19 14:16:19 +11:00
parent bd5eb82554
commit c5d6e693f8
7 changed files with 96 additions and 98 deletions

@ -8,11 +8,11 @@ and plugins implementing a wide variety of useful functions and tools.
For users, it provides a significant suite of bugfixes and interface
enhancements by default, and more can be enabled. There are also many tools
(such as `plugins/workflow` or `plugins/autodump`) which can make life easier.
(such as `workflow` or `autodump`) which can make life easier.
You can even add third-party scripts and plugins to do almost anything!
For modders, DFHack makes many things possible. Custom reactions, new
interactions, magic creature abilities, and more can be set through `scripts <scripts/modtools>`
interactions, magic creature abilities, and more can be set through `modtools`
and custom raws. Non-standard DFHack scripts and inits can be stored in the
raw directory, making raws or saves fully self-contained for distribution -
or for coexistence in a single DF install, even with incompatible components.

@ -7,7 +7,7 @@ Patching the DF binary
Writing scripts and plugins for DFHack is not the only way to modify Dwarf
Fortress. Before DFHack, it was common for tools to manually patch the
binary to change behaviour, and DFHack still contains tools to do this via
the `scripts/binpatch` command.
the `binpatch` command.
.. warning::
@ -45,7 +45,7 @@ There are two methods to apply a patch.
Patching at runtime
-------------------
The `scripts/binpatch` script checks, applies or removes binary patches
The `binpatch` script checks, applies or removes binary patches
directly in memory at runtime::
binpatch [check|apply|remove] <patchname>
@ -107,7 +107,7 @@ armor stands, and in containers.
.. note::
In order to actually be used, weapon racks have to be patched and
manually assigned to a squad. See `scripts/gui/assign-rack`.
manually assigned to a squad. See `gui/assign-rack`.
Note that the buildings in the armory are used as follows:
@ -171,7 +171,7 @@ work again. The existing issues are:
.. _`the bug report`: http://www.bay12games.com/dwarves/mantisbt/view.php?id=1445
* Haulers still take equipment stored in the armory away to the stockpiles,
unless `plugins/fix-armory` is used.
unless `fix-armory` is used.
The script interface simply lets you designate one of the squads that
are assigned to the barracks/armory containing the selected stand as

@ -158,12 +158,12 @@ describe the effect::
If it would be helpful to mention another DFHack command, don't just type the
name - add a hyperlink! Specify the link target in backticks, and it will be
replaced with the corresponding title and linked: eg ```plugins/autolabor```
=> `plugins/autolabor`. Link targets should be the path to the file
replaced with the corresponding title and linked: eg ```autolabor```
=> `autolabor`. Link targets should be equivalent to the command
described (without file extension), and placed above the heading of that
section like this::
.. _plugins/autolabor:
.. _autolabor:
autolabor
=========

@ -112,7 +112,7 @@ 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
they are re-created every time it is loaded.
Interactive commands like `plugins/liquids` cannot be used as hotkeys.
Interactive commands like `liquids` cannot be used as hotkeys.
Many commands come from plugins, which are stored in ``hack/plugins/``
and must be compiled with the same version of DFHack. Others come

@ -18,7 +18,7 @@ Informative Plugins
Visualizer and data export
==========================
.. _plugins/stonesense:
.. _stonesense:
stonesense
----------
@ -61,7 +61,7 @@ Options (If only region and name are given, export all):
:place: Export stockpile commands to "<name>-place.csv"
:query: Export query commands to "<name>-query.csv"
Goes very well with `plugins/fortplan`, for re-importing.
Goes very well with `fortplan`, for re-importing.
Map inspection
@ -120,7 +120,7 @@ probe
-----
Can be used to determine tile properties like temperature.
.. _plugins/prospect:
.. _prospect:
prospect
--------
@ -148,7 +148,7 @@ Options:
:all: Also estimate vein mineral amounts.
.. _plugins/reveal:
.. _reveal:
reveal
------
@ -248,7 +248,7 @@ Usage:
:petcapRemover pregtime n: sets the pregnancy duration to n ticks. natural pregnancies are
300000 ticks for the current race and 200000 for everyone else
.. _plugins/tweak:
.. _tweak:
tweak
=====
@ -328,7 +328,7 @@ Subcommands that persist until disabled or DF quits:
:stable-cursor: Saves the exact cursor position between t/q/k/d/b/etc menus of fortress mode.
:tradereq-pet-gender: Displays pet genders on the trade request screen
.. _plugins/fix-armory:
.. _fix-armory:
fix-armory
==========
@ -501,7 +501,7 @@ furniture placement. You can then place furniture and other buildings before
the required materials are available, and the job will be unsuspended when
the item is created.
Very useful when combined with `plugins/workflow` - you can set a constraint
Very useful when combined with `workflow` - you can set a constraint
to always have one or two doors/beds/tables/chairs/etc available, and place
as many as you like. The plugins then take over and fulfill the orders,
with minimal space dedicated to stockpiles.
@ -542,7 +542,7 @@ Usage::
mousequery [plugin] [rbutton] [track] [edge] [live] [enable|disable]
.. _plugins/resume:
.. _resume:
resume
------
@ -566,12 +566,12 @@ Toggle between displaying/not displaying liquid depth as numbers.
stockpile management
--------------------
.. _plugins/stocksettings:
.. _stocksettings:
import/export
~~~~~~~~~~~~~
The following commands allow you to save and load stockpile settings.
See `scripts/gui/stockpiles` for an in-game interface.
See `gui/stockpiles` for an in-game interface.
:copystock: Copies the parameters of the currently highlighted stockpile to the custom
stockpile settings and switches to custom stockpile placement mode, effectively
@ -609,11 +609,11 @@ designated to be taken to the Trade Depot whenever merchants are on the map.
When autodump is enabled for a stockpile, any items placed in this stockpile will
automatically be designated to be dumped.
.. _plugins/rename:
.. _rename:
rename
------
Allows renaming various things. Use `scripts/gui/rename` for an in-game interface.
Allows renaming various things. Use `gui/rename` for an in-game interface.
Options:
@ -893,7 +893,7 @@ all valid plant IDs will be listed.
Job and Fortress management
===========================
.. _plugins/autolabor:
.. _autolabor:
autolabor
=========
@ -951,7 +951,7 @@ Advanced usage:
:autolabor list: List current status of all labors.
:autolabor status: Show basic status information.
See `scripts/autolabor-artisans` for a differently-tunde setup.
See `autolabor-artisans` for a differently-tunde setup.
Examples:
@ -989,7 +989,7 @@ ALCHEMIST labor but can be changed by the user.
Job management
==============
.. _plugins/job:
.. _job:
job
---
@ -1060,13 +1060,13 @@ number of identical orders already in the queue.
In fast mode, new work orders will be enqueued once per day, instead of
waiting for the bookkeeper.
.. _plugins/workflow:
.. _workflow:
workflow
--------
Manage control of repeat jobs.
Check out `scripts/gui/workflow` for a simple front-end integrated
Check out `gui/workflow` for a simple front-end integrated
in the game UI.
Usage:
@ -1183,7 +1183,7 @@ Maintain 10-100 locally-made crafts of exceptional quality::
Cleanup and garbage disposal
============================
.. _plugins/clean:
.. _clean:
clean
-----
@ -1207,7 +1207,7 @@ spotclean
Works like ``clean map snow mud``, but only for the tile under the cursor. Ideal
if you want to keep that bloody entrance ``clean map`` would clean up.
.. _plugins/autodump:
.. _autodump:
autodump
--------
@ -1360,7 +1360,7 @@ Examples:
``seedwatch all 30``
adds all plants from the abbreviation list to the watch list, the limit being 30.
.. _plugins/zone:
.. _zone:
zone
----
@ -1509,7 +1509,7 @@ Options:
:sleep: Must be followed by number X. Changes the timer to sleep X
frames between runs.
.. _plugins/autobutcher:
.. _autobutcher:
autobutcher
-----------
@ -1518,8 +1518,8 @@ you add the target race(s) to a watch list. Only tame units will be processed.
Units will be ignored if they are:
* Nicknamed (for custom protection; you can use the `plugins/rename` ``unit`` tool
individually, or `plugins/zone` ``nick`` for groups)
* Nicknamed (for custom protection; you can use the `rename` ``unit`` tool
individually, or `zone` ``nick`` for groups)
* Caged, if and only if the cage is defined as a room (to protect zoos)
* Trained for war or hunting
@ -1528,7 +1528,7 @@ opposite sex or have been gelded) will be butchered before those who will.
Older adults and younger children will be butchered first if the population
is above the target (default 1 male, 5 female kids and adults). Note that
you may need to set a target above 1 to have a reliable breeding population
due to asexuality etc. See `scripts/fix-ster` if this is a problem.
due to asexuality etc. See `fix-ster` if this is a problem.
Options:
@ -1675,7 +1675,7 @@ the command for the second time should produce no change. It is best to
run it just once immediately after embark.
This command is intended as only a cosmetic change, so it takes
care to exactly preserve the mineral counts reported by `plugins/prospect` ``all``.
care to exactly preserve the mineral counts reported by `prospect` ``all``.
The amounts of different layer stones may slightly change in some cases
if vein mass shifts between Z layers.
@ -1692,7 +1692,7 @@ changes only the layer at the cursor position. Note that one layer can stretch
across lots of z levels. By default changes only the geology which is linked
to the biome under the cursor. That geology might be linked to other biomes
as well, though. Mineral veins and gem clusters will stay on the map. Use
`plugins/changevein` for them.
`changevein` for them.
tl;dr: You will end up with changing quite big areas in one go, especially if
you use it in lower z levels. Use with care.
@ -1744,7 +1744,7 @@ Examples:
Try reverting the changes manually or even better use an older savegame.
You did save your game, right?
.. _plugins/changevein:
.. _changevein:
changevein
==========
@ -1823,14 +1823,14 @@ Options:
:show X: Marks the selected map feature as discovered.
:hide X: Marks the selected map feature as undiscovered.
.. _plugins/fortplan:
.. _fortplan:
fortplan
========
Usage: fortplan [filename]
Designates furniture for building according to a .csv file with
quickfort-style syntax. Companion to `scripts/digfort`.
quickfort-style syntax. Companion to `digfort`.
The first line of the file must contain the following::
@ -1842,7 +1842,7 @@ is an optional description of where that is. You may also leave a description
of the contents of the file itself following the closing parenthesis on the
same line.
The syntax of the file itself is similar to `scripts/digfort` or
The syntax of the file itself is similar to `digfort` or
`quickfort <http://www.bay12forums.com/smf/index.php?topic=35931>`_. At present,
only buildings constructed of an item with the same name as the building
are supported. All other characters are ignored. For example::
@ -1878,7 +1878,7 @@ Usage:
cause cave-ins. Saving and loading after creating new z-levels should
fix the problem.
.. _plugins/liquids:
.. _liquids:
liquids
=======
@ -2138,7 +2138,7 @@ but do jobs at the same speed.
:fastdwarf 0 1: disables speedydwarf and enables teledwarf
:fastdwarf 1 1: enables both
.. _plugins/forceequip:
.. _forceequip:
forceequip
==========
@ -2146,14 +2146,14 @@ Forceequip moves local items into a unit's inventory. It is typically used to
equip specific clothing/armor items onto a dwarf, but can also be used to put
armor onto a war animal or to add unusual items (such as crowns) to any unit.
For more information run ``forceequip help``. See also `scripts/modtools/equip-item`.
For more information run ``forceequip help``. See also `modtools/equip-item`.
lair
====
This command allows you to mark the map as a monster lair, preventing item
scatter on abandon. When invoked as ``lair reset``, it does the opposite.
Unlike `plugins/reveal`, this command doesn't save the information about tiles - you
Unlike `reveal`, this command doesn't save the information about tiles - you
won't be able to restore state of real monster lairs using ``lair reset``.
Options:
@ -2197,7 +2197,7 @@ Examples:
* You switch to the adventure game mode, assume control of a creature, then save or retire.
* You just created a returnable mountain home and gained an adventurer.
.. _plugins/strangemood:
.. _strangemood:
strangemood
===========
@ -2227,7 +2227,7 @@ These plugins, when activated via configuration UI or by detecting certain
structures in RAWs, modify the game engine behavior concerning the target
objects to add features not otherwise present.
.. _plugins/siege-engine:
.. _siege-engine:
Siege Engine
------------
@ -2243,7 +2243,7 @@ just stones.
Configuration UI
~~~~~~~~~~~~~~~~
The configuration front-end to the plugin is implemented by `scripts/gui/siege-engine`.
The configuration front-end to the plugin is implemented by `gui/siege-engine`.
Bind it to a key (the example config uses Alt-A) and activate after selecting
a siege engine in ``q`` mode.
@ -2269,14 +2269,14 @@ Exiting from the siege engine script via ESC reverts the view to the state prior
the script. Shift-ESC retains the current viewport, and also exits from the ``q`` mode to main
menu.
.. _plugins/power-meter:
.. _power-meter:
Power Meter
-----------
The power-meter plugin implements a modified pressure plate that detects power being
supplied to gear boxes built in the four adjacent N/S/W/E tiles.
The configuration front-end is implemented by `scripts/gui/power-meter`. Bind it to a
The configuration front-end is implemented by `gui/power-meter`. Bind it to a
key (the example config uses Ctrl-Shift-M) and activate after selecting Pressure Plate
in the build menu.
@ -2384,11 +2384,11 @@ add-spatter
This plugin makes reactions with names starting with ``SPATTER_ADD_``
produce contaminants on the items instead of improvements. The produced
contaminants are immune to being washed away by water or destroyed by
the `plugins/clean` ``items`` command.
the `clean` ``items`` command.
The plugin is intended to give some use to all those poisons that can
be bought from caravans. :)
To be really useful this needs patches from bug 808, `plugins/tweak`
``fix-dimensions`` and `plugins/tweak` ``advmode-contained``.
To be really useful this needs patches from bug 808, `tweak`
``fix-dimensions`` and `tweak` ``advmode-contained``.

@ -113,7 +113,7 @@ fix/stable-temp
===============
Instantly sets the temperature of all free-lying items to be in equilibrium with
the environment and stops temperature updates. In order to maintain this efficient
state however, use `plugins/tweak` ``stable-temp`` and `plugins/tweak` ``fast-heat``.
state however, use `tweak` ``stable-temp`` and `tweak` ``fast-heat``.
fix/stuckdoors
==============
@ -162,7 +162,7 @@ gui/advfort_items
=================
Does something with items in adventure mode jobs.
.. _scripts/gui/assign-rack:
.. _gui/assign-rack:
gui/assign-rack
===============
@ -171,7 +171,7 @@ been available since DF 0.34.11
gui/autobutcher
===============
An in-game interface for `plugins/autobutcher`.
An in-game interface for `autobutcher`.
gui/choose-weapons
==================
@ -210,7 +210,7 @@ case. Must be in look or talk mode to issue command on tile.
* follow - rejoin the party after "wait"
* leave - remove from party (can be rejoined by talking)
.. _scripts/gui/create-item:
.. _gui/create-item:
gui/create-item
===============
@ -255,7 +255,7 @@ computes it when the order is executed for the first time.
gui/hack-wish
=============
An alias for `scripts/gui/create-item`. Deprecated.
An alias for `gui/create-item`. Deprecated.
gui/hello-world
===============
@ -267,7 +267,7 @@ To use, bind to a key (the example config uses Alt-L) and activate in the 'k' mo
.. image:: images/liquids.png
This script is a gui front-end to `plugins/liquids` and works similarly,
This script is a gui front-end to `liquids` and works similarly,
allowing you to add or remove water & magma, and create obsidian walls & floors.
.. warning::
@ -318,17 +318,17 @@ gui/no-dfhack-init
==================
Shows a warning at startup if no valid ``dfhack.init`` file is found.
.. _scripts/gui/power-meter:
.. _gui/power-meter:
gui/power-meter
===============
An in-game interface for `plugins/power-meter`.
An in-game interface for `power-meter`.
.. _scripts/gui/rename:
.. _gui/rename:
gui/rename
==========
Backed by `plugins/rename`, this script allows entering the desired name
Backed by `rename`, this script allows entering the desired name
via a simple dialog in the game ui.
* ``gui/rename [building]`` in 'q' mode changes the name of a building.
@ -364,17 +364,17 @@ either immediately or after opening the assign owner page.
The script lists other rooms owned by the same owner, or by the unit selected in the assign
list, and allows unassigning them.
.. _scripts/gui/siege-engine:
.. _gui/siege-engine:
gui/siege-engine
================
An in-game interface for `plugins/siege-engine`.
An in-game interface for `siege-engine`.
.. _scripts/gui/stockpiles:
.. _gui/stockpiles:
gui/stockpiles
==============
An in-game interface for `plugins/stocksettings`, to
An in-game interface for `stocksettings`, to
load and save stockpile settings from the 'q' menu.
Usage:
@ -392,7 +392,7 @@ gui/unit-info-viewer
Displays age, birth, maxage, shearing, milking, grazing, egg laying, body size,
and death info about a unit. Recommended keybinding Alt-I.
.. _scripts/gui/workflow:
.. _gui/workflow:
gui/workflow
============
@ -401,7 +401,7 @@ in a workshop in the 'q' mode.
.. image:: images/workflow.png
This script provides a simple interface to constraints managed by `plugins/workflow`.
This script provides a simple interface to constraints managed by `workflow`.
When active, it displays a list of all constraints applicable to the
current job, and their current status.
@ -419,8 +419,8 @@ items and expanding the range each gives a 2x bonus).
Pressing 'A' produces a list of possible outputs of this job as guessed by
workflow, and lets you create a new constraint by choosing one as template. If you
don't see the choice you want in the list, it likely means you have to adjust
the job material first using `plugins/job` ``item-material`` or `scripts/gui/workshop-job`,
as described in `plugins/workflow` documentation. In this manner, this feature
the job material first using `job` ``item-material`` or `gui/workshop-job`,
as described in `workflow` documentation. In this manner, this feature
can be used for troubleshooting jobs that don't match the right constraints.
.. image:: images/workflow-new1.png
@ -455,7 +455,7 @@ of stock history for the selected item, with the rightmost point representing
the current stock value. The bright green dashed line is the target
limit (maximum) and the dark green line is that minus the gap (minimum).
.. _scripts/gui/workshop-job:
.. _gui/workshop-job:
gui/workshop-job
================
@ -465,7 +465,7 @@ a workshop in the 'q' mode.
.. image:: images/workshop-job.png
The script shows a list of the input reagents of the selected job, and allows changing
them like the `plugins/job` ``item-type`` and `plugins/job` ``item-material`` commands.
them like the `job` ``item-type`` and `job` ``item-material`` commands.
Specifically, pressing the 'i' key pops up a dialog that lets you select an item
type from a list.
@ -503,7 +503,7 @@ material is matched against the barrel itself. Then, if you select, say, iron,
and then try to change the input item type, now it won't let you select *plant*;
you have to unset the material first.
.. _scripts/modtools:
.. _modtools:
========================
modtools/* - for modders
@ -544,14 +544,14 @@ modtools/create-unit
====================
Creates a unit.
.. _scripts/modtools/equip-item:
.. _modtools/equip-item:
modtools/equip-item
===================
Force a unit to equip an item; useful in conjunction with the ``create``
scripts above.
See also `plugins/forceequip`.
See also `forceequip`.
modtools/force
==============
@ -631,8 +631,6 @@ Other Scripts
=============
These scripts are not stored in any subdirectory, and can be invoked directly.
.. include:: ../scripts/include-all.rst
add-thought
===========
Adds a thought or emotion to the selected unit. Can be used by other scripts,
@ -646,8 +644,8 @@ between 0 and 800,000 inclusive.
armoks-blessing
===============
Runs the equivalent of `scripts/rejuvenate`, `scripts/elevate-physical`,
`scripts/elevate-mental`, and `scripts/brainwash`
Runs the equivalent of `rejuvenate`, `elevate-physical`,
`elevate-mental`, and `brainwash`
on all dwarves currently on the map. This is an extreme change, which sets every
stat to an ideal - legendary skills, great traits, and easy-to-satisfy preferences.
Use in moderation; it's as 'cheaty' as DFHack gets.
@ -664,18 +662,18 @@ Usage::
autofarm default 30
autofarm threshold 150 helmet_plump tail_pig
.. _scripts/autolabor-artisans:
.. _autolabor-artisans:
autolabor-artisans
==================
Runs `plugins/autolabor`, with settings tuned for small but highly skilled workforces.
Runs `autolabor`, with settings tuned for small but highly skilled workforces.
.. _scripts/autounsuspend:
.. _autounsuspend:
autounsuspend
=============
Automatically unsuspend jobs in workshops, on a recurring basis.
See `scripts/unsuspend` for one-off use, or `plugins/resume` ``all``.
See `unsuspend` for one-off use, or `resume` ``all``.
ban-cooking
===========
@ -683,13 +681,13 @@ A more convenient way to ban cooking various categories of foods than the
kitchen interface. Usage: ``ban-cooking <type>``. Valid types are ``booze``,
``honey``, ``tallow``, ``oil``, and ``seeds`` (non-tree plants with seeds).
.. _scripts/binpatch:
.. _binpatch:
binpatch
========
Implements functions for in-memory binpatches. See `binpatches`.
.. _scripts/brainwash:
.. _brainwash:
brainwash
=========
@ -747,7 +745,7 @@ dfusion
=======
Interface to a lecacy script system.
.. _scripts/digfort:
.. _digfort:
digfort
=======
@ -779,7 +777,7 @@ drain-aquifer
=============
Remove all 'aquifer' tag from the map blocks. Irreversible.
.. _scripts/elevate-mental:
.. _elevate-mental:
elevate-mental
==============
@ -787,7 +785,7 @@ Set all mental attributes of a dwarf to 2600, which is very high.
Other numbers can be passed as an argument: ``elevate-mental 100``
for example would make the dwarf very stupid indeed.
.. _scripts/elevate-physical:
.. _elevate-physical:
elevate-physical
================
@ -853,7 +851,7 @@ fixnaked
========
Removes all unhappy thoughts due to lack of clothing.
.. _scripts/fix-ster:
.. _fix-ster:
fix-ster
========
@ -916,7 +914,7 @@ Lists the key, name, and jump position of your hotkeys in the DFHack console.
item-descriptions
=================
Exports a table with custom description text for every item in the game.
Used by `scripts/view-item-info`.
Used by `view-item-info`.
lever
=====
@ -1063,7 +1061,7 @@ Usage:
:region-pops incr-all <pattern> <factor>:
Same as above, but match using a pattern acceptable to list.
.. _scripts/rejuvenate:
.. _rejuvenate:
rejuvenate
==========
@ -1080,7 +1078,7 @@ remove-wear
===========
Sets the wear on all items in your fort to zero.
.. _scripts/repeat:
.. _repeat:
repeat
======
@ -1183,7 +1181,7 @@ The number must be 7 or greater.
stripcaged
==========
For dumping items inside cages. Will mark selected items for dumping, then
a dwarf may come and actually dump it. See also `plugins/autodump`.
a dwarf may come and actually dump it. See also `autodump`.
With the ``items`` argument, only dumps items laying in the cage, excluding
stuff worn by caged creatures. ``weapons`` will dump worn weapons, ``armor``
@ -1226,14 +1224,14 @@ undump-buildings
================
Undesignates building base materials for dumping.
.. _scripts/unsuspend:
.. _unsuspend:
unsuspend
=========
Unsuspend jobs in workshops, on a one-off basis. See `scripts/autounsuspend`
Unsuspend jobs in workshops, on a one-off basis. See `autounsuspend`
for regular use.
.. _scripts/view-item-info:
.. _view-item-info:
view-item-info
==============
@ -1250,6 +1248,6 @@ warn-starving
=============
If any (live) units are starving, very thirsty, or very drowsy, the game will
be paused and a warning shown and logged to the console. Use with the
`scripts/repeat` command for regular checks.
`repeat` command for regular checks.
Use ``warn-starving all`` to display a list of all problematic units.

@ -4,7 +4,7 @@
--[[
BEGIN_DOCS
.. _scripts/add-thought
.. _add-thought:
add-thought
===========