From 780a9f3677917d6a2dea00a2cfabecc57b54cef5 Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Thu, 24 Sep 2015 16:30:11 +1000 Subject: [PATCH] Internal links and link targets, formatted tables * Enabled internal links; a phrase in backticks is linked to the corresponding link target and turns into the corresponding title. * Linked all existing references in Scripts.rst * Created corresponding link targets * Fixed formatting of some tables of arguments. --- docs/Plugins.rst | 148 +++++++++++++++++++++++++---------------------- docs/Scripts.rst | 110 +++++++++++++++++++++++++---------- docs/conf.py.in | 2 +- 3 files changed, 160 insertions(+), 100 deletions(-) diff --git a/docs/Plugins.rst b/docs/Plugins.rst index 5592889d7..b92cef810 100644 --- a/docs/Plugins.rst +++ b/docs/Plugins.rst @@ -18,6 +18,8 @@ Informative Plugins Visualizer and data export ========================== +.. _plugins/stonesense: + stonesense ---------- An isometric visualizer that runs in a second window. This requires working @@ -52,14 +54,14 @@ Exports a portion of your fortress into QuickFort style blueprint files.:: Options (If only region and name are given, export all): -:x,y,z: Size of map area to export -:name: Name of export files -:dig: Export dig commands to "-dig.csv" -:build: Export build commands to "-build.csv" -:place: Export stockpile commands to "-place.csv" -:query: Export query commands to "-query.csv" +:x,y,z: Size of map area to export +:name: Name of export files +:dig: Export dig commands to "-dig.csv" +:build: Export build commands to "-build.csv" +:place: Export stockpile commands to "-place.csv" +:query: Export query commands to "-query.csv" -Goes very well with ``fortplan``, for re-importing. +Goes very well with `plugins/fortplan`, for re-importing. Map inspection @@ -179,10 +181,6 @@ showmood Shows all items needed for the currently active strange mood. - - - - ======== Bugfixes ======== @@ -239,14 +237,15 @@ population booms as you go below the raised population cap, this plugin counts pregnancies toward the new population cap. It can still go over, but only in the case of multiple births. -`petcapRemover` - cause pregnancies now and schedule the next check -`petcapRemover every n` - set how often in ticks the plugin checks for possible pregnancies -`petcapRemover cap n` - set the new cap to n. if n = 0, no cap -`petcapRemover pregtime n` - sets the pregnancy duration to n ticks. natural pregnancies are 300000 ticks for the current race and 200000 for everyone else +Usage: + +:petcapRemover: cause pregnancies now and schedule the next check +:petcapRemover every n: set how often in ticks the plugin checks for possible pregnancies +:petcapRemover cap n: set the new cap to n. if n = 0, no cap +: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 ===== @@ -324,6 +323,8 @@ 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 ========== Enables a fix for storage of squad equipment in barracks. @@ -378,10 +379,6 @@ There are some minor traces in the game code to suggest that the first of these rules is intended by Toady; the rest are invented by this plugin. - - - - =========== UI Upgrades =========== @@ -447,10 +444,8 @@ The following mouse shortcuts are also available: Pressing ESC normally returns to the unit screen, but Shift-ESC would exit directly to the main dwarf mode screen. -Search +search ====== -Implemented by the 'search' plugin. - The search plugin adds search to the Stocks, Animals, Trading, Stockpile, Noble (assignment candidates), Military (position candidates), Burrows (unit list), Rooms, Announcements, Job List and Unit List screens. @@ -506,11 +501,8 @@ Tools: * ``sand``: Displays an indicator when sand is present in the currently-selected area, similar to the default clay/stone indicators. * ``sticky``: Maintains the selected local area while navigating the world map - -AutoMaterial +automaterial ------------ -Implemented by the 'automaterial' plugin. - This makes building constructions (walls, floors, fortifications, etc) a little bit easier by saving you from having to trawl through long lists of materials each time you place one. @@ -545,7 +537,6 @@ enabled materials, you should be able to place complex constructions more conven confirm ------- - Implements several confirmation dialogs for potentially destructive actions (for example, seizing goods from traders or deleting hauling routes). @@ -560,13 +551,20 @@ Makes the game view follow the currently highlighted unit after you exit from current menu/cursor mode. Handy for watching dwarves running around. Deactivated by moving the view manually. +.. _plugins/resume: + +resume +------ +Allows automatic resumption of suspended constructions, along with colored +UI hints for construction status. + tidlers ------- Toggle between all possible positions where the idlers count can be placed. trackstop --------- -Adds a `q` menu for track stops, which is completely blank by default. +Adds a ``q`` menu for track stops, which is completely blank by default. This allows you to view and/or change the track stop's friction and dump direction settings, using the keybindings from the track stop building interface. @@ -577,6 +575,8 @@ Toggle between displaying/not displaying liquid depth as numbers. stockpile management -------------------- +.. _plugins/stocksettings: + import/export ~~~~~~~~~~~~~ The following commands allow you to save and load stockpile settings. @@ -816,21 +816,22 @@ Options: digFlood -------- -Automatically digs out specified veins as they are discovered. It runs once every time a dwarf finishes a dig job. It will only dig out appropriate tiles that are adjacent to the finished dig job. To add a vein type, use `digFlood 1 [type]`. This will also enable the plugin. To remove a vein type, use `digFlood 0 [type] 1` to disable, then remove, then re-enable. - -`digFlood 0` disable - -`digFlood 1` enable - -`digFlood 0 MICROCLINE COAL_BITUMINOUS 1` disable plugin, remove microcline and bituminous coal from monitoring, then re-enable the plugin +Automatically digs out specified veins as they are discovered. It runs once +every time a dwarf finishes a dig job. It will only dig out appropriate tiles +that are adjacent to the finished dig job. To add a vein type, use ``digFlood 1 [type]``. +This will also enable the plugin. To remove a vein type, use ``digFlood 0 [type] 1`` +to disable, then remove, then re-enable. -`digFlood CLEAR` remove all inorganics from monitoring - -`digFlood digAll1` ignore the monitor list and dig any vein - -`digFlood digAll0` disable digAll mode +Usage: -See `help digFlood` for details. +:help digflood: detailed help message +:digFlood 0: disable the plugin +:digFlood 1: enable the plugin +:digFlood 0 MICROCLINE COAL_BITUMINOUS 1: + disable plugin, remove microcline and bituminous coal from monitoring, then re-enable the plugin +:digFlood CLEAR: remove all inorganics from monitoring +:digFlood digAll1: ignore the monitor list and dig any vein +:digFlood digAll0: disable digAll mode filltraffic ----------- @@ -897,19 +898,12 @@ Specifying both -t and -s will have no effect. If no plant IDs are specified, all valid plant IDs will be listed. - - - - - - - - - =========================== Job and Fortress management =========================== +.. _plugins/autolabor: + autolabor ========= Automatically manage dwarf labors to efficiently complete jobs. @@ -934,22 +928,25 @@ Anything beyond this is optional - autolabor works well on the default settings. Advanced usage: -:`autolabor []`: Set number of dwarves assigned to a labor. -:`autolabor haulers`: Set a labor to be handled by hauler dwarves. -:`autolabor disable`: Turn off autolabor for a specific labor. -:`autolabor reset`: Return a labor to the default handling. -:`autolabor reset-all`: Return all labors to the default handling. -:`autolabor list`: List current status of all labors. -:`autolabor status`: Show basic status information. -:`autolabor-artisans `: Run a command for labors where skill affects output quality +:autolabor []: + Set number of dwarves assigned to a labor. +:autolabor haulers: Set a labor to be handled by hauler dwarves. +:autolabor disable: Turn off autolabor for a specific labor. +:autolabor reset: Return a labor to the default handling. +:autolabor reset-all: Return all labors to the default handling. +:autolabor list: List current status of all labors. +:autolabor status: Show basic status information. + +See `scripts/autolabor-artisans` for a differently-tunde setup. -*Examples:* +Examples: -:`autolabor MINE 5`: Keep at least 5 dwarves with mining enabled. -:`autolabor CUT_GEM 1 1`: Keep exactly 1 dwarf with gemcutting enabled. -:`autolabor COOK 1 1 3`: Keep 1 dwarf with cooking enabled, selected only from the top 3. -:`autolabor FEED_WATER_CIVILIANS haulers`: Have haulers feed and water wounded dwarves. -:`autolabor CUTWOOD disable`: Turn off autolabor for wood cutting. +:autolabor MINE: Keep at least 5 dwarves with mining enabled. +:autolabor CUT_GEM 1 1: Keep exactly 1 dwarf with gemcutting enabled. +:autolabor COOK 1 1 3: Keep 1 dwarf with cooking enabled, selected only from the top 3. +:autolabor FEED_WATER_CIVILIANS haulers: + Have haulers feed and water wounded dwarves. +:autolabor CUTWOOD disable: Turn off autolabor for wood cutting. By default, each labor is assigned to between 1 and 200 dwarves (2-200 for mining). By default 33% of the workforce become haulers, who handle all hauling jobs as well @@ -977,6 +974,8 @@ We stop assigning dwarfs when we reach the maximum allowed. Job management ============== +.. _plugins/job: + job --- Command for general job query and manipulation. @@ -1046,6 +1045,8 @@ 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 -------- Manage control of repeat jobs. @@ -1077,7 +1078,6 @@ Usage: Function ~~~~~~~~ - When the plugin is enabled, it protects all repeat jobs from removal. If they do disappear due to any cause, they are immediately re-added to their workshop and suspended. @@ -1193,6 +1193,8 @@ 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 -------- This utility lets you quickly move all items designated to be dumped. @@ -1492,6 +1494,8 @@ Options: :sleep: Must be followed by number X. Changes the timer to sleep X frames between runs. +.. _plugins/autobutcher: + autobutcher ----------- Assigns lifestock for slaughter once it reaches a specific count. Requires that @@ -1785,6 +1789,8 @@ Options: :show X: Marks the selected map feature as discovered. :hide X: Marks the selected map feature as undiscovered. +.. _plugins/fortplan: + fortplan ======== Usage: fortplan [filename] @@ -2119,6 +2125,8 @@ structures in RAWs, modify the game engine behavior concerning the target objects to add features not otherwise present. +.. _plugins/siege-engine: + Siege Engine ------------ The siege-engine plugin enables siege engines to be linked to stockpiles, and @@ -2161,6 +2169,8 @@ 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 ----------- The power-meter plugin implements a modified pressure plate that detects power being diff --git a/docs/Scripts.rst b/docs/Scripts.rst index 329e30d2a..344095422 100644 --- a/docs/Scripts.rst +++ b/docs/Scripts.rst @@ -77,7 +77,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 ``tweak stable-temp`` and ``tweak fast-heat``. +state however, use `plugins/tweak` ``stable-temp`` and `plugins/tweak` ``fast-heat``. fix/stuckdoors ============== @@ -124,7 +124,7 @@ An example of player digging in adventure mode: gui/advfort_items ================= -Does something with items in advnedute mode jobs. +Does something with items in adventure mode jobs. gui/assign-rack =============== @@ -147,7 +147,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 the ``fix-armory`` plugin above is used. + unless `plugins/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 @@ -156,7 +156,7 @@ of currently assigned racks for every valid squad. gui/autobutcher =============== -An in-game interface for the ``autobutcher`` plugin. +An in-game interface for `plugins/autobutcher`. gui/choose-weapons ================== @@ -195,6 +195,8 @@ 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 =============== A graphical interface for creating items. @@ -238,7 +240,7 @@ computes it when the order is executed for the first time. gui/hack-wish ============= -An alias for ``gui/create-item``. Deprecated. +An alias for `scripts/gui/create-item`. Deprecated. gui/hello-world =============== @@ -300,7 +302,7 @@ Shows a warning at startup if no valid ``dfhack.init`` file is found. gui/power-meter =============== -An in-game interface for the ``power-meter`` plugin. +An in-game interface for `plugins/power-meter`. gui/rename ========== @@ -342,19 +344,21 @@ list, and allows unassigning them. gui/siege-engine ================ -An in-game interface for the ``siege-engine`` plugin. +An in-game interface for `plugins/siege-engine`. gui/stockpiles ============== -Load and save stockpile settings from the 'q' menu. -Usage:: +An in-game interface for `plugins/stocksettings`, to +load and save stockpile settings from the 'q' menu. + +Usage: - gui/stockpiles -save to save the current stockpile - gui/stockpiles -load to load settings into the current stockpile - gui/stockpiles -dir set the default directory to save settings into - gui/stockpiles -help to see this message +:gui/stockpiles -save: to save the current stockpile +:gui/stockpiles -load: to load settings into the current stockpile +:gui/stockpiles -dir : set the default directory to save settings into +:gui/stockpiles -help: to see this message -Don't forget to `enable stockpiles` and create the `stocksettings` directory in +Don't forget to ``enable stockpiles`` and create the ``stocksettings`` directory in the DF folder before trying to use this plugin. gui/unit-info-viewer @@ -387,8 +391,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 ``job item-material`` or ``gui/workshop-job``, -as described in ``workflow`` documentation above. In this manner, this feature +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 can be used for troubleshooting jobs that don't match the right constraints. .. image:: images/workflow-new1.png @@ -423,6 +427,8 @@ 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 ================ Bind to a key (the example config uses Alt-A), and activate with a job selected in @@ -431,7 +437,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 ``job item-type`` and ``job item-material`` commands. +them like the `plugins/job` ``item-type`` and `plugins/job` ``item-material`` commands. Specifically, pressing the 'i' key pops up a dialog that lets you select an item type from a list. @@ -621,14 +627,18 @@ Usage:: autofarm default 30 autofarm threshold 150 helmet_plump tail_pig +.. _scripts/autolabor-artisans: + autolabor-artisans ================== -Runs the ``autolabor`` plugin, with settings tuned for small but highly skilled workforces. +Runs `plugins/autolabor`, with settings tuned for small but highly skilled workforces. + +.. _scripts/autounsuspend: autounsuspend ============= Automatically unsuspend construction jobs, on a recurring basis. -See ``unsuspend`` for one-off use, or ``resume all``. +See `scripts/unsuspend` for one-off use, or `plugins/resume` ``all``. ban-cooking =========== @@ -863,7 +873,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 ``view-item-info``. +Used by `scripts/view-item-info`. lever ===== @@ -897,7 +907,10 @@ Examples:: log-region ========== -When enabled in dfhack.init, each time a fort is loaded identifying information will be written to the gamelog. Assists in parsing the file if you switch between forts, and adds information for story-building. +When enabled in dfhack.init, each time a fort is loaded identifying information +will be written to the gamelog. Assists in parsing the file if you switch +between forts, and adds information for story-building. + lua === There are the following ways to invoke this command: @@ -988,7 +1001,24 @@ normally used in seasonal auto-save. region-pops =========== -Show or modify the populations of animals in the region. Use ``region-pops`` for details. +Show or modify the populations of animals in the region. + +Usage: + +:region-pops list [pattern]: + Lists encountered populations of the region, possibly restricted by pattern. +:region-pops list-all [pattern]: + Lists all populations of the region. +:region-pops boost : + Multiply all populations of TOKEN by factor. + If the factor is greater than one, increases the + population, otherwise decreases it. +:region-pops boost-all : + Same as above, but match using a pattern acceptable to list. +:region-pops incr : + Augment (or diminish) all populations of TOKEN by factor (additive). +:region-pops incr-all : + Same as above, but match using a pattern acceptable to list. rejuvenate ========== @@ -1005,6 +1035,8 @@ remove-wear =========== Sets the wear on all items in your fort to zero. +.. _scripts/repeat: + repeat ====== Repeatedly calls a lua script at the specified interval. @@ -1034,8 +1066,22 @@ combat in slow motion or something :) show-unit-syndromes =================== Show syndromes affecting units and the remaining and maximum duration, along -with (optionally) substantial detail on the effects. Call -``show-unit-syndromes help`` for further options. +with (optionally) substantial detail on the effects. + +Use one or more of the following options: + +:showall: Show units even if not affected by any syndrome +:showeffects: Show detailed effects of each syndrome +:showdisplayeffects: Show effects that only change the look of the unit +:ignorehiddencurse: Hide syndromes the user should not be able to know about (TODO) +:selected: Show selected unit +:dwarves: Show dwarves +:livestock: Show livestock +:wildanimals: Show wild animals +:hostile: Show hostiles (e.g. invaders, thieves, forgotten beasts etc) +:world: Show all defined syndromes in the world +:export: ``export:`` sends output to the given file, showing all + syndromes affecting each unit with the maximum and present duration. siren ===== @@ -1071,12 +1117,12 @@ The number argument is the target liquid level (0 = drain, 7 = source). To add more than 1 unit everytime, call the command again on the same spot. -To delete one source, place the cursor over its tile and use ``delete``. +To delete one source, place the cursor over its tile and use ``source delete``. To remove all existing sources, call ``source clear``. The ``list`` argument shows all existing sources. -Ex:: +Examples:: source add water - water source source add magma 7 - magma source @@ -1092,7 +1138,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 ``autodump``. +a dwarf may come and actually dump it. See also `plugins/autodump`. With the ``items`` argument, only dumps items laying in the cage, excluding stuff worn by caged creatures. ``weapons`` will dump worn weapons, ``armor`` @@ -1135,10 +1181,14 @@ undump-buildings ================ Undesignates building base materials for dumping. +.. _scripts/unsuspend: + unsuspend ========= -Unsuspend construction jobs, on a one-off basis. See ``autounsuspend`` for regular use. -Equivalent to ``resume all``. +Unsuspend construction jobs, on a one-off basis. See `scripts/autounsuspend` for regular use. +Equivalent to `plugins/resume` ``all``. + +.. _scripts/view-item-info: view-item-info ============== @@ -1155,6 +1205,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 -``repeat`` command for regular checks. +`scripts/repeat` command for regular checks. Use ``warn-starving all`` to display a list of all problematic units. diff --git a/docs/conf.py.in b/docs/conf.py.in index d1ee2412f..58de900bb 100644 --- a/docs/conf.py.in +++ b/docs/conf.py.in @@ -91,7 +91,7 @@ exclude_patterns = ['docs/_build/*', 'depends/*'] # The reST default role (used for this markup: `text`) to use for all # documents. -#default_role = None +default_role = 'any' # If true, '()' will be appended to :func: etc. cross-reference text. #add_function_parentheses = True