reformat builtins and properly read tags

docs/Tags.rst

@@ -5,12 +5,19 @@ Tags
 
 This is the list of tags and their descriptions.
 
-- adventure: tools relevant to adventure mode
+- adventure: Tools relevant to adventure mode
-- fort: tools relevant to fort mode
+- fort: Tools relevant to fort mode
-- legends: tools relevant to legends mode
+- legends: Tools relevant to legends mode
-- enable: tools that are able to be enabled/disabled for some persistent effect
+- items: Tools that create or modify in-game items
-- items: tools that create or modify in-game items
+- units: Tools that create or modify units
-- units: tools that create or modify units
+- jobs: Tools that create or modify jobs
-- jobs: tools that create or modify jobs
+- labors: Tools that deal with labor assignment
-- labors: tools that deal with labor assignment
+- auto: Tools that automatically manage some aspect of your fortress
-- auto: tools that automatically manage some aspect of your fortress
+- map: Map modification
+- system: Tools related to working with DFHack commands or the core DFHack library
+- productivity: Tools that help you do things that you could do manually, but using the tool is better and faster
+- animals: Tools that help you manage animals
+- fix: Tools that fix specific bugs
+- inspection: Tools that let you inspect game data
+- buildings/furniture: Tools that help you work wtih placing or configuring buildings and furniture
+- quickfort: Tools that are involved in creating and playing back blueprints

docs/builtins/alias.rst

@@ -1,5 +1,8 @@
 alias
------
+=====
+
+Tags: system
+:dfhack-keybind:`alias`
 
 Configure helper aliases for other DFHack commands. Aliases are resolved
 immediately after built-in commands, which means that an alias cannot override
@@ -21,7 +24,10 @@ Usage:
 Aliases can be given additional arguments when created and invoked, which will
 be passed to the underlying command in order.
 
-Example::
+Example
+-------
+
+::
 
     [DFHack]# alias add pargs devel/print-args example
     [DFHack]# pargs text

docs/builtins/clear.rst

@@ -1,4 +1,7 @@
 clear
------
+=====
+
+Tags: system
+:dfhack-keybind:`clear`
 
 Clear the terminal screen. This command is an alias for `cls`.

docs/builtins/cls.rst

@@ -1,5 +1,8 @@
 cls
----
+===
 
-Clear the terminal screen. Can also be invoked as ``clear``. Note that this
+Tags: system
+:dfhack-keybind:`cls`
+
+Clear the terminal screen. Can also be invoked as `clear`. Note that this
 command does not delete command history. It just clears the text on the screen.

docs/builtins/devel/dump-rpc.rst

@@ -1,5 +1,8 @@
 devel/dump-rpc
---------------
+==============
+
+Tags: system
+:dfhack-keybind:`devel/dump-rpc`
 
 Writes RPC endpoint information to the specified file.
 

docs/builtins/die.rst

@@ -1,4 +1,7 @@
 die
----
+===
+
+Tags: system
+:dfhack-keybind:`die`
 
 Instantly exits DF without saving.

docs/builtins/dir.rst

@@ -1,4 +1,7 @@
 dir
----
+===
+
+Tags: system
+:dfhack-keybind:`dir`
 
 List available DFHack commands. This is an alias of the `ls` command.

docs/builtins/disable.rst

@@ -1,20 +1,12 @@
 disable
--------
+=======
 
-Deactivate a DFHack tool that has some persistent effect. Many plugins and
+Tags: system
-scripts can be in a distinct enabled or disabled state. Some of them activate
+:dfhack-keybind:`disable`
-and deactivate automatically depending on the contents of the world raws. Others
-store their state in world data. However a number of them have to be enabled
-globally, and the init file is the right place to do it.
 
-Most such plugins or scripts support the built-in ``enable`` and ``disable``
+Deactivate a DFHack tool that has some persistent effect. See the `enable`
-commands. Calling them at any time without arguments prints a list of enabled
+command for more info.
-and disabled plugins, and shows whether that can be changed through the same
-commands. Passing plugin names to these commands will enable or disable the
-specified plugins. For example, to disable the `manipulator` plugin::
 
-    disable manipulator
+Usage::
 
-It is also possible to enable or disable multiple plugins at once::
+    disable <plugin> [<plugin> ...]
-
-    disable manipulator search

docs/builtins/enable.rst

@@ -1,5 +1,8 @@
 enable
-------
+======
+
+Tags: system
+:dfhack-keybind:`enable`
 
 Activate a DFHack tool that has some persistent effect. Many plugins and scripts
 can be in a distinct enabled or disabled state. Some of them activate and
@@ -7,14 +10,21 @@ deactivate automatically depending on the contents of the world raws. Others
 store their state in world data. However a number of them have to be enabled
 globally, and the init file is the right place to do it.
 
-Most such plugins or scripts support the built-in ``enable`` and ``disable``
+Most such plugins or scripts support the built-in ``enable`` and `disable`
 commands. Calling them at any time without arguments prints a list of enabled
 and disabled plugins, and shows whether that can be changed through the same
 commands. Passing plugin names to these commands will enable or disable the
-specified plugins. For example, to enable the `manipulator` plugin::
+specified plugins.
+
+Usage::
 
-    enable manipulator
+    enable
+    enable <plugin> [<plugin> ...]
 
-It is also possible to enable or disable multiple plugins at once::
+Examples
+--------
 
-    enable manipulator search
+- ``enable manipulator``
+    Enable the ``manipulator`` plugin.
+- ``enable manipulator search``
+    Enable multiple plugins at once.

docs/builtins/fpause.rst

@@ -1,5 +1,12 @@
 fpause
-------
+======
+
+Tags: system
+:dfhack-keybind:`fpause`
 
 Forces DF to pause. This is useful when your FPS drops below 1 and you lose
 control of the game.
+
+Usage::
+
+    fpause

docs/builtins/help.rst

@@ -1,5 +1,8 @@
 help
-----
+====
+
+Tags: system
+:dfhack-keybind:`help`
 
 Display help about a command or plugin.
 
@@ -8,7 +11,10 @@ Usage::
     help|?|man
     help|?|man <command or plugin>
 
-Examples::
+Examples
+--------
+
+::
 
     help blueprint
     man blueprint
@@ -16,4 +22,4 @@ Examples::
 Both examples above will display the help text for the `blueprint` command.
 
 Some commands also take ``help`` or ``?`` as an option on their command line
-for the same effect - e.g. ``blueprint help``.
+for the same effect -- e.g. ``blueprint help``.

docs/builtins/hide.rst

@@ -1,8 +1,15 @@
 hide
-----
+====
+
+Tags: system
+:dfhack-keybind:`hide`
 
 Hides the DFHack terminal window. You can show it again with the `show`
 command, though you'll need to use it from a `keybinding` set beforehand or the
 in-game `command-prompt`.
 
 Only available on Windows.
+
+Usage::
+
+    hide

docs/builtins/keybinding.rst

@@ -1,5 +1,8 @@
 keybinding
-----------
+==========
+
+Tags: system
+:dfhack-keybind:`keybinding`
 
 Create hotkeys that will run DFHack commands. Like any other command it can be
 used at any time from the console, but bindings are not remembered between runs
@@ -46,7 +49,8 @@ example, ``@foo|bar|baz/foo`` would match anything under ``@foo``, ``@bar``, or
 
 Interactive commands like `liquids` cannot be used as hotkeys.
 
-Examples:
+Examples
+--------
 
 - ``keybinding add Alt-F1 hotkeys``
     Bind Alt-F1 to run the `hotkeys` command on any screen at any time.

docs/builtins/kill-lua.rst

@@ -1,6 +1,15 @@
 kill-lua
---------
+========
+
+Tags: system
+:dfhack-keybind:`kill-lua`
 
 Gracefully stops any currently-running Lua scripts. Use this command to stop
-a misbehaving script that appears to be stuck. Use ``kill-lua force`` if just
+a misbehaving script that appears to be stuck.
-``kill-lua`` doesn't work.
+
+Usage::
+
+    kill-lua
+    kill-lua force
+
+Use ``kill-lua force`` if just ``kill-lua`` doesn't seem to work.

docs/builtins/load.rst

@@ -1,5 +1,8 @@
 load
-----
+====
+
+Tags: system
+:dfhack-keybind:`load`
 
 Load and register a plugin library. Also see `unload` and `reload` for related
 actions.

docs/builtins/ls.rst

@@ -1,5 +1,8 @@
 ls
---
+==
+
+Tags: system
+:dfhack-keybind:`ls`
 
 List available DFHack commands. In order to group related commands, each command
 is associated with a list of tags. You can filter the listed commands by a tag
@@ -25,7 +28,8 @@ You can also pass some optional parameters to change how ``ls`` behaves:
 - ``--dev``
     Include commands intended for developers and modders.
 
-Examples:
+Examples
+--------
 
 - ``ls adventure``
     Lists all commands with the ``adventure`` tag.

docs/builtins/man.rst

@@ -0,0 +1,7 @@
+man
+===
+
+Tags: system
+:dfhack-keybind:`man`
+
+An alias for the `help` command.

docs/builtins/plug.rst

@@ -1,5 +1,8 @@
 plug
-----
+====
+
+Tags: system
+:dfhack-keybind:`plug`
 
 Lists available plugins and whether they are enabled.
 

docs/builtins/reload.rst

@@ -1,5 +1,8 @@
 reload
-------
+======
+
+Tags: system
+:dfhack-keybind:`reload`
 
 Reload a loaded plugin. Developer use this command to reload a plugin that they
 are actively modifying. Also see `load` and `unload` for related actions.

docs/builtins/sc-script.rst

@@ -1,5 +1,8 @@
 sc-script
----------
+=========
+
+Tags: system
+:dfhack-keybind:`sc-script`
 
 Runs commands when game state changes occur. This is similar to the static
 `init-files` but is slightly more flexible since it can be set dynamically.
@@ -13,7 +16,8 @@ Usage:
 - ``sc-script add|remove <event> <file> [<file> ...]``
     Register or unregister a file to be run for the specified event.
 
-Examples:
+Examples
+--------
 
 - ``sc-script add SC_MAP_LOADED spawn_extra_monsters.init``
     Registers the ``spawn_extra_monsters.init`` file to be run whenever a new

docs/builtins/script.rst

@@ -1,5 +1,8 @@
 script
-------
+======
+
+Tags: system
+:dfhack-keybind:`script`
 
 Executes a batch file of DFHack commands. It reads a text file and runs each
 line as a DFHack command as if it had been typed in by the user - treating the
@@ -12,7 +15,8 @@ Usage::
 
     script <filename>
 
-Examples:
+Examples
+--------
 
 - ``script startup.txt``
     Executes the commands in ``startup.txt``, which exists in your DF game

docs/builtins/show.rst

@@ -1,5 +1,8 @@
 show
-----
+====
+
+Tags: system
+:dfhack-keybind:`show`
 
 Unhides the DFHack terminal window. Useful if you have hidden the terminal with
 `hide` and you want it back. Since the terminal window won't be available to run
@@ -7,3 +10,7 @@ this command, you'll need to use it from a `keybinding` set beforehand or the
 in-game `command-prompt`.
 
 Only available on Windows.
+
+Usage::
+
+    show

docs/builtins/tags.rst

@@ -1,5 +1,8 @@
 tags
-----
+====
+
+Tags: system
+:dfhack-keybind:`tags`
 
 List the strings that DFHack tools can be tagged with. You can find groups of
 related tools by passing the tag name to the `ls` command.

docs/builtins/type.rst

@@ -1,5 +1,8 @@
 type
-----
+====
+
+Tags: system
+:dfhack-keybind:`type`
 
 Describes how a command is implemented. DFHack commands can be provided by
 plugins, scripts, or by the core library itself. The ``type`` command can tell

docs/builtins/unload.rst

@@ -1,5 +1,8 @@
 unload
-------
+======
+
+Tags: system
+:dfhack-keybind:`unload`
 
 Unload a plugin from memory. Also see `load` and `reload` for related actions.
 

library/lua/helpdb.lua

@@ -268,7 +268,7 @@ local function update_db(old_db, db, source, entry_name, kwargs)
         error('unhandled help source: ' .. source)
     end
     db[entry_name] = entry
-    for _,tag in ipairs(entry.tags) do
+    for tag in pairs(entry.tags) do
         -- ignore unknown tags
         if tag_index[tag] then
             table.insert(tag_index[tag], entry_name)