Merge pull request #2247 from DFHack/docs

Doc system and tool help overhaul

.github/workflows/build.yml

@@ -129,14 +129,14 @@ jobs:
         python-version: 3
     - name: Install dependencies
       run: |
-        pip install 'sphinx<4.4.0'
+        pip install 'sphinx'
     - name: Clone DFHack
       uses: actions/checkout@v1
       with:
         submodules: true
     - name: Build docs
       run: |
-        sphinx-build -W --keep-going -j3 --color . docs/html
+        sphinx-build -W --keep-going -j auto --color . docs/html
     - name: Upload docs
       uses: actions/upload-artifact@v1
       with:

.gitignore

@@ -15,9 +15,14 @@ build/VC2010
 !build/
 
 # Sphinx generated documentation
-docs/_*
+docs/changelogs/
 docs/html/
 docs/pdf/
+docs/pseudoxml/
+docs/tags/
+docs/text/
+docs/tools/
+docs/xml/
 
 # in-place build
 build/Makefile

CMakeLists.txt

@@ -1,7 +1,7 @@
 # main project file. use it from a build sub-folder, see COMPILE for details
 
 ## some generic CMake magic
-cmake_minimum_required(VERSION 2.8.12 FATAL_ERROR)
+cmake_minimum_required(VERSION 3.6 FATAL_ERROR)
 cmake_policy(SET CMP0048 NEW)
 project(dfhack)
 
@@ -442,43 +442,67 @@ endif()
 add_subdirectory(data)
 add_subdirectory(scripts)
 
-find_package(Sphinx QUIET)
 if(BUILD_DOCS)
+    find_package(Python3)
+    find_package(Sphinx)
+
     if(NOT SPHINX_FOUND)
         message(SEND_ERROR "Sphinx not found but BUILD_DOCS enabled")
     endif()
 
-    file(GLOB SPHINX_DEPS
+    file(GLOB SPHINX_GLOB_DEPS
-        "${CMAKE_CURRENT_SOURCE_DIR}/docs/*.rst"
+        LIST_DIRECTORIES false
-        "${CMAKE_CURRENT_SOURCE_DIR}/docs/guides/*.rst"
-        "${CMAKE_CURRENT_SOURCE_DIR}/docs/changelog.txt"
-        "${CMAKE_CURRENT_SOURCE_DIR}/docs/gen_changelog.py"
         "${CMAKE_CURRENT_SOURCE_DIR}/docs/images/*.png"
         "${CMAKE_CURRENT_SOURCE_DIR}/docs/styles/*"
-        "${CMAKE_CURRENT_SOURCE_DIR}/conf.py"
+        "${CMAKE_CURRENT_SOURCE_DIR}/data/init/*init"
-        "${CMAKE_CURRENT_SOURCE_DIR}/scripts/about.txt"
+    )
-        "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*/about.txt"
+    file(GLOB_RECURSE SPHINX_GLOB_RECURSE_DEPS
+        "${CMAKE_CURRENT_SOURCE_DIR}/*.rst"
+        "${CMAKE_CURRENT_SOURCE_DIR}/changelog.txt"
+        "${CMAKE_CURRENT_SOURCE_DIR}/docs/*py"
+    )
+    list(FILTER SPHINX_GLOB_RECURSE_DEPS
+        EXCLUDE REGEX "docs/changelogs"
+    )
+    list(FILTER SPHINX_GLOB_RECURSE_DEPS
+        EXCLUDE REGEX "docs/html"
+    )
+    list(FILTER SPHINX_GLOB_RECURSE_DEPS
+        EXCLUDE REGEX "docs/tags"
     )
-    file(GLOB_RECURSE SPHINX_SCRIPT_DEPS
+    list(FILTER SPHINX_GLOB_RECURSE_DEPS
-        "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*.lua"
+        EXCLUDE REGEX "docs/text"
-        "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*.rb"
     )
-    set(SPHINX_DEPS ${SPHINX_DEPS} ${SPHINX_SCRIPT_DEPS}
+    list(FILTER SPHINX_GLOB_RECURSE_DEPS
-        "${CMAKE_CURRENT_SOURCE_DIR}/LICENSE.rst"
+        EXCLUDE REGEX "docs/tools"
+    )
+    set(SPHINX_DEPS ${SPHINX_GLOB_DEPS} ${SPHINX_GLOB_RECURSE_DEPS} ${SPHINX_SCRIPT_DEPS}
         "${CMAKE_CURRENT_SOURCE_DIR}/CMakeLists.txt"
+        "${CMAKE_CURRENT_SOURCE_DIR}/conf.py"
     )
 
     set(SPHINX_OUTPUT "${CMAKE_CURRENT_SOURCE_DIR}/docs/html/.buildinfo")
-    set_source_files_properties(${SPHINX_OUTPUT} PROPERTIES GENERATED TRUE)
+    set_property(
-    add_custom_command(OUTPUT ${SPHINX_OUTPUT}
+        DIRECTORY PROPERTY ADDITIONAL_CLEAN_FILES TRUE
-        COMMAND ${SPHINX_EXECUTABLE}
+        "${CMAKE_CURRENT_SOURCE_DIR}/docs/changelogs"
-            -a -E -q -b html
-            "${CMAKE_CURRENT_SOURCE_DIR}"
         "${CMAKE_CURRENT_SOURCE_DIR}/docs/html"
-            -w "${CMAKE_CURRENT_SOURCE_DIR}/docs/_sphinx-warnings.txt"
+        "${CMAKE_CURRENT_SOURCE_DIR}/docs/pdf"
-            -j 2
+        "${CMAKE_CURRENT_SOURCE_DIR}/docs/pseudoxml"
+        "${CMAKE_CURRENT_SOURCE_DIR}/docs/tags"
+        "${CMAKE_CURRENT_SOURCE_DIR}/docs/text"
+        "${CMAKE_CURRENT_SOURCE_DIR}/docs/tools"
+        "${CMAKE_CURRENT_SOURCE_DIR}/docs/xml"
+        "${CMAKE_BINARY_DIR}/docs/html"
+        "${CMAKE_BINARY_DIR}/docs/pdf"
+        "${CMAKE_BINARY_DIR}/docs/pseudoxml"
+        "${CMAKE_BINARY_DIR}/docs/text"
+        "${CMAKE_BINARY_DIR}/docs/xml"
+    )
+    add_custom_command(OUTPUT ${SPHINX_OUTPUT}
+        COMMAND "${Python3_EXECUTABLE}" "${CMAKE_CURRENT_SOURCE_DIR}/docs/build.py"
+            html text --sphinx="${SPHINX_EXECUTABLE}" -- -q
         DEPENDS ${SPHINX_DEPS}
-        COMMENT "Building HTML documentation with Sphinx"
+        COMMENT "Building documentation with Sphinx"
     )
 
     add_custom_target(dfhack_docs ALL
@@ -490,8 +514,12 @@ if(BUILD_DOCS)
         COMMAND ${CMAKE_COMMAND} -E touch ${SPHINX_OUTPUT})
 
     install(DIRECTORY ${dfhack_SOURCE_DIR}/docs/html/
+        DESTINATION ${DFHACK_USERDOC_DESTINATION}/docs
+        FILES_MATCHING PATTERN "*"
+                       PATTERN html/_sources EXCLUDE)
+    install(DIRECTORY ${dfhack_SOURCE_DIR}/docs/text/
         DESTINATION ${DFHACK_USERDOC_DESTINATION}/docs)
-    install(FILES docs/_auto/news.rst docs/_auto/news-dev.rst DESTINATION ${DFHACK_USERDOC_DESTINATION})
+    install(FILES docs/changelogs/news.rst docs/changelogs/news-dev.rst DESTINATION ${DFHACK_USERDOC_DESTINATION})
     install(FILES "README.html" DESTINATION "${DFHACK_DATA_DESTINATION}")
 endif()
 

conf.py

@@ -15,186 +15,128 @@ serve to show the default.
 # pylint:disable=redefined-builtin
 
 import datetime
-from io import open
 import os
 import re
 import shlex  # pylint:disable=unused-import
 import sphinx
 import sys
 
+sys.path.append(os.path.join(os.path.abspath(os.path.dirname(__file__)), 'docs', 'sphinx_extensions'))
+from dfhack.util import write_file_if_changed
 
-# -- Support :dfhack-keybind:`command` ------------------------------------
+if os.environ.get('DFHACK_DOCS_BUILD_OFFLINE'):
-# this is a custom directive that pulls info from default keybindings
+    # block attempted image downloads, particularly for the PDF builder
+    def request_disabled(*args, **kwargs):
+        raise RuntimeError('Offline build - network request blocked')
 
-from docutils import nodes
+    import urllib3.util
-from docutils.parsers.rst import roles
+    urllib3.util.create_connection = request_disabled
 
-sphinx_major_version = sphinx.version_info[0]
+    import urllib3.connection
+    urllib3.connection.HTTPConnection.connect = request_disabled
 
-def get_keybinds(root, files, keybindings):
+    import requests
-    """Add keybindings in the specified files to the
+    requests.request = request_disabled
-    given keybindings dict.
+    requests.get = request_disabled
-    """
+
-    for file in files:
+
-        with open(os.path.join(root, file)) as f:
+# -- Autodoc for DFhack plugins and scripts -------------------------------
-            lines = [l.replace('keybinding add', '').strip() for l in f.readlines()
+
-                     if l.startswith('keybinding add')]
+def doc_dir(dirname, files, prefix):
-        for k in lines:
+    """Yield (name, includepath) for each file in the directory."""
-            first, command = k.split(' ', 1)
-            bind, context = (first.split('@') + [''])[:2]
-            if ' ' not in command:
-                command = command.replace('"', '')
-            tool = command.split(' ')[0].replace('"', '')
-            keybindings[tool] = keybindings.get(tool, []) + [
-                (command, bind.split('-'), context)]
-
-def get_all_keybinds(root_dir):
-    """Get the implemented keybinds, and return a dict of
-    {tool: [(full_command, keybinding, context), ...]}.
-    """
-    keybindings = dict()
-    for root, _, files in os.walk(root_dir):
-        get_keybinds(root, files, keybindings)
-    return keybindings
-
-KEYBINDS = get_all_keybinds('data/init')
-
-
-# pylint:disable=unused-argument,dangerous-default-value,too-many-arguments
-def dfhack_keybind_role_func(role, rawtext, text, lineno, inliner,
-                             options={}, content=[]):
-    """Custom role parser for DFHack default keybinds."""
-    roles.set_classes(options)
-    if text not in KEYBINDS:
-        msg = inliner.reporter.error(
-            'no keybinding for {} in dfhack.init-example'.format(text),
-            line=lineno)
-        prb = inliner.problematic(rawtext, rawtext, msg)
-        return [prb], [msg]
-    newnode = nodes.paragraph()
-    for cmd, key, ctx in KEYBINDS[text]:
-        n = nodes.paragraph()
-        newnode += n
-        n += nodes.strong('Keybinding: ', 'Keybinding: ')
-        for k in key:
-            n += nodes.inline(k, k, classes=['kbd'])
-        if cmd != text:
-            n += nodes.inline(' -> ', ' -> ')
-            n += nodes.literal(cmd, cmd, classes=['guilabel'])
-        if ctx:
-            n += nodes.inline(' in ', ' in ')
-            n += nodes.literal(ctx, ctx)
-    return [newnode], []
-
-
-roles.register_canonical_role('dfhack-keybind', dfhack_keybind_role_func)
-
-# -- Autodoc for DFhack scripts -------------------------------------------
-
-def doc_dir(dirname, files):
-    """Yield (command, includepath) for each script in the directory."""
     sdir = os.path.relpath(dirname, '.').replace('\\', '/').replace('../', '')
+    if prefix == '.':
+        prefix = ''
+    else:
+        prefix += '/'
     for f in files:
-        if f[-3:] not in ('lua', '.rb'):
+        if f[-4:] != '.rst':
             continue
-        with open(os.path.join(dirname, f), 'r', encoding='utf8') as fstream:
+        yield prefix + f[:-4], sdir + '/' + f
-            text = [l.rstrip() for l in fstream.readlines() if l.strip()]
-        # Some legacy lua files use the ruby tokens (in 3rdparty scripts)
-        tokens = ('=begin', '=end')
-        if f[-4:] == '.lua' and any('[====[' in line for line in text):
-            tokens = ('[====[', ']====]')
-        command = None
-        for line in text:
-            if command and line == len(line) * '=':
-                yield command, sdir + '/' + f, tokens[0], tokens[1]
-                break
-            command = line
 
 
 def doc_all_dirs():
     """Collect the commands and paths to include in our docs."""
-    scripts = []
+    tools = []
-    for root, _, files in os.walk('scripts'):
+    # TODO: as we scan the docs, parse out the tags and short descriptions and
-        scripts.extend(doc_dir(root, files))
+    # build a map for use in generating the tags pages and links in the tool
-    return tuple(scripts)
+    # doc footers
+    for root, _, files in os.walk('docs/builtins'):
+        tools.extend(doc_dir(root, files, os.path.relpath(root, 'docs/builtins')))
+    for root, _, files in os.walk('docs/plugins'):
+        tools.extend(doc_dir(root, files, os.path.relpath(root, 'docs/plugins')))
+    for root, _, files in os.walk('scripts/docs'):
+        tools.extend(doc_dir(root, files, os.path.relpath(root, 'scripts/docs')))
+    return tuple(tools)
 
 DOC_ALL_DIRS = doc_all_dirs()
 
 
-def document_scripts():
+def get_tags():
-    """Autodoc for files with the magic script documentation marker strings.
+    groups = {}
-
+    group_re = re.compile(r'"([^"]+)"')
-    Returns a dict of script-kinds to lists of .rst include directives.
+    tag_re = re.compile(r'- `tag/([^`]+)`: (.*)')
-    """
+    with open('docs/Tags.rst') as f:
-    # Next we split by type and create include directives sorted by command
+        lines = f.readlines()
-    kinds = {'base': [], 'devel': [], 'fix': [], 'gui': [], 'modtools': []}
+        for line in lines:
-    for s in DOC_ALL_DIRS:
+            line = line.strip()
-        k_fname = s[0].split('/', 1)
+            m = re.match(group_re, line)
-        if len(k_fname) == 1:
+            if m:
-            kinds['base'].append(s)
+                group = m.group(1)
-        else:
+                groups[group] = []
-            kinds[k_fname[0]].append(s)
+                continue
-
+            m = re.match(tag_re, line)
-    def template(arg):
+            if m:
-        tmp = '.. _{}:\n\n.. include:: /{}\n' +\
+                tag = m.group(1)
-            '   :start-after: {}\n   :end-before: {}\n'
+                desc = m.group(2)
-        if arg[0] in KEYBINDS:
+                groups[group].append((tag, desc))
-            tmp += '\n:dfhack-keybind:`{}`\n'.format(arg[0])
+    return groups
-        return tmp.format(*arg)
+
-
+
-    return {key: '\n\n'.join(map(template, sorted(value)))
+def generate_tag_indices():
-            for key, value in kinds.items()}
+    os.makedirs('docs/tags', mode=0o755, exist_ok=True)
-
+    tag_groups = get_tags()
-
+    for tag_group in tag_groups:
-def write_script_docs():
+        with write_file_if_changed(('docs/tags/by{group}.rst').format(group=tag_group)) as topidx:
+            for tag_tuple in tag_groups[tag_group]:
+                tag = tag_tuple[0]
+                with write_file_if_changed(('docs/tags/{name}.rst').format(name=tag)) as tagidx:
+                    tagidx.write('TODO: add links to the tools that have this tag')
+                topidx.write(('.. _tag/{name}:\n\n').format(name=tag))
+                topidx.write(('{name}\n').format(name=tag))
+                topidx.write(('{underline}\n').format(underline='*'*len(tag)))
+                topidx.write(('{desc}\n\n').format(desc=tag_tuple[1]))
+                topidx.write(('.. include:: /docs/tags/{name}.rst\n\n').format(name=tag))
+
+
+def write_tool_docs():
     """
-    Creates a file for eack kind of script (base/devel/fix/gui/modtools)
+    Creates a file for each tool with the ".. include::" directives to pull in
-    with all the ".. include::" directives to pull out docs between the
+    the original documentation. Then we generate a label and useful info in the
-    magic strings.
+    footer.
     """
-    kinds = document_scripts()
+    for k in DOC_ALL_DIRS:
-    head = {
+        header = ':orphan:\n'
-        'base': 'Basic Scripts',
+        label = ('.. _{name}:\n\n').format(name=k[0])
-        'devel': 'Development Scripts',
+        include = ('.. include:: /{path}\n\n').format(path=k[1])
-        'fix': 'Bugfixing Scripts',
+        # TODO: generate a footer with links to tools that share at least one
-        'gui': 'GUI Scripts',
+        # tag with this tool. Just the tool names, strung across the bottom of
-        'modtools': 'Scripts for Modders'}
+        # the page in one long wrapped line, similar to how the wiki does it
-    for k in head:
+        os.makedirs(os.path.join('docs/tools', os.path.dirname(k[0])),
-        title = ('.. _scripts-{k}:\n\n{l}\n{t}\n{l}\n\n'
+                    mode=0o755, exist_ok=True)
-                 '.. include:: /scripts/{a}about.txt\n\n'
+        with write_file_if_changed('docs/tools/{}.rst'.format(k[0])) as outfile:
-                 '.. contents:: Contents\n'
+            outfile.write(header)
-                 '  :local:\n\n').format(
+            if k[0] != 'search':
-                     k=k, t=head[k],
+                outfile.write(label)
-                     l=len(head[k])*'#',
+            outfile.write(include)
-                     a=('' if k == 'base' else k + '/')
-                     )
-        mode = 'w' if sys.version_info.major > 2 else 'wb'
-        with open('docs/_auto/{}.rst'.format(k), mode) as outfile:
-            outfile.write(title)
-            outfile.write(kinds[k])
-
-
-def all_keybinds_documented():
-    """Check that all keybindings are documented with the :dfhack-keybind:
-    directive somewhere."""
-    configured_binds = set(KEYBINDS)
-    script_commands = set(i[0] for i in DOC_ALL_DIRS)
-    with open('./docs/Plugins.rst') as f:
-        plugin_binds = set(re.findall(':dfhack-keybind:`(.*?)`', f.read()))
-    undocumented_binds = configured_binds - script_commands - plugin_binds
-    if undocumented_binds:
-        raise ValueError('The following DFHack commands have undocumented '
-                         'keybindings: {}'.format(sorted(undocumented_binds)))
 
 
 # Actually call the docs generator and run test
-write_script_docs()
+write_tool_docs()
-all_keybinds_documented()
+generate_tag_indices()
 
 # -- General configuration ------------------------------------------------
 
-sys.path.append(os.path.join(os.path.abspath(os.path.dirname(__file__)), 'docs', 'sphinx_extensions'))
-
 # If your documentation needs a minimal Sphinx version, state it here.
 needs_sphinx = '1.8'
 
@@ -205,8 +147,11 @@ extensions = [
     'sphinx.ext.extlinks',
     'dfhack.changelog',
     'dfhack.lexer',
+    'dfhack.tool_docs',
 ]
 
+sphinx_major_version = sphinx.version_info[0]
+
 def get_caption_str(prefix=''):
     return prefix + (sphinx_major_version >= 5 and '%s' or '')
 
@@ -286,12 +231,18 @@ today_fmt = html_last_updated_fmt = '%Y-%m-%d'
 # directories to ignore when looking for source files.
 exclude_patterns = [
     'README.md',
-    'docs/html*',
-    'depends/*',
     'build*',
-    'docs/_auto/news*',
+    'depends/*',
-    'docs/_changelogs/',
+    'docs/html/*',
+    'docs/tags/*',
+    'docs/text/*',
+    'docs/builtins/*',
+    'docs/pdf/*',
+    'docs/plugins/*',
+    'docs/pseudoxml/*',
+    'docs/xml/*',
     'scripts/docs/*',
+    'plugins/*',
     ]
 
 # The reST default role (used for this markup: `text`) to use for all
@@ -367,8 +318,11 @@ html_sidebars = {
 # If false, no module index is generated.
 html_domain_indices = False
 
-# If false, no index is generated.
+# If false, no genindex.html is generated.
-html_use_index = False
+html_use_index = True
+
+# don't link to rst sources in the generated pages
+html_show_sourcelink = False
 
 html_css_files = [
     'dfhack.css',
@@ -388,3 +342,11 @@ latex_documents = [
 ]
 
 latex_toplevel_sectioning = 'part'
+
+# -- Options for text output ---------------------------------------------
+
+from sphinx.writers import text
+
+text.MAXWIDTH = 52
+
+text_sectionchars = '=-~`+"*'

docs/Core.rst

@@ -11,8 +11,7 @@ DFHack Core
 
 Command Implementation
 ======================
-DFHack commands can be implemented in three ways, all of which
+DFHack commands can be implemented in any of three ways:
-are used in the same way:
 
 :builtin:   commands are implemented by the core of DFHack. They manage
             other DFHack tools, interpret commands, and control basic
@@ -27,6 +26,7 @@ are used in the same way:
             more flexible about versions, and easier to distribute.
             Most third-party DFHack addons are scripts.
 
+All tools distributed with DFHack are documented `here <genindex>`.
 
 Using DFHack Commands
 =====================
@@ -113,260 +113,6 @@ second (Windows) example uses `kill-lua` to stop a Lua script.
   you have multiple copies of DF running simultaneously. To assign a different
   port, see `remote-server-config`.
 
-
-Built-in Commands
-=================
-The following commands are provided by the 'core' components
-of DFHack, rather than plugins or scripts.
-
-.. contents::
-   :local:
-
-
-.. _alias:
-
-alias
------
-The ``alias`` command allows configuring aliases to other DFHack commands.
-Aliases are resolved immediately after built-in commands, which means that an
-alias cannot override a built-in command, but can override a command implemented
-by a plugin or script.
-
-Usage:
-
-:``alias list``: lists all configured aliases
-:``alias add <name> <command> [arguments...]``: adds an alias
-:``alias replace <name> <command> [arguments...]``: replaces an existing
-    alias with a new command, or adds the alias if it does not already exist
-:``alias delete <name>``: removes the specified alias
-
-Aliases can be given additional arguments when created and invoked, which will
-be passed to the underlying command in order. An example with `devel/print-args`::
-
-    [DFHack]# alias add pargs devel/print-args example
-    [DFHack]# pargs text
-    example
-    text
-
-
-.. _cls:
-
-cls
----
-Clear the terminal.  Does not delete command history.
-
-
-.. _die:
-
-die
----
-Instantly kills DF without saving.
-
-
-.. _disable:
-
-.. _enable:
-
-enable
-------
-Many plugins can be in a distinct enabled or disabled state. Some of
-them activate 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``
-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::
-
-  enable manipulator
-
-It is also possible to enable or disable multiple plugins at once::
-
-  enable manipulator search
-
-
-.. _fpause:
-
-fpause
-------
-Forces DF to pause. This is useful when your FPS drops below 1 and you lose
-control of the game.
-
-
-.. _help:
-
-help
-----
-Most commands support using the ``help <command>`` built-in command
-to retrieve further help without having to look at this document.
-``? <cmd>`` and ``man <cmd>`` are aliases.
-
-Some commands (including many scripts) instead take ``help`` or ``?``
-as an option on their command line - ie ``<cmd> help``.
-
-
-.. _hide:
-
-hide
-----
-Hides the DFHack terminal window.  Only available on Windows.
-
-
-.. _keybinding:
-
-keybinding
-----------
-To set keybindings, use the built-in ``keybinding`` command. Like any other
-command it can be used at any time from the console, but bindings are not
-remembered between runs of the game unless re-created in `dfhack.init`.
-
-Currently, any combinations of Ctrl/Alt/Shift with A-Z, 0-9, F1-F12 or \`
-are supported.
-
-Possible ways to call the command:
-
-``keybinding list <key>``
-  List bindings active for the key combination.
-``keybinding clear <key> <key>...``
-  Remove bindings for the specified keys.
-``keybinding add <key> "cmdline" "cmdline"...``
-  Add bindings for the specified key.
-``keybinding set <key> "cmdline" "cmdline"...``
-  Clear, and then add bindings for the specified key.
-
-The ``<key>`` parameter above has the following *case-sensitive* syntax::
-
-    [Ctrl-][Alt-][Shift-]KEY[@context[|context...]]
-
-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
-the first applicable one. Later ``add`` commands, and earlier entries within one
-``add`` command have priority. Commands that are not specifically intended for use
-as a hotkey are always considered applicable.
-
-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 ``keybinding`` command among other things prints the current context string.
-
-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.
-when in context ``foo/bar/baz``, keybindings restricted to any of ``@foo/bar/baz``,
-``@foo/bar``, ``@foo`` or none will be active.
-
-Multiple contexts can be specified by separating them with a
-pipe (``|``) - for example, ``@foo|bar|baz/foo`` would match
-anything under ``@foo``, ``@bar``, or ``@baz/foo``.
-
-Interactive commands like `liquids` cannot be used as hotkeys.
-
-
-.. _kill-lua:
-
-kill-lua
---------
-Stops any currently-running Lua scripts. By default, scripts can
-only be interrupted every 256 instructions. Use ``kill-lua force``
-to interrupt the next instruction.
-
-
-.. _load:
-.. _unload:
-.. _reload:
-
-load
-----
-``load``, ``unload``, and ``reload`` control whether a plugin is loaded
-into memory - note that plugins are loaded but disabled unless you do
-something.  Usage::
-
-    load|unload|reload PLUGIN|(-a|--all)
-
-Allows dealing with plugins individually by name, or all at once.
-
-Note that plugins do not maintain their enabled state if they are reloaded, so
-you may need to use `enable` to re-enable a plugin after reloading it.
-
-
-.. _ls:
-
-ls
---
-``ls`` does not list files like the Unix command, but rather
-available commands - first built in commands, then plugins,
-and scripts at the end.  Usage:
-
-:ls -a:         Also list scripts in subdirectories of ``hack/scripts/``,
-                which are generally not intended for direct use.
-:ls <plugin>:   List subcommands for the given plugin.
-
-
-.. _plug:
-
-plug
-----
-Lists available plugins, including their state and detailed description.
-
-``plug``
-        Lists available plugins (*not* commands implemented by plugins)
-``plug [PLUGIN] [PLUGIN] ...``
-        List state and detailed description of the given plugins,
-        including commands implemented by the plugin.
-
-
-.. _sc-script:
-
-sc-script
----------
-Allows additional scripts to be run when certain events occur
-(similar to onLoad*.init scripts)
-
-
-.. _script:
-
-script
-------
-Reads a text file, and runs each line as a DFHack command
-as if it had been typed in by the user - treating the
-input like `an init file <init-files>`.
-
-Some other tools, such as `autobutcher` and `workflow`, export
-their settings as the commands to create them - which are later
-loaded with ``script``
-
-
-.. _show:
-
-show
-----
-Shows the terminal window after it has been `hidden <hide>`.
-Only available on Windows.  You'll need to use it from a
-`keybinding` set beforehand, or the in-game `command-prompt`.
-
-.. _type:
-
-type
-----
-``type command`` shows where ``command`` is implemented.
-
-Other Commands
---------------
-The following commands are *not* built-in, but offer similarly useful functions.
-
-* `command-prompt`
-* `hotkeys`
-* `lua`
-* `multicmd`
-* `nopause`
-* `quicksave`
-* `rb`
-* `repeat`
-
-
 .. _dfhack-config:
 
 Configuration Files
@@ -439,7 +185,7 @@ where ``*`` can be any string, including the empty string.
 A world being loaded can mean a fortress, an adventurer, or legends mode.
 
 These files are best used for non-persistent commands, such as setting
-a `fix <scripts-fix>` script to run on `repeat`.
+a `tag/bugfix` script to run on `repeat`.
 
 
 .. _onMapLoad.init:

docs/Dev-intro.rst

@@ -41,7 +41,7 @@ Installed plugins live in the ``hack/plugins`` folder of a DFHack installation,
 and the `load` family of commands can be used to load a recompiled plugin
 without restarting DF.
 
-See `plugins-index` for a list of all plugins included in DFHack.
+Run `plug` at the DFHack prompt for a list of all plugins included in DFHack.
 
 Scripts
 -------
@@ -51,10 +51,10 @@ is more complete and currently better-documented, however. Referring to existing
 scripts as well as the API documentation can be helpful when developing new
 scripts.
 
-`Scripts included in DFHack <scripts-index>` live in a separate `scripts repository <https://github.com/dfhack/scripts>`_.
+Scripts included in DFHack live in a separate
-This can be found in the ``scripts`` submodule if you have
+:source-scripts:`scripts repository <>`. This can be found in the ``scripts``
-`cloned DFHack <compile-how-to-get-the-code>`, or the ``hack/scripts`` folder
+submodule if you have `cloned DFHack <compile-how-to-get-the-code>`, or the
-of an installed copy of DFHack.
+``hack/scripts`` folder of an installed copy of DFHack.
 
 Core
 ----

docs/Documentation.rst

@@ -5,20 +5,24 @@ DFHack Documentation System
 ###########################
 
 
-DFHack documentation, like the file you are reading now, is created as ``.rst`` files,
+DFHack documentation, like the file you are reading now, is created as a set of
-which are in `reStructuredText (reST) <https://www.sphinx-doc.org/rest.html>`_ format.
+``.rst`` files in `reStructuredText (reST) <https://www.sphinx-doc.org/rest.html>`_
-This is a documentation format common in the Python community. It is very
+format. This is a documentation format common in the Python community. It is very
 similar in concept - and in syntax - to Markdown, as found on GitHub and many other
 places. However it is more advanced than Markdown, with more features available when
 compiled to HTML, such as automatic tables of contents, cross-linking, special
 external links (forum, wiki, etc) and more. The documentation is compiled by a
-Python tool, `Sphinx <https://www.sphinx-doc.org>`_.
+Python tool named `Sphinx <https://www.sphinx-doc.org>`_.
 
-The DFHack build process will compile the documentation, but this is disabled
+The DFHack build process will compile and install the documentation so it can be
-by default due to the additional Python and Sphinx requirements. You typically
+displayed in-game by the `help` and `ls` commands (and any other command or GUI that
-only need to build the docs if you're changing them, or perhaps
+displays help text), but this is disabled by default due to the additional Python and
-if you want a local HTML copy; otherwise, you can read an
+Sphinx requirements. If you already have a version of the docs installed (say from a
-`online version hosted by ReadTheDocs <https://dfhack.readthedocs.org>`_.
+downloaded release binary), then you only need to build the docs if you're changing them
+and want to see the changes reflected in your game.
+
+You can also build the docs if you just want a local HTML- or text-rendered copy, though
+you can always read the `online version <https://dfhack.readthedocs.org>`_ too.
 
 (Note that even if you do want a local copy, it is certainly not necessary to
 compile the documentation in order to read it. Like Markdown, reST documents are
@@ -28,116 +32,307 @@ The main thing you lose in plain text format is hyperlinking.)
 .. contents:: Contents
   :local:
 
+Concepts and general guidance
+=============================
+
+The source ``.rst`` files are compiled to HTML for viewing in a browser and to text
+format for viewing in-game. For in-game help, the help text is read from its installed
+location in ``hack/docs`` under the DF directory.
+
+When writing documentation, remember that everything should be documented!  If it's not
+clear *where* a particular thing should be documented, ask on Discord or in the DFHack
+thread on Bay12 -- you'll not only be getting help, you'll also be providing valuable
+feedback that makes it easier for future contributers to find documentation on how to
+write the documentation!
+
+Try to keep lines within 80-100 characters, so it's readable in plain text
+in the terminal - Sphinx (our documentation system) will make sure
+paragraphs flow.
+
+Short descriptions
+------------------
+
+Each command that a user can run, as well as every plugin that can be enabled for some
+lasting effect, needs to have a short (~54 character) descriptive string associated with
+it. This description text is:
+
+- used in-game by the `ls` command and DFHack UI screens that list commands
+- used in the generated index entries in the HTML docs
+
+Tags
+----
+
+To make it easier for players to find related commands, all plugins and commands are marked
+with relevant tags. These are used to compile indices and generate cross-links between the
+commands, both in the HTML documents and in-game. See the list of available `tag-list` and
+think about which categories your new tool belongs in.
+
+Links
+-----
+
+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:  e.g. ```autolabor```
+=> `autolabor`. Scripts and plugins have link targets that match their names
+created for you automatically.
+
+If you want to link to a heading in your own page, you can specifiy it like this::
+
+    `Heading text exactly as written`_
+
+Note that the DFHack documentation is configured so that single backticks (with
+no prefix or suffix) produce links to internal link targets, such as the
+``autolabor`` target shown above. This is different from the reStructuredText
+default behavior of rendering such text in italics (as a reference to a title).
+For alternative link behaviors, see:
+
+- `The reStructuredText documentation on roles <https://docutils.sourceforge.io/docs/ref/rst/roles.html>`__
+- `The reStructuredText documentation on external links <https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#hyperlink-targets>`__
+- `The Sphinx documentation on roles <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html>`__
+    - ``:doc:`` is useful for linking to another document outside of DFHack.
+
 .. _docs-standards:
 
 Documentation standards
 =======================
 
+.. highlight:: rst
+
 Whether you're adding new code or just fixing old documentation (and there's plenty),
 there are a few important standards for completeness and consistent style.  Treat
 this section as a guide rather than iron law, match the surrounding text, and you'll
 be fine.
 
-Command documentation
+Where do I add the help text?
----------------------
+-----------------------------
 
-Each command should have a short (~54 character) help string, which is shown
+For scripts and plugins that are distributed as part of DFHack, documentation files
-by the `ls` command.  For scripts, this is a comment on the first line
+should be added to the :source-scripts:`scripts/docs <docs>` and :source:`docs/plugins` directories,
-(the comment marker and whitespace is stripped).  For plugins it's the second
+respectively, in a file named after the script or plugin. For example, a script named
-argument to ``PluginCommand``.  Please make this brief but descriptive!
+``gui/foobar.lua`` (which provides the ``gui/foobar`` command) should be documented
+in a file named ``docs/gui/foobar.rst`` in the scripts repo. Similarly, a plugin named
+``foobaz`` should be documented in a file named ``docs/plugins/foobaz.rst`` in the dfhack repo.
+For plugins, all commands provided by that plugin should be documented in that same file.
 
-Everything should be documented!  If it's not clear *where* a particular
+Short descriptions (the ~54 character short help) are taken from the first "sentence" of
-thing should be documented, ask on IRC or in the DFHack thread on Bay12 -
+the help text for scripts and plugins that can be enabled. This means that the help should
-as well as getting help, you'll be providing valuable feedback that
+begin with a sentence fragment that begins with a capital letter and ends in a full stop
-makes it easier for future readers!
+(``.``). Please make this brief but descriptive!
 
-Scripts can use a custom autodoc function, based on the Sphinx ``include``
+Short descriptions for commands provided by plugins are taken from the ``description``
-directive - anything between the tokens is copied into the appropriate scripts
+parameter passed to the ``PluginCommand`` constructor used when the command is registered
-documentation page.  For Ruby, we follow the built-in docstring convention
+in the plugin source file.
-(``=begin`` and ``=end``).  For Lua, the tokens are ``[====[`` and ``]====]``
-- ordinary multi-line strings.  It is highly encouraged to reuse this string
-as the in-console documentation by (e.g.) printing it when a ``-help`` argument
-is given.
 
-The docs **must** have a heading which exactly matches the command, underlined
+Header format
-with ``=====`` to the same length.  For example, a lua file would have:
+-------------
 
-.. code-block:: lua
+The docs **must** begin with a heading which exactly matches the script or plugin name, underlined
+with ``=====`` to the same length. This should be followed by a ``.. dfhack-tool:`` directive with
+at least the following parameters:
 
-    local helpstr = [====[
+* ``:summary:`` - a short, single-sentence description of the tool
+* ``:tags:`` - a space-separated list of tags that apply to the tool
 
-    add-thought
+By default, ``dfhack-tool`` generates both a description of a tool and a command
-    ===========
+with the same name. For tools (specifically plugins) that do not provide exactly
-    Adds a thought or emotion to the selected unit.  Can be used by other scripts,
+1 command with the same name as the tool, pass the ``:no-command:`` parameter (with
-    or the gui invoked by running ``add-thought gui`` with a unit selected.
+no content after it) to prevent the command block from being generated.
 
-    ]====]
+For tools that provide multiple commands, or a command by the same name but with
+significantly different functionality (e.g. a plugin that can be both enabled
+and invoked as a command for different results), use the ``.. dfhack-command:``
+directive for each command. This takes only a ``:summary:`` argument, with the
+same meaning as above.
 
+For example, documentation for the ``build-now`` script might look like::
 
-.. highlight:: rst
+    build-now
+    =========
 
-Where the heading for a section is also the name of a command, the spelling
+    .. dfhack-tool::
-and case should exactly match the command to enter in the DFHack command line.
+        :summary: Instantly completes unsuspended building construction jobs.
+        :tags: fort armok buildings
 
-Try to keep lines within 80-100 characters, so it's readable in plain text
+    By default, all buildings on the map are completed, but the area of effect is configurable.
-in the terminal - Sphinx (our documentation system) will make sure
-paragraphs flow.
 
-Command usage
+And documentation for the ``autodump`` plugin might look like::
--------------
+
+    autodump
+    ========
+
+    .. dfhack-tool::
+        :summary: Automatically set items in a stockpile to be dumped.
+        :tags: fort armok fps productivity items stockpiles
+        :no-command:
+
+    .. dfhack-command:: autodump
+        :summary: Teleports items marked for dumping to the cursor position.
+
+    .. dfhack-command:: autodump-destroy-here
+        :summary: Destroy items marked for dumping under the cursor.
 
-If there aren't many options or examples to show, they can go in a paragraph of
+    .. dfhack-command:: autodump-destroy-item
-text.  Use double-backticks to put commands in monospaced font, like this::
+        :summary: Destroys the selected item.
 
-    You can use ``cleanowned scattered x`` to dump tattered or abandoned items.
+    When `enabled <enable>`, this plugin adds an option to the :kbd:`q` menu for
+    stockpiles.
 
-If the command takes more than three arguments, format the list as a table
+    When invoked as a command, it can instantly move all unforbidden items marked
-called Usage.  The table *only* lists arguments, not full commands.
+    for dumping to the tile under the cursor.
-Input values are specified in angle brackets.  Example::
+
+Usage help
+----------
+
+The first section after the header and introductory text should be the usage block. You can
+choose between two formats, based on whatever is cleaner or clearer for your syntax. The first
+option is to show usage formats together, with an explanation following the block::
+
+    Usage::
+
+        build-now [<options>]
+        build-now here [<options>]
+        build-now [<pos> [<pos>]] [<options>]
+
+    Where the optional ``<pos>`` pair can be used to specify the
+    coordinate bounds within which ``build-now`` will operate. If
+    they are not specified, ``build-now`` will scan the entire map.
+    If only one ``<pos>`` is specified, only the building at that
+    coordinate is built.
+
+    The ``<pos>`` parameters can either be an ``<x>,<y>,<z>`` triple
+    (e.g. ``35,12,150``) or the string ``here``, which means the
+    position of the active game cursor.
+
+The second option is to arrange the usage options in a list, with the full command
+and arguments in monospaced font. Then indent the next line and describe the effect::
 
     Usage:
 
-    :arg1:          A simple argument.
+    ``build-now [<options>]``
-    :arg2 <input>:  Does something based on the input value.
+        Scan the entire map and build all unsuspended constructions
-    :Very long argument:
+        and buildings.
-                    Is very specific.
+    ``build-now here [<options>]``
+        Build the unsuspended construction or building under the
+        cursor.
+    ``build-now [<pos> [<pos>]] [<options>]``
+        Build all unsuspended constructions within the specified
+        coordinate box.
+
+    The ``<pos>`` parameters are specified as...
+
+Note that in both options, the entire commandline syntax is written, including the command itself.
+Literal text is written as-is (e.g. the word ``here`` in the above example), and text that
+describes the kind of parameter that is being passed (e.g. ``pos`` or ``options``) is enclosed in
+angle brackets (``<`` and ``>``). Optional elements are enclosed in square brackets (``[`` and ``]``).
+
+Examples
+--------
+
+If the only way to run the command is to type the command itself, then this section is not necessary.
+Otherwise, please consider adding a section that shows some real, practical usage examples. For
+many users, this will be the **only** section they will read. It is so important that it is a good
+idea to include the ``Examples`` section **before** you describe any extended options your command
+might take. Write examples for what you expect the popular use cases will be. Also be sure to write
+examples showing specific, practical values being used for any parameter that takes a value.
+
+Examples should go in their own subheading with a single dash underline (``--------``). The examples
+themselves should be organized in a list, the same as in option 2 for Usage above. Here is an
+example Examples section::
+
+    Examples
+    --------
+
+    ``build-now``
+        Completes all unsuspended construction jobs on the map.
+    ``build-now 37,20,154 here``
+        Builds the unsuspended, unconstructed buildings in the box
+        bounded by the coordinate x=37,y=20,z=154 and the cursor.
+
+Options
+-------
 
-To demonstrate usage - useful mainly when the syntax is complicated, list the
+The options header should follow the examples, with each option in the same list format as the
-full command with arguments in monospaced font, then indent the next line and
+examples::
-describe the effect::
 
-    ``resume all``
+    Options
-            Resumes all suspended constructions.
+    -------
 
-Links
+    ``-h``, ``--help``
------
+        Show help text.
+    ``-l``, ``--quality <level>``
+        Set the quality of the architecture for built architected
+        builtings.
+    ``-q``, ``--quiet``
+        Suppress informational output (error messages are still
+        printed).
 
-If it would be helpful to mention another DFHack command, don't just type the
+Note that for parameters that have both short and long forms, any values that those options
-name - add a hyperlink!  Specify the link target in backticks, and it will be
+take only need to be specified once (e.g. ``<level>``).
-replaced with the corresponding title and linked:  e.g. ```autolabor```
-=> `autolabor`.  Link targets should be equivalent to the command
-described (without file extension), and placed above the heading of that
-section like this::
 
-    .. _autolabor:
+External scripts and plugins
+============================
 
-    autolabor
+Scripts and plugins distributed separately from DFHack's release packages don't have the
-    =========
+opportunity to add their documentation to the rendered HTML or text output. However, these
+scripts and plugins can use a different mechanism to at least make their help text available
+in-game.
 
-Add link targets if you need them, but otherwise plain headings are preferred.
+Note that since help text for external scripts and plugins is not rendered by Sphinx,
-Scripts have link targets created automatically.
+it should be written in plain text. Any reStructuredText markup will not be processed.
 
-Note that the DFHack documentation is configured so that single backticks (with
+For external scripts, the short description comes from a comment on the first line
-no prefix or suffix) produce links to internal link targets, such as the
+(the comment marker and extra whitespace is stripped). For Lua, this would look like:
-``autolabor`` target shown above. This is different from the reStructuredText
-default behavior of rendering such text in italics (as a reference to a title).
-For alternative link behaviors, see:
 
-- `The reStructuredText documentation on roles <https://docutils.sourceforge.io/docs/ref/rst/roles.html>`__
+.. code-block:: lua
-- `The reStructuredText documentation on external links <https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#hyperlink-targets>`__
+
-- `The Sphinx documentation on roles <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html>`__
+    -- A short description of my cool script.
 
-    - ``:doc:`` is useful for linking to another document
+and for Ruby scripts it would look like:
+
+.. code-block:: ruby
+
+    # A short description of my cool script.
+
+The main help text for an external script needs to appear between two markers. For
+Lua, these markers are ``[====[`` and ``]====]``, and for Ruby they are ``=begin`` and
+``=end``. The documentation standards above still apply to external tools, but there is
+no need to include backticks for links or monospaced fonts. Here is a Lua example for an
+entire script header::
+
+    -- Inventory management for adventurers.
+    -- [====[
+    gui/adv-inventory
+    =================
+    Tags: adventure, items
+
+    Allows you to quickly move items between containers. This
+    includes yourself and any followers you have.
+
+    Usage:
+
+        gui/adv-inventory [<options>]
+
+    Examples:
+
+    gui/adv-inventory
+        Opens the GUI with nothing preselected
+    gui/adv-inventory take-all
+        Opens the GUI with all container items already selected and
+        ready to move into the adventurer's inventory.
+
+    Options:
+
+    take-all
+        Starts the GUI with container items pre-selected
+    give-all
+        Starts the GUI with your own items pre-selected
+    ]====]
+
+For external plugins, help text for provided commands can be passed as the ``usage``
+parameter when registering the commands with the ``PluginCommand`` constructor. There
+is currently no way for associating help text with the plugin itself, so any
+information about what the plugin does when enabled should be combined into the command
+help.
 
 Required dependencies
 =====================
@@ -258,33 +453,48 @@ ways to do this:
 * On Windows, if you prefer to use the batch scripts, you can run
   ``generate-msvc-gui.bat`` and set ``BUILD_DOCS`` through the GUI. If you are
   running another file, such as ``generate-msvc-all.bat``, you will need to edit
-  it to add the flag. You can also run ``cmake`` on the command line, similar to
+  the batch script to add the flag. You can also run ``cmake`` on the command line,
-  other platforms.
+  similar to other platforms.
 
-The generated documentation will be stored in ``docs/html`` in the root DFHack
+By default, both HTML and text docs are built by CMake. The generated
-folder, and will be installed to ``hack/docs`` when you next install DFHack in a
+documentation is stored in ``docs/html`` and ``docs/text`` (respectively) in the
-DF folder.
+root DFHack folder, and will be installed to ``hack/docs`` when you install
+DFHack.
 
 Running Sphinx manually
 -----------------------
 
 You can also build the documentation without running CMake - this is faster if
-you only want to rebuild the documentation regardless of any code changes. There
+you only want to rebuild the documentation regardless of any code changes. The
-is a ``docs/build.sh`` script provided for Linux and macOS that will run
+``docs/build.py`` script will build the documentation in any specified formats
-essentially the same command that CMake runs when building the docs - see the
+(HTML only by default) using essentially the same command that CMake runs when
-script for additional options.
+building the docs. Run the script with ``--help`` to see additional options.
+
+Examples:
+
+* ``docs/build.py``
+    Build just the HTML docs
+
+* ``docs/build.py html text``
+    Build both the HTML and text docs
+
+* ``docs/build.py --clean``
+    Build HTML and force a clean build (all source files are re-read)
 
-To build the documentation with default options, run the following command from
+The resulting documentation will be stored in ``docs/html`` and/or ``docs/text``.
-the root DFHack folder::
+
+Alternatively, you can run Sphinx manually with::
 
     sphinx-build . docs/html
 
-The resulting documentation will be stored in ``docs/html`` (you can specify
+or, to build plain-text output::
-a different path when running ``sphinx-build`` manually, but be warned that
+
-Sphinx may overwrite existing files in this folder).
+    sphinx-build -b text . docs/text
 
 Sphinx has many options to enable clean builds, parallel builds, logging, and
-more - run ``sphinx-build --help`` for details.
+more - run ``sphinx-build --help`` for details. If you specify a different
+output path, be warned that Sphinx may overwrite existing files in the output
+folder.
 
 Building a PDF version
 ----------------------
@@ -295,10 +505,11 @@ want to build a PDF version locally, you will need ``pdflatex``, which is part
 of a TeX distribution. The following command will then build a PDF, located in
 ``docs/pdf/latex/DFHack.pdf``, with default options::
 
-  sphinx-build -M latexpdf . docs/pdf
+  docs/build.py pdf
 
-There is a ``docs/build-pdf.sh`` script provided for Linux and macOS that runs
+Alternatively, you can run Sphinx manually with::
-this command for convenience - see the script for additional options.
+
+  sphinx-build -M latexpdf . docs/pdf
 
 .. _build-changelog:
 
@@ -318,10 +529,10 @@ changelogs are combined as part of the changelog build process:
 * ``scripts/changelog.txt`` for changes made to scripts in the ``scripts`` repo
 * ``library/xml/changelog.txt`` for changes made in the ``df-structures`` repo
 
-Building the changelogs generates two files: ``docs/_auto/news.rst`` and
+Building the changelogs generates two files: ``docs/changelogs/news.rst`` and
-``docs/_auto/news-dev.rst``. These correspond to `changelog` and `dev-changelog`
+``docs/changelogs/news-dev.rst``. These correspond to `changelog` and
-and contain changes organized by stable and development DFHack releases,
+`dev-changelog` and contain changes organized by stable and development DFHack
-respectively. For example, an entry listed under "0.44.05-alpha1" in
+releases, respectively. For example, an entry listed under "0.44.05-alpha1" in
 changelog.txt will be listed under that version in the development changelog as
 well, but under "0.44.05-r1" in the stable changelog (assuming that is the
 closest stable release after 0.44.05-alpha1). An entry listed under a stable

docs/History.rst

@@ -1350,7 +1350,7 @@ Misc improvements
 - `createitem`: in adventure mode it now defaults to the controlled unit as maker.
 - `autotrade`: adds "(Un)mark All" options to both panes of trade screen.
 - `mousequery`: several usability improvements; show live overlay (in menu area) of what's on the tile under the mouse cursor.
-- `search`: workshop profile search added.
+- `search-plugin`: workshop profile search added.
 - `dwarfmonitor`: add screen to summarise preferences of fortress dwarfs.
 - `getplants`: add autochop function to automate woodcutting.
 - `stocks`: added more filtering and display options.
@@ -1510,7 +1510,7 @@ New binary patches
 New Plugins
 -----------
 - `fix-armory`: Together with a couple of binary patches and the `gui/assign-rack` script, this plugin makes weapon racks, armor stands, chests and cabinets in properly designated barracks be used again for storage of squad equipment.
-- `search`: Adds an incremental search function to the Stocks, Trading, Stockpile and Unit List screens.
+- `search-plugin`: Adds an incremental search function to the Stocks, Trading, Stockpile and Unit List screens.
 - `automaterial`: 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.
 - Dfusion: Reworked to make use of lua modules, now all the scripts can be used from other scripts.
 - Eventful: A collection of lua events, that will allow new ways to interact with df world.

docs/Installing.rst

@@ -96,13 +96,14 @@ When you `download DFHack <downloading>`, you will end up with a release archive
 operating system should have built-in utilities capable of extracting files from
 these archives.
 
-The release archives contain several files and folders, including a ``hack``
+The release archives contain several folders, including a ``hack`` folder where
-folder, a ``dfhack-config`` folder, and a ``dfhack.init-example`` file. To
+DFHack binary and system data is stored, a ``dfhack-config`` folder where user
-install DFHack, copy all of the files from the DFHack archive into the root DF
+data and configuration is stored, and a ``blueprints`` folder where `quickfort`
-folder, which should already include a ``data`` folder and a ``raw`` folder,
+blueprints are stored. To install DFHack, copy all of the files from the DFHack
-among other things. Some packs and other redistributions of Dwarf Fortress may
+archive into the root DF folder, which should already include a ``data`` folder
-place DF in another folder, so ensure that the ``hack`` folder ends up next to
+and a ``raw`` folder, among other things. Some packs and other redistributions
-the ``data`` folder.
+of Dwarf Fortress may place DF in another folder, so ensure that the ``hack``
+folder ends up next to the ``data`` folder.
 
 .. note::
 

docs/Introduction.rst

@@ -21,7 +21,7 @@ enhancements by default, and more can be enabled.  There are also many tools
 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-modtools`
+interactions, magic creature abilities, and more can be set through `DFHack tools <genindex>`
 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.
@@ -59,7 +59,43 @@ used by the DFHack console.
 * Finally, some commands are persistent once enabled, and will sit in the
   background managing or changing some aspect of the game if you `enable` them.
 
+.. note::
+    In order to avoid user confusion, as a matter of policy all GUI tools
+    display the word :guilabel:`DFHack` on the screen somewhere while active.
+
+    When that is not appropriate because they merely add keybinding hints to
+    existing DF screens, they deliberately use red instead of green for the key.
+
+.. _support:
 
 Getting help
 ============
-There are several support channels available - see `support` for details.
+
+DFHack has several ways to get help online, including:
+
+- The `DFHack Discord server <https://dfhack.org/discord>`__
+- The ``#dfhack`` IRC channel on `Libera <https://libera.chat/>`__
+- GitHub:
+    - for bugs, use the :issue:`issue tracker <>`
+    - for more open-ended questions, use the `discussion board
+      <https://github.com/DFHack/dfhack/discussions>`__. Note that this is a
+      relatively-new feature as of 2021, but maintainers should still be
+      notified of any discussions here.
+- The `DFHack thread on the Bay 12 Forum <https://dfhack.org/bay12>`__
+
+Some additional, but less DFHack-specific, places where questions may be answered include:
+
+- The `/r/dwarffortress <https://dwarffortress.reddit.com>`_ questions thread on Reddit
+- If you are using a starter pack, the relevant thread on the `Bay 12 Forum <http://www.bay12forums.com/smf/index.php?board=2.0>`__ -
+  see the :wiki:`DF Wiki <Utility:Lazy_Newb_Pack>` for a list of these threads
+
+When reaching out to any support channels regarding problems with DFHack, please
+remember to provide enough details for others to identify the issue. For
+instance, specific error messages (copied text or screenshots) are helpful, as
+well as any steps you can follow to reproduce the problem. Sometimes, log output
+from ``stderr.log`` in the DF folder can point to the cause of issues as well.
+
+Some common questions may also be answered in documentation, including:
+
+- This documentation (`online here <https://dfhack.readthedocs.io>`__; search functionality available `here <search>`)
+- :wiki:`The DF wiki <>`

docs/Lua API.rst

@@ -4397,7 +4397,7 @@ blueprint files:
 The names of the functions are also available as the keys of the
 ``valid_phases`` table.
 
-.. _building-hacks:
+.. _building-hacks-api:
 
 building-hacks
 ==============
@@ -4536,7 +4536,7 @@ Native functions:
 
 The lua module file also re-exports functions from ``dfhack.burrows``.
 
-.. _cxxrandom:
+.. _cxxrandom-api:
 
 cxxrandom
 =========
@@ -4706,7 +4706,7 @@ The dig-now plugin exposes the following functions to Lua:
     command ``dig-now <pos> <pos>``. See the `dig-now` documentation for details
     on default settings.
 
-.. _eventful:
+.. _eventful-api:
 
 eventful
 ========
@@ -4874,7 +4874,7 @@ Integrated tannery::
   b=require "plugins.eventful"
   b.addReactionToShop("TAN_A_HIDE","LEATHERWORKS")
 
-.. _luasocket:
+.. _luasocket-api:
 
 luasocket
 =========
@@ -4945,7 +4945,7 @@ A class with all the tcp functionality.
   Tries connecting to that address and port. Returns ``client`` object.
 
 
-.. _map-render:
+.. _map-render-api:
 
 map-render
 ==========
@@ -4961,7 +4961,7 @@ Functions
 
   returns a table with w*h*4 entries of rendered tiles. The format is same as ``df.global.gps.screen`` (tile,foreground,bright,background).
 
-.. _pathable:
+.. _pathable-api:
 
 pathable
 ========
@@ -4995,7 +4995,7 @@ sort
 The `sort <sort>` plugin does not export any native functions as of now.
 Instead, it calls Lua code to perform the actual ordering of list items.
 
-.. _xlsxreader:
+.. _xlsxreader-api:
 
 xlsxreader
 ==========

docs/Memory-research.rst

@@ -63,7 +63,7 @@ are not built by default, but can be built by setting the ``BUILD_DEVEL``
 Scripts
 ~~~~~~~
 
-Several `development scripts <scripts-devel>` can be useful for memory research.
+Several `development tools <tag/dev>` can be useful for memory research.
 These include (but are not limited to):
 
 - `devel/dump-offsets`

docs/NEWS-dev.rst

@@ -17,4 +17,4 @@ See `changelog` for a list of changes grouped by stable releases.
   :local:
   :depth: 1
 
-.. include:: /docs/_auto/news-dev.rst
+.. include:: /docs/changelogs/news-dev.rst

docs/NEWS.rst

@@ -17,7 +17,7 @@ See `dev-changelog` for a list of changes grouped by development releases.
   :local:
   :depth: 1
 
-.. include:: /docs/_auto/news.rst
+.. include:: /docs/changelogs/news.rst
 
 
 Older Changelogs

docs/Removed.rst

@@ -48,6 +48,14 @@ existing .csv files. Just move them to the ``blueprints`` folder in your DF
 installation, and instead of ``digfort file.csv``, run
 ``quickfort run file.csv``.
 
+.. _fix-armory:
+
+fix-armory
+==========
+Allowed the military to store equipment in barracks containers. Removed because
+it required a binary patch to DF in order to function, and no such patch has
+existed since DF 0.34.11.
+
 .. _fix/build-location:
 
 fix/build-location
@@ -74,9 +82,9 @@ Replaced by `gui/create-item`.
 
 gui/no-dfhack-init
 ==================
-No longer useful since the user doesn't have to create their own ``dfhack.init``
+Tool that warned the user when the ``dfhack.init`` file did not exist. Now that
-file now that init files have moved to ``dfhack-config/init``. It used to show
+``dfhack.init`` is autogenerated in ``dfhack-config/init``, this warning is no
-a warning at startup if :file:`dfhack.init` file was not found.
+longer necessary.
 
 .. _warn-stuck-trees:
 

docs/Scripts.rst

@@ -1,19 +0,0 @@
-.. _scripts-index:
-
-##############
-DFHack Scripts
-##############
-
-Lua or ruby scripts placed in the :file:`hack/scripts/` directory
-are considered for execution as if they were native DFHack commands.
-
-The following pages document all the scripts in the DFHack standard library.
-
-.. toctree::
-   :maxdepth: 2
-
-   /docs/_auto/base
-   /docs/_auto/devel
-   /docs/_auto/fix
-   /docs/_auto/gui
-   /docs/_auto/modtools

docs/Support.rst

@@ -1,34 +1,3 @@
-.. _support:
+:orphan:
 
-===============
+Please continue to the new `support` page.
-Getting Support
-===============
-
-DFHack has several ways to get help online, including:
-
-- The `DFHack Discord server <https://dfhack.org/discord>`__
-- The ``#dfhack`` IRC channel on `Libera <https://libera.chat/>`__
-- GitHub:
-    - for bugs, use the :issue:`issue tracker <>`
-    - for more open-ended questions, use the `discussion board
-      <https://github.com/DFHack/dfhack/discussions>`__. Note that this is a
-      relatively-new feature as of 2021, but maintainers should still be
-      notified of any discussions here.
-- The `DFHack thread on the Bay 12 Forum <https://dfhack.org/bay12>`__
-
-Some additional, but less DFHack-specific, places where questions may be answered include:
-
-- The `/r/dwarffortress <https://dwarffortress.reddit.com>`_ questions thread on Reddit
-- If you are using a starter pack, the relevant thread on the `Bay 12 Forum <http://www.bay12forums.com/smf/index.php?board=2.0>`__ -
-  see the :wiki:`DF Wiki <Utility:Lazy_Newb_Pack>` for a list of these threads
-
-When reaching out to any support channels regarding problems with DFHack, please
-remember to provide enough details for others to identify the issue. For
-instance, specific error messages (copied text or screenshots) are helpful, as
-well as any steps you can follow to reproduce the problem. Sometimes, log output
-from ``stderr.log`` in the DF folder can point to the cause of issues as well.
-
-Some common questions may also be answered in documentation, including:
-
-- This documentation (`online here <https://dfhack.readthedocs.io>`__; search functionality available `here <search>`)
-- :wiki:`The DF wiki <>`

docs/Tags.rst

@@ -0,0 +1,48 @@
+:orphan:
+
+.. _tag-list:
+
+DFHack tool tags
+================
+
+A tool often has at least one tag per group, encompassing when you use the tool,
+why you might want to use it, and what kind of thing you're trying to affect.
+
+See https://docs.google.com/spreadsheets/d/1hiDlo8M_bB_1jE-5HRs2RrrA_VZ4cRu9VXaTctX_nwk/edit#gid=1774645373
+for the tag assignment spreadsheet.
+
+"when" tags
+-----------
+- `tag/adventure`: Tools that are useful while in adventure mode. Note that some tools only tagged with "fort" might also work in adventure mode, but not always in expected ways. Feel free to experiment, though!
+- `tag/dfhack`: Tools that you use to run DFHack commands or interact with the DFHack library. This tag also includes tools that help you manage the DF game itself (e.g. settings, saving, etc.)
+- `tag/embark`: Tools that are useful while on the fort embark screen or while creating an adventurer.
+- `tag/fort`: Tools that are useful while in fort mode.
+- `tag/legends`: Tools that are useful while in legends mode.
+
+"why" tags
+----------
+- `tag/armok`: Tools that give you complete control over an aspect of the game or provide access to information that the game intentionally keeps hidden.
+- `tag/auto`: Tools that run in the background and automatically manage routine, toilsome aspects of your fortress.
+- `tag/bugfix`: Tools that fix specific bugs, either permanently or on-demand.
+- `tag/design`: Tools that help you design your fort.
+- `tag/dev`: Tools that are useful when developing scripts or mods.
+- `tag/fps`: Tools that help you manage FPS drop.
+- `tag/gameplay`: Tools that introduce new gameplay elements.
+- `tag/inspection`: Tools that let you view information that is otherwise difficult to find.
+- `tag/productivity`: Tools that help you do things that you could do manually, but using the tool is better and faster.
+
+"what" tags
+-----------
+- `tag/animals`: Tools that interact with animals.
+- `tag/buildings`: Tools that interact with buildings and furniture.
+- `tag/graphics`: Tools that interact with game graphics.
+- `tag/interface`: Tools that interact with or extend the DF user interface.
+- `tag/items`: Tools that interact with in-game items.
+- `tag/jobs`: Tools that interact with jobs.
+- `tag/labors`: Tools that deal with labor assignment.
+- `tag/map`: Tools  that interact with the game map.
+- `tag/military`: Tools that interact with the military.
+- `tag/plants`: Tools that interact with trees, shrubs, and crops.
+- `tag/stockpiles`: Tools that interact wtih stockpiles.
+- `tag/units`: Tools that interact with units.
+- `tag/workorders`: Tools that interact with workorders.

docs/Tools.rst

@@ -0,0 +1,50 @@
+.. _tools:
+
+DFHack tools
+============
+
+DFHack has **a lot** of tools. This page attempts to make it clearer what they
+are, how they work, and how to find the ones you want.
+
+.. contents:: Contents
+  :local:
+
+What tools are and how they work
+--------------------------------
+
+DFHack is a Dwarf Fortress memory access and modification framework, so DFHack
+tools normally access Dwarf Fortress internals and make some specific changes.
+
+Some tools just make a targeted change when you run them, like `unforbid`, which
+scans through all your items and removes the ``forbidden`` flag from each of
+them.
+
+Some tools need to be enabled, and then they run in the background and make
+changes to the game on your behalf, like `autobutcher`, which monitors your
+livestock population and automatically marks excess animals for butchering.
+
+And some tools just exist to give you information that is otherwise hard to
+come by, like `gui/petitions`, which shows you the active petitions for
+guildhalls and temples that you have agreed to.
+
+Finding the tool you need
+-------------------------
+
+DFHack tools are tagged with categories to make them easier to find. Note that a
+tool can belong to more than one category. If you'd like to see the full list of
+tools in one flat list, please refer to the `index <genindex>`.
+
+DFHack tools by game mode
+-------------------------
+
+.. include:: tags/bywhen.rst
+
+DFHack tools by theme
+---------------------
+
+.. include:: tags/bywhy.rst
+
+DFHack tools by what they affect
+--------------------------------
+
+.. include:: tags/bywhat.rst

docs/_auto/.gitignore

@@ -1 +0,0 @@
-*.rst

docs/_changelogs/.gitignore

@@ -1 +0,0 @@
-*.txt

docs/build-pdf.sh

@@ -1,23 +0,0 @@
-#!/bin/sh
-
-# usage:
-#   ./build-pdf.sh
-#   SPHINX=/path/to/sphinx-build ./build-pdf.sh
-#   JOBS=3 ./build-pdf.sh ...
-# all command-line arguments are passed directly to sphinx-build - run
-# ``sphinx-build --help`` for a list, or see
-# https://www.sphinx-doc.org/en/master/man/sphinx-build.html
-
-cd $(dirname "$0")
-cd ..
-
-sphinx=sphinx-build
-if [ -n "$SPHINX" ]; then
-    sphinx=$SPHINX
-fi
-
-if [ -z "$JOBS" ]; then
-    JOBS=2
-fi
-
-"$sphinx" -M latexpdf . ./docs/pdf -w ./docs/_sphinx-warnings.txt -j "$JOBS" "$@"

docs/build.py

@@ -0,0 +1,100 @@
+#!/usr/bin/env python3
+
+# for help, run: python3 build.py --help
+
+import argparse
+import os
+import subprocess
+import sys
+
+class SphinxOutputFormat:
+    def __init__(self, name, pre_args):
+        self.name = str(name)
+        self.pre_args = tuple(pre_args)
+
+    @property
+    def args(self):
+        output_dir = os.path.join('docs', self.name)
+        artifacts_dir = os.path.join('build', 'docs', self.name)  # for artifacts not part of the final documentation
+        return [
+            *self.pre_args,
+            '.',  # source dir
+            output_dir,
+            '-d', artifacts_dir,
+            '-w', os.path.join(artifacts_dir, 'sphinx-warnings.txt'),
+        ]
+
+OUTPUT_FORMATS = {
+    'html': SphinxOutputFormat('html', pre_args=['-b', 'html']),
+    'text': SphinxOutputFormat('text', pre_args=['-b', 'text']),
+    'pdf': SphinxOutputFormat('pdf', pre_args=['-M', 'latexpdf']),
+    'xml': SphinxOutputFormat('xml', pre_args=['-b', 'xml']),
+    'pseudoxml': SphinxOutputFormat('pseudoxml', pre_args=['-b', 'pseudoxml']),
+}
+
+def _parse_known_args(parser, source_args):
+    # pass along any arguments after '--'
+    ignored_args = []
+    if '--' in source_args:
+        source_args, ignored_args = source_args[:source_args.index('--')], source_args[source_args.index('--')+1:]
+    args, forward_args = parser.parse_known_args(source_args)
+    forward_args += ignored_args
+    return args, forward_args
+
+def parse_args(source_args):
+    def output_format(s):
+        if s in OUTPUT_FORMATS:
+            return s
+        raise ValueError
+
+    parser = argparse.ArgumentParser(usage='%(prog)s [{} ...] [options] [--] [sphinx_options]'.format('|'.join(OUTPUT_FORMATS.keys())), description='''
+    DFHack wrapper around sphinx-build.
+
+    Any unrecognized options are passed directly to sphinx-build, as well as any
+    options following a '--' argument, if specified.
+    ''')
+    parser.add_argument('format', nargs='*', type=output_format, action='append',
+        help='Documentation format(s) to build - choose from {}'.format(', '.join(OUTPUT_FORMATS.keys())))
+    parser.add_argument('-E', '--clean', action='store_true',
+        help='Re-read all input files')
+    parser.add_argument('--sphinx', type=str, default=os.environ.get('SPHINX', 'sphinx-build'),
+        help='Sphinx executable to run [environment variable: SPHINX; default: "sphinx-build"]')
+    parser.add_argument('-j', '--jobs', type=str, default=os.environ.get('JOBS', 'auto'),
+        help='Number of Sphinx threads to run [environment variable: JOBS; default: "auto"]')
+    parser.add_argument('--debug', action='store_true',
+        help='Log commands that are run, etc.')
+    parser.add_argument('--offline', action='store_true',
+        help='Disable network connections')
+    args, forward_args = _parse_known_args(parser, source_args)
+
+    # work around weirdness with list args
+    args.format = args.format[0]
+    if not args.format:
+        args.format = ['html']
+
+    return args, forward_args
+
+if __name__ == '__main__':
+    os.chdir(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+    if not os.path.isfile('conf.py'):
+        print('Could not find conf.py', file=sys.stderr)
+        exit(1)
+
+    args, forward_args = parse_args(sys.argv[1:])
+
+    sphinx_env = os.environ.copy()
+    if args.offline:
+        sphinx_env['DFHACK_DOCS_BUILD_OFFLINE'] = '1'
+
+    for format_name in args.format:
+        command = [args.sphinx] + OUTPUT_FORMATS[format_name].args + ['-j', args.jobs]
+        if args.clean:
+            command += ['-E']
+        command += forward_args
+
+        if args.debug:
+            print('Building:', format_name)
+            print('Running:', command)
+        subprocess.run(command, check=True, env=sphinx_env)
+
+        print('')

docs/build.sh

@@ -1,23 +0,0 @@
-#!/bin/sh
-
-# usage:
-#   ./build.sh
-#   SPHINX=/path/to/sphinx-build ./build.sh
-#   JOBS=3 ./build.sh ...
-# all command-line arguments are passed directly to sphinx-build - run
-# ``sphinx-build --help`` for a list, or see
-# https://www.sphinx-doc.org/en/master/man/sphinx-build.html
-
-cd $(dirname "$0")
-cd ..
-
-sphinx=sphinx-build
-if [ -n "$SPHINX" ]; then
-    sphinx=$SPHINX
-fi
-
-if [ -z "$JOBS" ]; then
-    JOBS=2
-fi
-
-"$sphinx" -a -b html . ./docs/html -w ./docs/_sphinx-warnings.txt -j "$JOBS" "$@"

docs/builtins/alias.rst

@@ -0,0 +1,36 @@
+alias
+=====
+
+.. dfhack-tool::
+    :summary: Configure helper aliases for other DFHack commands.
+    :tags: dfhack
+
+Aliases are resolved immediately after built-in commands, which means that an
+alias cannot override a built-in command, but can override a command implemented
+by a plugin or script.
+
+Usage
+-----
+
+``alias list``
+    Lists all configured aliases
+``alias add <name> <command> [arguments...]``
+    Adds an alias
+``alias replace <name> <command> [arguments...]``
+    Replaces an existing alias with a new command, or adds the alias if it does
+    not already exist
+``alias delete <name>``
+    Removes the specified alias
+
+Aliases can be given additional arguments when created and invoked, which will
+be passed to the underlying command in order.
+
+Example
+-------
+
+::
+
+    [DFHack]# alias add pargs devel/print-args example
+    [DFHack]# pargs text
+    example
+    text

docs/builtins/cls.rst

@@ -0,0 +1,16 @@
+cls
+===
+
+.. dfhack-tool::
+    :summary: Clear the terminal screen.
+    :tags: dfhack
+
+Can also be invoked as ``clear``. Note that this command does not delete command
+history. It just clears the text on the screen.
+
+Usage
+-----
+
+::
+
+    cls

docs/builtins/devel/dump-rpc.rst

@@ -0,0 +1,15 @@
+devel/dump-rpc
+==============
+
+.. dfhack-tool::
+    :summary: Dump RPC endpoint info.
+    :tags: dev
+
+Write RPC endpoint information to the specified file.
+
+Usage
+-----
+
+::
+
+    devel/dump-rpc <filename>

docs/builtins/die.rst

@@ -0,0 +1,15 @@
+die
+===
+
+.. dfhack-tool::
+    :summary: Instantly exit DF without saving.
+    :tags: dfhack
+
+Use to exit DF quickly and safely.
+
+Usage
+-----
+
+::
+
+    die

docs/builtins/disable.rst

@@ -0,0 +1,15 @@
+disable
+=======
+
+.. dfhack-tool::
+    :summary: Deactivate a DFHack tool that has some persistent effect.
+    :tags: dfhack
+
+See the `enable` command for more info.
+
+Usage
+-----
+
+::
+
+    disable <plugin> [<plugin> ...]

docs/builtins/enable.rst

@@ -0,0 +1,33 @@
+enable
+======
+
+.. dfhack-tool::
+    :summary: Activate a DFHack tool that has some persistent effect.
+    :tags: dfhack
+
+Many plugins and scripts can be in a distinct enabled or disabled state. Some
+of them activate 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`
+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.
+
+Usage
+-----
+
+::
+
+    enable
+    enable <plugin> [<plugin> ...]
+
+Examples
+--------
+
+``enable manipulator``
+    Enable the ``manipulator`` plugin.
+``enable manipulator search``
+    Enable multiple plugins at once.

docs/builtins/fpause.rst

@@ -0,0 +1,15 @@
+fpause
+======
+
+.. dfhack-tool::
+    :summary: Forces DF to pause.
+    :tags: dfhack
+
+This is useful when your FPS drops below 1 and you lose control of the game.
+
+Usage
+-----
+
+::
+
+    fpause

docs/builtins/help.rst

@@ -0,0 +1,29 @@
+help
+====
+
+.. dfhack-tool::
+    :summary: Display help about a command or plugin.
+    :tags: dfhack
+
+Can also be invoked as ``?`` or ``man`` (short for "manual").
+
+Usage
+-----
+
+::
+
+    help|?|man
+    help|?|man <command or plugin>
+
+Examples
+--------
+
+::
+
+    help blueprint
+    man blueprint
+
+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``.

docs/builtins/hide.rst

@@ -0,0 +1,18 @@
+hide
+====
+
+.. dfhack-tool::
+    :summary: Hide the DFHack terminal window.
+    :tags: dfhack
+
+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

@@ -0,0 +1,61 @@
+keybinding
+==========
+
+.. dfhack-tool::
+    :summary: Create hotkeys that will run DFHack commands.
+    :tags: dfhack
+
+Like any other command, it can be used at any time from the console, but
+bindings are not remembered between runs of the game unless re-created in
+`dfhack.init`.
+
+Hotkeys can be any combinations of Ctrl/Alt/Shift with A-Z, 0-9, F1-F12, or
+``\``` (the key below the ``Esc`` key.
+
+Usage
+-----
+
+``keybinding``
+    Show some useful information, including the current game context.
+``keybinding list <key>``
+    List bindings active for the key combination.
+``keybinding clear <key> [<key>...]``
+    Remove bindings for the specified keys.
+``keybinding add <key> "cmdline" ["cmdline"...]``
+    Add bindings for the specified key.
+``keybinding set <key> "cmdline" ["cmdline"...]``
+    Clear, and then add bindings for the specified key.
+
+The ``<key>`` parameter above has the following **case-sensitive** syntax::
+
+    [Ctrl-][Alt-][Shift-]KEY[@context[|context...]]
+
+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
+the first applicable one. Later ``add`` commands, and earlier entries within one
+``add`` command have priority. Commands that are not specifically intended for
+use as a hotkey are always considered applicable.
+
+The ``context`` part in the key specifier above can be used to explicitly
+restrict the UI state where the binding would be applicable.
+
+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. when in context ``foo/bar/baz``, keybindings restricted to any
+of ``@foo/bar/baz``, ``@foo/bar``, ``@foo``, or none will be active.
+
+Multiple contexts can be specified by separating them with a pipe (``|``) - for
+example, ``@foo|bar|baz/foo`` would match anything under ``@foo``, ``@bar``, or
+``@baz/foo``.
+
+Interactive commands like `liquids` cannot be used as hotkeys.
+
+Examples
+--------
+
+``keybinding add Alt-F1 hotkeys``
+    Bind Alt-F1 to run the `hotkeys` command on any screen at any time.
+``keybinding add Alt-F@dwarfmode gui/quickfort``
+    Bind Alt-F to run `gui/quickfort`, but only when on a screen that shows the
+    main map.

docs/builtins/kill-lua.rst

@@ -0,0 +1,18 @@
+kill-lua
+========
+
+.. dfhack-tool::
+    :summary: Gracefully stop any currently-running Lua scripts.
+    :tags: dfhack
+
+Use this command to stop a misbehaving script that appears to be stuck.
+
+Usage
+-----
+
+::
+
+    kill-lua
+    kill-lua force
+
+Use ``kill-lua force`` if just ``kill-lua`` doesn't seem to work.

docs/builtins/load.rst

@@ -0,0 +1,19 @@
+load
+====
+
+.. dfhack-tool::
+    :summary: Load and register a plugin library.
+    :tags: dfhack
+
+Also see `unload` and `reload` for related actions.
+
+Usage
+-----
+
+::
+
+    load <plugin> [<plugin> ...]
+    load -a|--all
+
+You can load individual named plugins or all plugins at once. Note that plugins
+are disabled after loading/reloading until you explicitly `enable` them.

docs/builtins/ls.rst

@@ -0,0 +1,40 @@
+ls
+==
+
+.. dfhack-tool::
+    :summary: List available DFHack commands.
+    :tags: dfhack
+
+In order to group related commands, each command is associated with a list of
+tags. You can filter the listed commands by a tag or a substring of the
+command name. Can also be invoked as ``dir``.
+
+Usage
+-----
+
+``ls [<options>]``
+    Lists all available commands and the tags associated with them.
+``ls <tag> [<options>]``
+    Shows only commands that have the given tag. Use the `tags` command to see
+    the list of available tags.
+``ls <string> [<options>]``
+    Shows commands that include the given string. E.g. ``ls quick`` will show
+    all the commands with "quick" in their names. If the string is also the
+    name of a tag, then it will be interpreted as a tag name.
+
+Examples
+--------
+
+- ``ls adventure``
+    Lists all commands with the ``adventure`` tag.
+- ``ls --dev trigger``
+    Lists all commands, including developer and modding commands, that match the
+    substring "trigger"
+
+Options
+-------
+
+``--notags``
+    Don't print out the tags associated with each command.
+``--dev``
+    Include commands intended for developers and modders.

docs/builtins/plug.rst

@@ -0,0 +1,16 @@
+plug
+====
+
+.. dfhack-tool::
+    :summary: List available plugins and whether they are enabled.
+    :tags: dfhack
+
+Usage
+-----
+
+::
+
+    plug [<plugin> [<plugin> ...]]
+
+If run with parameters, it lists only the named plugins. Otherwise it will list
+all available plugins.

docs/builtins/reload.rst

@@ -0,0 +1,21 @@
+reload
+======
+
+.. dfhack-tool::
+    :summary: Reload a loaded plugin.
+    :tags: dfhack
+
+Developers use this command to reload a plugin that they are actively modifying.
+Also see `load` and `unload` for related actions.
+
+Usage
+-----
+
+::
+
+    reload <plugin> [<plugin> ...]
+    reload -a|--all
+
+You can reload individual named plugins or all plugins at once. Note that
+plugins are disabled after loading/reloading until you explicitly `enable`
+them.

docs/builtins/sc-script.rst

@@ -0,0 +1,26 @@
+sc-script
+=========
+
+.. dfhack-tool::
+    :summary: Run commands when game state changes occur.
+    :tags: dfhack
+
+This is similar to the static `init-files` but is slightly more flexible since
+it can be set dynamically.
+
+Usage
+-----
+
+``sc-script [help]``
+    Show the list of valid event names.
+``sc-script list [<event>]``
+    List the currently registered files for all events or the specified event.
+``sc-script add|remove <event> <file> [<file> ...]``
+    Register or unregister a file to be run for the specified event.
+
+Example
+-------
+
+``sc-script add SC_MAP_LOADED spawn_extra_monsters.init``
+    Registers the ``spawn_extra_monsters.init`` file to be run whenever a new
+    map is loaded.

docs/builtins/script.rst

@@ -0,0 +1,26 @@
+script
+======
+
+.. dfhack-tool::
+    :summary: Execute a batch file of DFHack commands.
+    :tags: dfhack
+
+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 input like `an init file <init-files>`.
+
+Some other tools, such as `autobutcher` and `workflow`, export their settings as
+the commands to create them - which can later be reloaded with ``script``.
+
+Usage
+-----
+
+::
+
+    script <filename>
+
+Example
+-------
+
+``script startup.txt``
+    Executes the commands in ``startup.txt``, which exists in your DF game
+    directory.

docs/builtins/show.rst

@@ -0,0 +1,19 @@
+show
+====
+
+.. dfhack-tool::
+    :summary: Unhides the DFHack terminal window.
+    :tags: dfhack
+
+Useful if you have hidden the terminal with `hide` and you want it back. Since
+the terminal window won't be available to run 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

@@ -0,0 +1,16 @@
+tags
+====
+
+.. dfhack-tool::
+    :summary: List the strings that DFHack tools can be tagged with.
+    :tags: dfhack
+
+You can find groups of related tools by passing the tag name to the `ls`
+command.
+
+Usage
+-----
+
+::
+
+    tags

docs/builtins/type.rst

@@ -0,0 +1,17 @@
+type
+====
+
+.. dfhack-tool::
+    :summary: Describe how a command is implemented.
+    :tags: dfhack
+
+DFHack commands can be provided by plugins, scripts, or by the core library
+itself. The ``type`` command can tell you which is the source of a particular
+command.
+
+Usage
+-----
+
+::
+
+    type <command>

docs/builtins/unload.rst

@@ -0,0 +1,18 @@
+unload
+======
+
+.. dfhack-tool::
+    :summary: Unload a plugin from memory.
+    :tags: dfhack
+
+Also see `load` and `reload` for related actions.
+
+Usage
+-----
+
+::
+
+    unload <plugin> [<plugin> ...]
+    unload -a|--all
+
+You can unload individual named plugins or all plugins at once.

docs/changelog.txt

@@ -39,6 +39,9 @@ changelog.txt uses a syntax similar to RST, with a few special sequences:
 
 ## New Tweaks
 
+## New Internal Commands
+- `tags`: new built-in command to list the tool category tags and their definitions. tags associated with each tool are visible in the tool help and in the output of `ls`.
+
 ## Fixes
 - ``job.removeJob()``: ensure jobs are removed from the world list when they are canceled
 
@@ -47,6 +50,7 @@ changelog.txt uses a syntax similar to RST, with a few special sequences:
 - History files: ``dfhack.history``, ``tiletypes.history``, ``lua.history``, and ``liquids.history`` have moved to the ``dfhack-config`` directory. If you'd like to keep the contents of your current history files, please move them to ``dfhack-config``.
 - `do-job-now`: new global keybinding for boosting the priority of the jobs associated with the selected building/work order/unit/item etc.: Alt-N
 - `keybinding`: support backquote (\`) as a hotkey (and assign the hotkey to the new `gui/launcher` interface)
+- `ls`: can now filter tools by substring or tag. note that dev scripts are hidden by default. pass the ``--dev`` option to show them.
 - `manipulator`: add a library of useful default professions
 - `manipulator`: move professions configuration from ``professions/`` to ``dfhack-config/professions/`` to keep it together with other dfhack configuration. If you have saved professions that you would like to keep, please manually move them to the new folder.
 - ``materials.ItemTraitsDialog``: added a default ``on_select``-handler which toggles the traits.
@@ -58,6 +62,8 @@ changelog.txt uses a syntax similar to RST, with a few special sequences:
 - `quickfort`: `Dreamfort <quickfort-blueprint-guide>` blueprint set improvements: set traffic designations to encourage dwarves to eat in the grand hall instead of the manager's office and to eat cooked food instead of raw ingredients
 
 ## Documentation
+- Update all DFHack tool documentation with standard syntax formatting, usage examples, and overall clarified text.
+- Group DFHack tools by `tag <tools>` so similar tools are grouped and easy to find
 
 ## API
 - Removed "egg" ("eggy") hook support (Linux only). The only remaining method of hooking into DF is by interposing SDL calls, which has been the method used by all binary releases of DFHack.
@@ -1056,7 +1062,7 @@ changelog.txt uses a syntax similar to RST, with a few special sequences:
 - `caravan`: documented (new in 0.44.10-alpha1)
 - `deathcause`: added "slaughtered" to descriptions
 - `fix/retrieve-units`: now re-adds units to active list to counteract `fix/dead-units`
-- `item-descriptions`: fixed several grammatical errors
+- ``item-descriptions``: fixed several grammatical errors
 - `modtools/create-unit`:
     - added quantity argument
     - now selects a caste at random if none is specified

docs/guides/examples-guide.rst

@@ -28,8 +28,8 @@ it is useful (and customizable) for any fort. It includes the following config:
 - Calls `ban-cooking` for items that have important alternate uses and should
   not be cooked. This configuration is only set when a fortress is first
   started, so later manual changes will not be overridden.
-- Automates calling of various fort maintenance and `scripts-fix`, like
+- Automates calling of various fort maintenance scripts, like `cleanowned` and
-  `cleanowned` and `fix/stuckdoors`.
+  `fix/stuckdoors`.
 - Keeps your manager orders intelligently ordered with `orders` ``sort`` so no
   orders block other orders from ever getting completed.
 - Periodically enqueues orders to shear and milk shearable and milkable pets.

docs/guides/quickfort-library-guide.rst

@@ -5,9 +5,7 @@ Blueprint Library Index
 =======================
 
 This guide contains a high-level overview of the blueprints available in the
-:source:`quickfort blueprint library <data/blueprints/library>`. You can list
+:source:`quickfort blueprint library <data/blueprints/library>`.
-library blueprints by running ``quickfort list --library`` or by hitting
-:kbd:`Alt`:kbd:`l` in the ``gui/quickfort`` file load dialog.
 
 Each file is hyperlinked to its online version so you can see exactly what the
 blueprints do before you run them. Also, if you use `gui/quickfort`, you will

docs/guides/quickfort-user-guide.rst

@@ -29,7 +29,7 @@ For those just looking to apply existing blueprints, check out the `quickfort
 command's documentation <quickfort>` for syntax. There are also many
 ready-to-use blueprints available in the ``blueprints/library`` subfolder in
 your DFHack installation. Browse them on your computer or
-:source:`online <data/blueprints/library>`, or run ``quickfort list -l`` at the
+:source:`online <data/blueprints/library>`, or run ``quickfort list`` at the
 ``[DFHack]#`` prompt to list them, and then ``quickfort run`` to apply them to
 your fort!
 

docs/plugins/3dveins.rst

@@ -0,0 +1,37 @@
+3dveins
+=======
+
+.. dfhack-tool::
+    :summary: Rewrite layer veins to expand in 3D space.
+    :tags: fort gameplay map
+
+Existing, flat veins are removed and new 3D veins that naturally span z-levels
+are generated in their place. The transformation preserves the mineral counts
+reported by `prospect`.
+
+Usage
+-----
+
+::
+
+    3dveins [verbose]
+
+The ``verbose`` option prints out extra information to the console.
+
+Example
+-------
+
+::
+
+    3dveins
+
+New veins are generated using 3D Perlin noise in order to produce a layout that
+flows smoothly between z-levels. The vein distribution is based on the world
+seed, so running 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 ``prospect all``. The amounts of layer
+stones may slightly change in some cases if vein mass shifts between z layers.
+
+The only undo option is to restore your save from backup.

docs/plugins/RemoteFortressReader.rst

@@ -0,0 +1,24 @@
+RemoteFortressReader
+====================
+
+.. dfhack-tool::
+    :summary: Backend for Armok Vision.
+    :tags: dev graphics
+    :no-command:
+
+.. dfhack-command:: RemoteFortressReader_version
+    :summary: Print the loaded RemoteFortressReader version.
+
+.. dfhack-command:: load-art-image-chunk
+    :summary: Gets an art image chunk by index.
+
+This plugin provides an API for realtime remote fortress visualization. See
+:forums:`Armok Vision <146473>`.
+
+Usage
+-----
+
+``RemoteFortressReader_version``
+    Print the loaded RemoteFortressReader version.
+``load-art-image-chunk <chunk id>``
+    Gets an art image chunk by index, loading from disk if necessary.

docs/plugins/add-spatter.rst

@@ -0,0 +1,14 @@
+add-spatter
+===========
+
+.. dfhack-tool::
+    :summary: Make tagged reactions produce contaminants.
+    :tags: adventure fort gameplay items
+    :no-command:
+
+Give some use to all those poisons that can be bought from caravans! The plugin
+automatically enables itself when you load a world with reactions that include
+names starting with ``SPATTER_ADD_``, so there are no commands to run to use it.
+These reactions will then produce contaminants on items instead of improvements.
+The contaminants are immune to being washed away by water or destroyed by
+`clean`.

docs/plugins/autobutcher.rst

@@ -0,0 +1,111 @@
+autobutcher
+===========
+
+.. dfhack-tool::
+    :summary: Automatically butcher excess livestock.
+    :tags: fort auto fps animals
+
+This plugin monitors how many pets you have of each gender and age and assigns
+excess lifestock for slaughter. It requires that you add the target race(s) to a
+watch list. Units will be ignored if they are:
+
+* Untamed
+* 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
+
+Creatures who will not reproduce (because they're not interested in the
+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 (defaults are: 1 male kid, 5 female kids, 1 male adult,
+5 female adults). Note that you may need to set a target above 1 to have a
+reliable breeding population due to asexuality etc. See `fix-ster` if this is a
+problem.
+
+Usage
+-----
+
+``enable autobutcher``
+    Start processing livestock according to the configuration. Note that
+    no races are watched by default. You have to add the ones you want to
+    monitor with ``autobutcher watch``, ``autobutcher target`` or
+    ``autobutcher autowatch``.
+``autobutcher autowatch``
+    Automatically add all new races (animals you buy from merchants, tame
+    yourself, or get from migrants) to the watch list using the default target
+    counts.
+``autobutcher noautowatch``
+    Stop auto-adding new races to the watch list.
+``autobutcher target <fk> <mk> <fa> <ma> all|new|<race> [<race> ...]``
+    Set target counts for the specified races:
+    - fk = number of female kids
+    - mk = number of male kids
+    - fa = number of female adults
+    - ma = number of female adults
+    If you specify ``all``, then this command will set the counts for all races
+    on your current watchlist (including the races which are currenly set to
+    'unwatched') and sets the new default for future watch commands. If you
+    specify ``new``, then this command just sets the new default counts for
+    future watch commands without changing your current watchlist. Otherwise,
+    all space separated races listed will be modified (or added to the watchlist
+    if they aren't there already).
+``autobutcher ticks <ticks>``
+    Change the number of ticks between scanning cycles when the plugin is
+    enabled. By default, a cycle happens every 6000 ticks (about 8 game days).
+``autobutcher watch all|<race> [<race> ...]``
+    Start watching the listed races. If they aren't already in your watchlist,
+    then they will be added with the default target counts. If you specify the
+    keyword ``all``, then all races in your watchlist that are currently marked
+    as unwatched will become watched.
+``autobutcher unwatch all|<race> [<race> ...]``
+    Stop watching the specified race(s) (or all races on your watchlist if
+    ``all`` is given). The current target settings will be remembered.
+``autobutcher forget all|<race> [<race> ...]``
+    Unwatch the specified race(s) (or all races on your watchlist if ``all`` is
+    given) and forget target settings for it/them.
+``autobutcher [list]``
+    Print status and current settings, including the watchlist. This is the
+    default command if autobutcher is run without parameters.
+``autobutcher list_export``
+    Print commands required to set the current settings in another fort.
+
+To see a list of all races, run this command:
+
+    devel/query --table df.global.world.raws.creatures.all --search ^creature_id --maxdepth 1
+
+Though not all the races listed there are tameable/butcherable.
+
+.. note::
+
+    Settings and watchlist are stored in the savegame, so you can have different
+    settings for each save. If you want to copy your watchlist to another,
+    savegame, you can export the commands required to recreate your settings.
+
+    To export, open an external terminal in the DF directory, and run
+    ``dfhack-run autobutcher list_export > filename.txt``.  To import, load your
+    new save and run ``script filename.txt`` in the DFHack terminal.
+
+Examples
+--------
+
+Keep at most 7 kids (4 female, 3 male) and at most 3 adults (2 female, 1 male)
+for turkeys. Once the kids grow up, the oldest adults will get slaughtered.
+Excess kids will get slaughtered starting the the youngest to allow that the
+older ones grow into adults::
+
+    autobutcher target 4 3 2 1 BIRD_TURKEY
+
+Configure useful limits for dogs, cats, geese (for eggs, leather, and bones),
+alpacas, sheep, and llamas (for wool), and pigs (for milk and meat). All other
+unnamed tame units will be marked for slaughter as soon as they arrive in your
+fortress::
+
+    enable autobutcher
+    autobutcher target 2 2 2 2 DOG
+    autobutcher target 1 1 2 2 CAT
+    autobutcher target 50 50 14 2 BIRD_GOOSE
+    autobutcher target 2 2 4 2 ALPACA SHEEP LLAMA
+    autobutcher target 5 5 6 2 PIG
+    autobutcher target 0 0 0 0 new
+    autobutcher autowatch

docs/plugins/autochop.rst

@@ -0,0 +1,27 @@
+autochop
+========
+
+.. dfhack-tool::
+    :summary: Auto-harvest trees when low on stockpiled logs.
+    :tags: fort auto plants
+    :no-command:
+
+This plugin can designate trees for chopping when your stocks are low on logs.
+
+Usage
+-----
+
+::
+
+    enable autochop
+
+Then, open the settings menu with :kbd:`c` from the designations menu (the
+option appears when you have "Chop Down Trees" selected with :kbd:`d`-:kbd:`t`).
+
+Set your desired thresholds and enable autochopping with :kbd:`a`.
+
+You can also restrict autochopping to specific burrows. Highlight a burrow name
+with the Up/Down arrow keys and hit :kbd:`Enter` to mark it as the autochop
+burrrow.
+
+Autochop checks your stock of logs and designates trees once every in game day.

docs/plugins/autoclothing.rst

@@ -0,0 +1,32 @@
+autoclothing
+============
+
+.. dfhack-tool::
+    :summary: Automatically manage clothing work orders.
+    :tags: fort auto workorders
+
+This command allows you to set how many of each clothing type every citizen
+should have.
+
+Usage
+-----
+
+::
+
+    autoclothing
+    autoclothing <material> <item> [quantity]
+
+``material`` can be "cloth", "silk", "yarn", or "leather". The ``item`` can be
+anything your civilization can produce, such as "dress" or "mitten".
+
+When invoked without parameters, it shows a summary of all managed clothing
+orders. When invoked with a material and item, but without a quantity, it shows
+the current configuration for that material and item.
+
+Examples
+--------
+
+``autoclothing cloth "short skirt" 10``
+    Sets the desired number of cloth short skirts available per citizen to 10.
+``autoclothing cloth dress``
+    Displays the currently set number of cloth dresses chosen per citizen.

docs/plugins/autodump.rst

@@ -0,0 +1,71 @@
+autodump
+========
+
+.. dfhack-tool::
+    :summary: Automatically set items in a stockpile to be dumped.
+    :tags: fort armok fps productivity items stockpiles
+    :no-command:
+
+.. dfhack-command:: autodump
+    :summary: Teleports items marked for dumping to the cursor position.
+
+.. dfhack-command:: autodump-destroy-here
+    :summary: Destroy items marked for dumping under the cursor.
+
+.. dfhack-command:: autodump-destroy-item
+    :summary: Destroys the selected item.
+
+When `enabled <enable>`, this plugin adds an option to the :kbd:`q` menu for
+stockpiles. When the ``autodump`` option is selected for the stockpile, any
+items placed in the stockpile will automatically be designated to be dumped.
+
+When invoked as a command, it can instantly move all unforbidden items marked
+for dumping to the tile under the cursor. After moving the items, the dump flag
+is unset and the forbid flag is set, just as if it had been dumped normally. Be
+aware that dwarves that are en route to pick up the item for dumping may still
+come and move the item to your dump zone.
+
+The cursor must be placed on a floor tile so the items can be dumped there.
+
+Usage
+-----
+
+::
+
+    enable autodump
+    autodump [<options>]
+    autodump-destroy-here
+    autodump-destroy-item
+
+``autodump-destroy-here`` is an alias for ``autodump destroy-here`` and is
+intended for use as a keybinding.
+
+``autodump-destroy-item`` destroys only the selected item. The item may be
+selected in the :kbd:`k` list or in the container item list. If called again
+before the game is resumed, cancels destruction of the item.
+
+Options
+-------
+
+``destroy``
+    Destroy instead of dumping. Doesn't require a cursor. If ``autodump`` is
+    called again with this option before the game is resumed, it cancels
+    pending destroy actions.
+``destroy-here``
+    Destroy items marked for dumping under the cursor.
+``visible``
+    Only process items that are not hidden.
+``hidden``
+    Only process hidden items.
+``forbidden``
+    Only process forbidden items (default: only unforbidden).
+
+Examples
+--------
+
+``autodump``
+    Teleports items marked for dumping to the cursor position.
+``autodump destroy``
+    Destroys all unforbidden items marked for dumping
+``autodump-destroy-item``
+    Destroys the selected item.

docs/plugins/autofarm.rst

@@ -0,0 +1,37 @@
+autofarm
+========
+
+.. dfhack-tool::
+    :summary: Automatically manage farm crop selection.
+    :tags: fort auto plants
+
+Periodically scan your plant stocks and assign crops to your farm plots based on
+which plant stocks are low (as long as you have the appropriate seeds). The
+target threshold for each crop type is configurable.
+
+Usage
+-----
+
+``enable autofarm``
+    Enable the plugin and start managing crop assignment.
+``autofarm runonce``
+    Updates all farm plots once, without enabling the plugin.
+``autofarm status``
+    Prints status information, including any defined thresholds.
+``autofarm default <number>``
+    Sets the default threshold.
+``autofarm threshold <number> <type> [<type> ...]``
+    Sets thresholds of individual plant types.
+
+You can find the identifiers for the crop types in your world by running the
+following command::
+
+    lua "for _,plant in ipairs(df.global.world.raws.plants.all) do if plant.flags.SEED then print(plant.id) end end"
+
+Examples
+--------
+
+``autofarm default 30``
+    Set the default threshold to 30.
+``autofarm threshold 150 MUSHROOM_HELMET_PLUMP GRASS_TAIL_PIG``
+    Set the threshold for Plump Helmets and Pig Tails to 150

docs/plugins/autogems.rst

@@ -0,0 +1,26 @@
+autogems
+========
+
+.. dfhack-tool::
+    :summary: Automatically cut rough gems.
+    :tags: fort auto workorders
+    :no-command:
+
+.. dfhack-command:: autogems-reload
+    :summary: Reloads the autogems configuration file.
+
+Automatically cut rough gems. This plugin periodically scans your stocks of
+rough gems and creates manager orders for cutting them at a Jeweler's Workshop.
+
+Usage
+-----
+
+``enable autogems``
+    Enables the plugin and starts autocutting gems according to its
+    configuration.
+``autogems-reload``
+    Reloads the autogems configuration file. You might need to do this if you
+    have manually modified the contents while the game is running.
+
+Run `gui/autogems` for a configuration UI, or access the ``Auto Cut Gems``
+option from the Current Workshop Orders screen (:kbd:`o`-:kbd:`W`).

docs/plugins/autohauler.rst

@@ -0,0 +1,57 @@
+autohauler
+==========
+
+.. dfhack-tool::
+    :summary: Automatically manage hauling labors.
+    :tags: fort auto labors
+
+Similar to `autolabor`, but instead of managing all labors, ``autohauler`` only
+addresses hauling labors, leaving the assignment of skilled labors entirely up
+to you. You can use the in-game `manipulator` UI or an external tool like Dwarf
+Therapist to do so.
+
+Idle dwarves who are not on active military duty will be assigned the hauling
+labors; everyone else (including those currently hauling) will have the hauling
+labors removed. This is to encourage every dwarf to do their assigned skilled
+labors whenever possible, but resort to hauling when those jobs are not
+available. This also implies that the user will have a very tight skill
+assignment, with most skilled labors only being assigned to just a few dwarves
+and almost every non-military dwarf having at least one skilled labor assigned.
+
+Autohauler allows a skill to be used as a flag to exempt a dwarf from
+``autohauler``'s effects. By default, this is the unused ALCHEMIST labor, but it
+can be changed by the user.
+
+Usage
+-----
+
+``enable autohauler``
+    Start managing hauling labors. This is normally all you need to do.
+    Autohauler works well on default settings.
+``autohauler status``
+    Show autohauler status and status of fort dwarves.
+``autohauler <labor> haulers``
+    Set whether a particular labor should be assigned to haulers.
+``autohauler <labor> allow|forbid``
+    Set whether a particular labor should mark a dwarf as exempt from hauling.
+    By default, only the ``ALCHEMIST`` labor is set to ``forbid``.
+``autohauler reset-all|<labor> reset``
+    Reset a particular labor (or all labors) to their default
+    haulers/allow/forbid state.
+``autohauler list``
+    Show the active configuration for all labors.
+``autohauler frameskip <number>``
+    Set the number of frames between runs of autohauler.
+``autohauler debug``
+    In the next cycle, output the state of every dwarf.
+
+Examples
+--------
+
+``autohauler HAUL_STONE haulers``
+    Set stone hauling as a hauling labor (this is already the default).
+``autohauler RECOVER_WOUNDED allow``
+    Allow the "Recover wounded" labor to be manually assigned by the player. By
+    default it is automatically given to haulers.
+``autohauler MINE forbid``
+    Don't assign hauling labors to dwarves with the Mining labor enabled.

docs/plugins/autolabor.rst

@@ -0,0 +1,92 @@
+autolabor
+=========
+
+.. dfhack-tool::
+    :summary: Automatically manage dwarf labors.
+    :tags: fort auto labors
+
+Autolabor attempts to keep as many dwarves as possible busy while allowing
+dwarves to specialize in specific skills.
+
+Autolabor frequently checks how many jobs of each type are available and sets
+labors proportionally in order to get them all done quickly. Labors with
+equipment -- mining, hunting, and woodcutting -- which are abandoned if labors
+change mid-job, are handled slightly differently to minimise churn.
+
+Dwarves on active military duty or dwarves assigned to burrows are left
+untouched by autolabor.
+
+.. warning::
+
+    autolabor will override any manual changes you make to labors while it is
+    enabled, including through other tools such as Dwarf Therapist.
+
+Usage
+-----
+
+::
+
+    enable autolabor
+
+Anything beyond this is optional - autolabor works well with the default
+settings. Once you have enabled it in a fortress, it stays enabled until you
+explicitly disable it, even if you save and reload your game.
+
+By default, each labor is assigned to between 1 and 200 dwarves (2-200 for
+mining). 33% of the workforce become haulers, who handle all hauling jobs as
+well as cleaning, pulling levers, recovering wounded, removing constructions,
+and filling ponds. Other jobs are automatically assigned as described above.
+Each of these settings can be adjusted.
+
+Jobs are rarely assigned to nobles with responsibilities for meeting diplomats
+or merchants, never to the chief medical dwarf, and less often to the bookeeper
+and manager.
+
+Hunting is never assigned without a butchery, and fishing is never assigned
+without a fishery.
+
+For each labor, a preference order is calculated based on skill, biased against
+masters of other trades and excluding those who can't do the job. The labor is
+then added to the best <minimum> dwarves for that labor, then to additional
+dwarfs that meet any of these conditions:
+
+* The dwarf is idle and there are no idle dwarves assigned to this labor
+* The dwarf has non-zero skill associated with the labor
+* The labor is mining, hunting, or woodcutting and the dwarf currently has it enabled.
+
+We stop assigning dwarves when we reach the maximum allowed.
+
+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.
+
+Advanced usage
+--------------
+
+``autolabor list``
+    List current status of all labors. Use this command to see the IDs for all
+    labors.
+``autolabor status``
+    Show basic status information.
+``autolabor <labor> <minimum> [<maximum>] [<talent pool>]``
+    Set range of dwarves assigned to a labor, optionally specifying the size of
+    the pool of most skilled dwarves that will ever be considered for this
+    labor.
+``autolabor <labor> haulers``
+    Set a labor to be handled by hauler dwarves.
+``autolabor <labor> disable``
+    Turn off autolabor for a specific labor.
+``autolabor reset-all|<labor> reset``
+    Return a labor (or all labors) to the default handling.
+
+See `autolabor-artisans` for a differently-tuned setup.

docs/plugins/automaterial.rst

@@ -0,0 +1,53 @@
+automaterial
+============
+
+.. dfhack-tool::
+    :summary: Sorts building materials by recent usage.
+    :tags: fort design productivity buildings map
+    :no-command:
+
+This plugin makes building constructions (walls, floors, fortifications, etc)
+much easier by saving you from having to trawl through long lists of materials
+each time you place one.
+
+It moves the last used material for a given construction type to the top of the
+list, if there are any left. So if you build a wall with chalk blocks, the next
+time you place a wall the chalk blocks will be at the top of the list,
+regardless of distance (it only does this in "grouped" mode, as individual item
+lists could be huge). This means you can place most constructions without having
+to search for your preferred material type.
+
+Usage
+-----
+
+::
+
+    enable automaterial
+
+.. image:: ../images/automaterial-mat.png
+
+Pressing :kbd:`a` while highlighting any material will enable that material for
+"auto select" for this construction type. You can enable multiple materials. Now
+the next time you place this type of construction, the plugin will automatically
+choose materials for you from the kinds you enabled. If there is enough to
+satisfy the whole placement, you won't be prompted with the material screen at
+all -- the construction will be placed and you will be back in the construction
+menu.
+
+When choosing the construction placement, you will see a couple of options:
+
+.. image:: ../images/automaterial-pos.png
+
+Use :kbd:`a` here to temporarily disable the material autoselection, e.g. if you
+need to go to the material selection screen so you can toggle some materials on
+or off.
+
+The other option (auto type selection, off by default) can be toggled on with
+:kbd:`t`. If you toggle this option on, instead of returning you to the main
+construction menu after selecting materials, it returns you back to this screen.
+If you use this along with several autoselect enabled materials, you should be
+able to place complex constructions more conveniently.
+
+The ``automaterial`` plugin also enables extra contruction placement modes, such
+as designating areas larger than 10x10 and allowing you to designate hollow
+rectangles instead of the default filled ones.

docs/plugins/automelt.rst

@@ -0,0 +1,18 @@
+automelt
+========
+
+.. dfhack-tool::
+    :summary: Quickly designate items to be melted.
+    :tags: fort productivity items stockpiles
+    :no-command:
+
+When `enabled <enable>`, this plugin adds an option to the :kbd:`q` menu for
+stockpiles. When the ``automelt`` option is selected for the stockpile, any
+items placed in the stockpile will automatically be designated to be melted.
+
+Usage
+-----
+
+::
+
+    enable automelt

docs/plugins/autonestbox.rst

@@ -0,0 +1,33 @@
+autonestbox
+===========
+
+.. dfhack-tool::
+    :summary: Auto-assign egg-laying female pets to nestbox zones.
+    :tags: fort auto animals
+
+To use this feature, you must create pen/pasture zones above nestboxes. If the
+pen is bigger than 1x1, the nestbox must be in the top left corner. Only 1 unit
+will be assigned per pen, regardless of the size. Egg layers who are also
+grazers will be ignored, since confining them to a 1x1 pasture is not a good
+idea. Only tame and domesticated own units are processed since pasturing
+half-trained wild egg layers could destroy your neat nestbox zones when they
+revert to wild.
+
+Note that the age of the units is not checked, so you might get some egg-laying
+kids assigned to the nestbox zones. Most birds grow up quite fast, though, so
+they should be adults and laying eggs soon enough.
+
+Usage
+-----
+
+``enable autonestbox``
+    Start checking for unpastured egg-layers and assigning them to nestbox
+    zones.
+``autonestbox``
+    Print current status.
+``autonestbox now``
+    Run a scan and assignment cycle right now. Does not require that the plugin
+    is enabled.
+``autonestbox ticks <ticks>``
+    Change the number of ticks between scan and assignment cycles when the
+    plugin is enabled. The default is 6000 (about 8 days).

docs/plugins/autotrade.rst

@@ -0,0 +1,18 @@
+autotrade
+=========
+
+.. dfhack-tool::
+    :summary: Quickly designate items to be traded.
+    :tags: fort productivity items stockpiles
+    :no-command:
+
+When `enabled <enable>`, this plugin adds an option to the :kbd:`q` menu for
+stockpiles. When the ``autotrade`` option is selected for the stockpile, any
+items placed in the stockpile will automatically be designated to be traded.
+
+Usage
+-----
+
+::
+
+    enable autotrade

docs/plugins/blueprint.rst

@@ -0,0 +1,133 @@
+blueprint
+=========
+
+.. dfhack-tool::
+    :summary: Record a live game map in a quickfort blueprint.
+    :tags: fort design buildings map stockpiles
+
+With ``blueprint``, you can export the structure of a portion of your fortress
+in a blueprint file that you (or anyone else) can later play back with
+`quickfort`.
+
+Blueprints are ``.csv`` or ``.xlsx`` files created in the ``blueprints``
+subdirectory of your DF folder. The map area to turn into a blueprint is either
+selected interactively with the ``blueprint gui`` command or, if the GUI is not
+used, starts at the active cursor location and extends right and down for the
+requested width and height.
+
+Usage
+-----
+
+::
+
+    blueprint <width> <height> [<depth>] [<name> [<phases>]] [<options>]
+    blueprint gui [<name> [<phases>]] [<options>]
+
+Examples
+--------
+
+``blueprint gui``
+    Runs `gui/blueprint`, the interactive frontend, where all configuration for
+    a ``blueprint`` command can be set visually and interactively.
+``blueprint 30 40 bedrooms``
+    Generates blueprints for an area 30 tiles wide by 40 tiles tall, starting
+    from the active cursor on the current z-level. Blueprints are written to
+    ``bedrooms.csv`` in the ``blueprints`` directory.
+``blueprint 30 40 bedrooms dig --cursor 108,100,150``
+    Generates only the ``#dig`` blueprint in the ``bedrooms.csv`` file, and
+    the start of the blueprint area is set to a specific value instead of using
+    the in-game cursor position.
+
+Positional parameters
+---------------------
+
+``width``
+    Width of the area (in tiles) to translate.
+``height``
+    Height of the area (in tiles) to translate.
+``depth``
+    Number of z-levels to translate. Positive numbers go *up* from the cursor
+    and negative numbers go *down*. Defaults to 1 if not specified, indicating
+    that the blueprint should only include the current z-level.
+``name``
+    Base name for blueprint files created in the ``blueprints`` directory. If no
+    name is specified, "blueprint" is used by default. The string must contain
+    some characters other than numbers so the name won't be confused with the
+    optional ``depth`` parameter.
+
+Phases
+------
+
+If you want to generate blueprints only for specific phases, add their names to
+the commandline, anywhere after the blueprint base name. You can list multiple
+phases; just separate them with a space.
+
+``dig``
+    Generate quickfort ``#dig`` blueprints for digging natural stone.
+``carve``
+    Generate quickfort ``#dig`` blueprints for smoothing and carving.
+``build``
+    Generate quickfort ``#build`` blueprints for constructions and buildings.
+``place``
+    Generate quickfort ``#place`` blueprints for placing stockpiles.
+``zone``
+    Generate quickfort ``#zone`` blueprints for designating zones.
+``query``
+    Generate quickfort ``#query`` blueprints for configuring rooms.
+
+If no phases are specified, phases are autodetected. For example, a ``#place``
+blueprint will be created only if there are stockpiles in the blueprint area.
+
+Options
+-------
+
+``-c``, ``--cursor <x>,<y>,<z>``
+    Use the specified map coordinates instead of the current cursor position for
+    the upper left corner of the blueprint range. If this option is specified,
+    then an active game map cursor is not necessary.
+``-e``, ``--engrave``
+    Record engravings in the ``carve`` phase. If this option is not specified,
+    engravings are ignored.
+``-f``, ``--format <format>``
+    Select the output format of the generated files. See the `Output formats`_
+    section below for options. If not specified, the output format defaults to
+    "minimal", which will produce a small, fast ``.csv`` file.
+``-h``, ``--help``
+    Show command help text.
+``-s``, ``--playback-start <x>,<y>,<comment>``
+    Specify the column and row offsets (relative to the upper-left corner of the
+    blueprint, which is ``1,1``) where the player should put the cursor when the
+    blueprint is played back with `quickfort`, in
+    `quickfort start marker <quickfort-start>` format, for example:
+    ``10,10,central stairs``. If there is a space in the comment, you will need
+    to surround the parameter string in double quotes:
+    ``"-s10,10,central stairs"`` or ``--playback-start "10,10,central stairs"``
+    or ``"--playback-start=10,10,central stairs"``.
+``-t``, ``--splitby <strategy>``
+    Split blueprints into multiple files. See the `Splitting output into
+    multiple files`_ section below for details. If not specified, defaults to
+    "none", which will create a standard quickfort
+    `multi-blueprint <quickfort-packaging>` file.
+
+Output formats
+--------------
+
+Here are the values that can be passed to the ``--format`` flag:
+
+``minimal``
+    Creates ``.csv`` files with minimal file size that are fast to read and
+    write. This is the default.
+``pretty``
+    Makes the blueprints in the ``.csv`` files easier to read and edit with a
+    text editor by adding extra spacing and alignment markers.
+
+Splitting output into multiple files
+------------------------------------
+
+The ``--splitby`` flag can take any of the following values:
+
+``none``
+    Writes all blueprints into a single file. This is the standard format for
+    quickfort fortress blueprint bundles and is the default.
+``phase``
+    Creates a separate file for each phase.

docs/plugins/building-hacks.rst

@@ -0,0 +1,9 @@
+building-hacks
+==============
+
+.. dfhack-tool::
+    :summary: Provides a Lua API for creating powered workshops.
+    :tags: fort gameplay buildings
+    :no-command:
+
+See `building-hacks-api` for more details.

docs/plugins/buildingplan.rst

@@ -0,0 +1,92 @@
+buildingplan
+============
+
+.. dfhack-tool::
+    :summary: Plan building construction before you have materials.
+    :tags: fort design buildings
+
+This plugin adds a planning mode for building placement. You can then place
+furniture, constructions, and other buildings before the required materials are
+available, and they will be created in a suspended state. Buildingplan will
+periodically scan for appropriate items, and the jobs will be unsuspended when
+the items are available.
+
+This is very useful when combined with manager work orders or `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. Materials are used to build the
+planned buildings as they are produced, with minimal space dedicated to
+stockpiles.
+
+Usage
+-----
+
+::
+
+    enable buildingplan
+    buildingplan set
+    buildingplan set <setting> true|false
+
+Running ``buildingplan set`` without parameters displays the current settings.
+
+.. _buildingplan-settings:
+
+Global settings
+---------------
+
+The buildingplan plugin has global settings that can be set from the UI
+(:kbd:`G` from any building placement screen, for example:
+:kbd:`b`:kbd:`a`:kbd:`G`). These settings can also be set via the
+``buildingplan set`` command. The available settings are:
+
+``all_enabled`` (default: false)
+    Enable planning mode for all building types.
+``blocks``, ``boulders``, ``logs``, ``bars`` (defaults: true, true, true, false)
+    Allow blocks, boulders, logs, or bars to be matched for generic "building
+    material" items.
+``quickfort_mode`` (default: false)
+    Enable compatibility mode for the legacy Python Quickfort (this setting is
+    not required for DFHack `quickfort`)
+
+The settings for ``blocks``, ``boulders``, ``logs``, and ``bars`` are saved with
+your fort, so you only have to set them once and they will be persisted in your
+save.
+
+If you normally embark with some blocks on hand for early workshops, you might
+want to add this line to your ``dfhack-config/init/onMapLoad.init`` file to
+always configure buildingplan to just use blocks for buildings and
+constructions::
+
+    on-new-fortress buildingplan set boulders false; buildingplan set logs false
+
+.. _buildingplan-filters:
+
+Item filtering
+--------------
+
+While placing a building, you can set filters for what materials you want the
+building made out of, what quality you want the component items to be, and
+whether you want the items to be decorated.
+
+If a building type takes more than one item to construct, use
+:kbd:`Ctrl`:kbd:`Left` and :kbd:`Ctrl`:kbd:`Right` to select the item that you
+want to set filters for. Any filters that you set will be used for all buildings
+of the selected type placed from that point onward (until you set a new filter
+or clear the current one). Buildings placed before the filters were changed will
+keep the filter values that were set when the building was placed.
+
+For example, you can be sure that all your constructed walls are the same color
+by setting a filter to accept only certain types of stone.
+
+Quickfort mode
+--------------
+
+If you use the external Python Quickfort to apply building blueprints instead of
+the native DFHack `quickfort` script, you must enable Quickfort mode. This
+temporarily enables buildingplan for all building types and adds an extra blank
+screen after every building placement. This "dummy" screen is needed for Python
+Quickfort to interact successfully with Dwarf Fortress.
+
+Note that Quickfort mode is only for compatibility with the legacy Python
+Quickfort. The DFHack `quickfort` script does not need this Quickfort mode to be
+enabled. The `quickfort` script will successfully integrate with buildingplan as
+long as the buildingplan plugin itself is enabled.

docs/plugins/burrows.rst

@@ -0,0 +1,54 @@
+burrows
+=======
+
+.. dfhack-tool::
+    :summary: Auto-expand burrows as you dig.
+    :tags: fort auto design productivity map units
+    :no-command:
+
+.. dfhack-command:: burrow
+    :summary: Quickly add units/tiles to burrows.
+
+When a wall inside a burrow with a name ending in ``+`` is dug out, the burrow
+will be extended to newly-revealed adjacent walls.
+
+Usage
+-----
+
+``burrow enable auto-grow``
+    When a wall inside a burrow with a name ending in '+' is dug out, the burrow
+    will be extended to newly-revealed adjacent walls. This final '+' may be
+    omitted in burrow name args of other ``burrow`` commands. Note that digging
+    1-wide corridors with the miner inside the burrow is SLOW.
+``burrow disable auto-grow``
+    Disables auto-grow processing.
+``burrow clear-unit <burrow> [<burrow> ...]``
+    Remove all units from the named burrows.
+``burrow clear-tiles <burrow> [<burrow> ...]``
+    Remove all tiles from the named burrows.
+``burrow set-units target-burrow <burrow> [<burrow> ...]``
+    Clear all units from the target burrow, then add units from the named source
+    burrows.
+``burrow add-units target-burrow <burrow> [<burrow> ...]``
+    Add units from the source burrows to the target.
+``burrow remove-units target-burrow <burrow> [<burrow> ...]``
+    Remove units in source burrows from the target.
+``burrow set-tiles target-burrow <burrow> [<burrow> ...]``
+    Clear target burrow tiles and adds tiles from the names source burrows.
+``burrow add-tiles target-burrow <burrow> [<burrow> ...]``
+    Add tiles from the source burrows to the target.
+``burrow remove-tiles target-burrow <burrow> [<burrow> ...]``
+    Remove tiles in source burrows from the target.
+
+In place of a source burrow, you can use one of the following keywords:
+
+- ``ABOVE_GROUND``
+- ``SUBTERRANEAN``
+- ``INSIDE``
+- ``OUTSIDE``
+- ``LIGHT``
+- ``DARK``
+- ``HIDDEN``
+- ``REVEALED``
+
+to add tiles with the given properties.

docs/plugins/changeitem.rst

@@ -0,0 +1,44 @@
+changeitem
+==========
+
+.. dfhack-tool::
+    :summary: Change item material or base quality.
+    :tags: adventure fort armok items
+
+By default, a change is only allowed if the existing and desired item materials
+are of the same subtype (for example wood -> wood, stone -> stone, etc). But
+since some transformations work pretty well and may be desired you can override
+this with ``force``. Note that forced changes can possibly result in items that
+crafters and haulers refuse to touch.
+
+Usage
+-----
+
+``changeitem info``
+   Show details about the selected item. Does not change the item. You can use
+   this command to discover RAW ids for existing items.
+``changeitem [<options>]``
+   Change the item selected in the ``k`` list or inside a container/inventory.
+``changeitem here [<options>]``
+   Change all items at the cursor position. Requires in-game cursor.
+
+Examples
+--------
+
+``changeitem here m INORGANIC:GRANITE``
+   Change material of all stone items under the cursor to granite.
+``changeitem q 5``
+   Change currently selected item to masterpiece quality.
+
+Options
+-------
+
+``m``, ``material <RAW id>``
+   Change material. Must be followed by valid material RAW id.
+``s``, ``subtype <RAW id>``
+   Change subtype. Must be followed by a valid subtype RAW id."
+``q``, ``quality <quality>``
+   Change base quality. Must be followed by number (0-5) with 0 being no quality
+   and 5 being masterpiece quality.
+``force``
+   Ignore subtypes and force the change to the new material.

docs/plugins/changelayer.rst

@@ -0,0 +1,76 @@
+changelayer
+===========
+
+.. dfhack-tool::
+    :summary: Change the material of an entire geology layer.
+    :tags: fort armok map
+
+Note that one layer can stretch across many z-levels, and changes to the geology
+layer will affect all surrounding regions, not just your embark! Mineral veins
+and gem clusters will not be affected. Use `changevein` if you want to modify
+those.
+
+tl;dr: You will end up with changing large areas in one go, especially if you
+use it in lower z levels. Use this command with care!
+
+Usage
+-----
+
+::
+
+   changelayer <material RAW id> [<options>]
+
+When run without options, ``changelayer`` will:
+
+- only affect the geology layer at the current cursor position
+- only affect the biome that covers the current cursor position
+- not allow changing stone to soil and vice versa
+
+You can use the `probe` command on various tiles around your map to find valid
+material RAW ids and to get an idea how layers and biomes are distributed.
+
+Examples
+--------
+
+``changelayer GRANITE``
+   Convert the layer at the cursor position into granite.
+``changelayer SILTY_CLAY force``
+   Convert teh layer at the cursor position into clay, even if it's stone.
+``changelayer MARBLE all_biomes all_layers``
+   Convert all layers of all biomes which are not soil into marble.
+
+.. note::
+
+    * If you use changelayer and nothing happens, try to pause/unpause the game
+      for a while and move the cursor to another tile. Then try again. If that
+      doesn't help, then try to temporarily change some other layer, undo your
+      changes, and try again for the layer you want to change. Saving and
+      reloading your map also sometimes helps.
+    * You should be fine if you only change single layers without the use
+      of 'force'. Still, it's advisable to save your game before messing with
+      the map.
+    * When you force changelayer to convert soil to stone, you might see some
+      weird stuff (flashing tiles, tiles changed all over place etc). Try
+      reverting the changes manually or even better use an older savegame. You
+      did save your game, right?
+
+Options
+-------
+
+``all_biomes``
+   Change the corresponding geology layer for all biomes on your map. Be aware
+   that the same geology layer can AND WILL be on different z-levels for
+   different biomes.
+``all_layers``
+   Change all geology layers on your map (only for the selected biome unless
+   ``all_biomes`` is also specified). Candy mountain, anyone? Will make your map
+   quite boring, but tidy.
+``force``
+   Allow changing stone to soil and vice versa. **THIS CAN HAVE WEIRD EFFECTS,
+   USE WITH CARE AND SAVE FIRST**. Note that soil will not be magically replaced
+   with stone. You will, however, get a stone floor after digging, so it will
+   allow the floor to be engraved. Similarly, stone will not be magically
+   replaced with soil, but you will get a soil floor after digging, so it could
+   be helpful for creating farm plots on maps with no soil.
+``verbose``
+   Output details about what is being changed.

docs/plugins/changevein.rst

@@ -0,0 +1,26 @@
+changevein
+==========
+
+.. dfhack-tool::
+    :summary: Change the material of a mineral inclusion.
+    :tags: fort armok map
+
+You can change a vein to any incorganic material RAW id. Note that this command
+only affects tiles within the current 16x16 block - for large veins and
+clusters, you will need to use this command multiple times.
+
+You can use the `probe` command to discover the material RAW ids for existing
+veins that you want to duplicate.
+
+Usage
+-----
+
+::
+
+    changevein <material RAW id>
+
+Example
+-------
+
+``changevein NATIVE_PLATINUM``
+    Convert vein at cursor position into platinum ore.

docs/plugins/cleanconst.rst

@@ -0,0 +1,18 @@
+cleanconst
+==========
+
+.. dfhack-tool::
+    :summary: Cleans up construction materials.
+    :tags: fort fps buildings
+
+This tool alters all constructions on the map so that they spawn their building
+component when they are disassembled, allowing their actual build items to be
+safely deleted. This can improve FPS when you have many constructions on the
+map.
+
+Usage
+-----
+
+::
+
+    cleanconst

docs/plugins/cleaners.rst

@@ -0,0 +1,57 @@
+.. _clean:
+.. _spotclean:
+
+cleaners
+========
+
+.. dfhack-tool::
+    :summary: Provides commands for cleaning spatter from the map.
+    :tags: adventure fort armok fps items map units
+    :no-command:
+
+.. dfhack-command:: clean
+    :summary: Removes contaminants.
+
+.. dfhack-command:: spotclean
+    :summary: Remove all contaminants from the tile under the cursor.
+
+This plugin provides commands that clean the splatter that get scattered all
+over the map and that clings to your items and units. In an old fortress,
+cleaning with this tool can significantly reduce FPS lag! It can also spoil your
+!!FUN!!, so think before you use it.
+
+Usage
+-----
+
+::
+
+    clean all|map|items|units|plants [<options>]
+    spotclean
+
+By default, cleaning the map leaves mud and snow alone. Note that cleaning units
+includes hostiles, and that cleaning items removes poisons from weapons.
+
+``spotclean`` works like ``clean map snow mud``, removing all contaminants from
+the tile under the cursor. This is ideal if you just want to clean a specific
+tile but don't want the `clean` command to remove all the glorious blood from
+your entranceway.
+
+Examples
+--------
+
+``clean all``
+    Clean everything that can be cleaned (except mud and snow).
+``clean all mud item snow``
+    Removes all spatter, including mud, leaves, and snow from map tiles.
+
+Options
+-------
+
+When cleaning the map, you can specify extra options for extra cleaning:
+
+``mud``
+    Also remove mud.
+``item``
+    Also remove item spatter, like fallen leaves and flowers.
+``snow``
+    Also remove snow coverings.

docs/plugins/cleanowned.rst

@@ -0,0 +1,41 @@
+cleanowned
+==========
+
+.. dfhack-tool::
+    :summary: Confiscates and dumps garbage owned by dwarves.
+    :tags: fort productivity items
+
+This tool gets dwarves to give up ownership of scattered items and items with
+heavy wear and then marks those items for dumping. Now you can finally get your
+dwarves to give up their rotten food and tattered loincloths and go get new
+ones!
+
+Usage
+-----
+
+::
+
+    cleanowned [<types>] [dryrun]
+
+When run without parameters, ``cleanowned`` will confiscate and dump rotten
+items and owned food that is left behind on the floor. Specify the ``dryrun``
+parameter to just print out what would be done, but don't actually confiscate
+anything.
+
+You can confiscate additional types of items by adding them to the commandline:
+
+``scattered``
+    Confiscate/dump all items scattered on the floor.
+``x``
+    Confiscate/dump items with wear level 'x' (lightly worn) and more.
+``X``
+    Confiscate/dump items with wear level 'X' (heavily worn) and more.
+
+Or you can confiscate all owned items by specifying ``all``.
+
+Example
+-------
+
+``cleanowned scattered X``
+    Confiscate and dump rotten and dropped food, garbage on the floors, and any
+    worn items with 'X' damage and above.

docs/plugins/command-prompt.rst

@@ -0,0 +1,22 @@
+command-prompt
+==============
+
+.. dfhack-tool::
+    :summary: An in-game DFHack terminal where you can run other commands.
+    :tags: dfhack
+
+Usage
+-----
+
+::
+
+    command-prompt [entry]
+
+If called with parameters, it starts with that text in the command edit area.
+This is most useful for developers, who can set a keybinding to open a laungage
+interpreter for lua or Ruby by starting with the `:lua <lua>` or `:rb <rb>`
+portions of the command already filled in.
+
+Also see `gui/quickcmd` for a different take on running commands from the UI.
+
+.. image:: ../images/command-prompt.png

docs/plugins/confirm.rst

@@ -0,0 +1,20 @@
+confirm
+=======
+
+.. dfhack-tool::
+    :summary: Adds confirmation dialogs for destructive actions.
+    :tags: fort interface
+
+Now you can get the chance to avoid seizing goods from traders or deleting a
+hauling route in case you hit the key accidentally.
+
+Usage
+-----
+
+``enable confirm``, ``confirm enable all``
+    Enable all confirmation options. Replace with ``disable`` to disable all.
+``confirm enable option1 [option2...]``
+    Enable (or ``disable``) specific confirmation dialogs.
+
+When run without parameters, ``confirm`` will report which confirmation dialogs
+are currently enabled.

docs/plugins/createitem.rst

@@ -0,0 +1,54 @@
+createitem
+==========
+
+.. dfhack-tool::
+    :summary: Create arbitrary items.
+    :tags: adventure fort armok items
+
+You can create new items of any type and made of any material. A unit must be
+selected in-game to use this command. 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:
+
+* Separate the item and material with a space rather than a colon
+* If the item has no subtype, the ``:NONE`` can be omitted
+* If the item is ``REMAINS``, ``FISH``, ``FISH_RAW``, ``VERMIN``, ``PET``, or
+  ``EGG``, then specify a ``CREATURE:CASTE`` pair instead of a material token.
+* If the item is a ``PLANT_GROWTH``, specify a ``PLANT_ID:GROWTH_ID`` pair
+  instead of a material token.
+
+Corpses, body parts, and prepared meals cannot be created using this tool.
+
+Usage
+-----
+
+``createitem <item> <material> [<count>]``
+    Create <count> copies (default is 1) of the specified item made out of the
+    specified material.
+``createitem inspect``
+    Obtain the item and material tokens of an existing item. Its output can be
+    used directly as arguments to ``createitem`` to create new matching items
+    (as long as the item type is supported).
+``createitem floor|item|building``
+    Subsequently created items will be placed on the floor beneath the selected
+    unit's, inside the selected item, or as part of the selected building.
+
+.. note::
+
+    ``createitem building`` is good for loading traps, but if you use it with
+    workshops, you will have to deconstruct the workshop to access the item.
+
+Examples
+--------
+
+``createitem GLOVES:ITEM_GLOVES_GAUNTLETS INORGANIC:STEEL 2``
+    Create 2 pairs of steel gauntlets (that is, 2 left gauntlets and 2 right
+    gauntlets).
+``createitem WOOD PLANT_MAT:TOWER_CAP:WOOD 100``
+    Create 100 tower-cap logs.
+``createitem PLANT_GROWTH BILBERRY:FRUIT``
+    Create a single bilberry.
+
+For more examples, :wiki:`the wiki <Utility:DFHack/createitem>`.

docs/plugins/cursecheck.rst

@@ -0,0 +1,61 @@
+cursecheck
+==========
+
+.. dfhack-tool::
+    :summary: Check for cursed creatures.
+    :tags: fort armok inspection units
+
+This command checks a single map tile (or the whole map/world) for cursed
+creatures (ghosts, vampires, necromancers, werebeasts, zombies, etc.).
+
+With an active in-game cursor, only the selected tile will be checked. Without a
+cursor, the whole map will be checked.
+
+By default, you will just see the count of cursed creatures in case you just
+want to find out if you have any of them running around in your fort. Dead and
+passive creatures (ghosts who were put to rest, killed vampires, etc.) are
+ignored. Undead skeletons, corpses, bodyparts and the like are all thrown into
+the curse category "zombie". Anonymous zombies and resurrected body parts will
+show as "unnamed creature".
+
+Usage
+-----
+
+::
+
+   cursecheck [<options>]
+
+Examples
+--------
+
+- ``cursecheck``
+   Display a count of cursed creatures on the map (or under the cursor).
+- ``cursecheck detail all``
+   Give detailed info about all cursed creatures including deceased ones.
+- ``cursecheck nick``
+   Give a nickname all living/active cursed creatures.
+
+.. note::
+
+    If you do a full search (with the option "all") former ghosts will show up
+    with the cursetype "unknown" because their ghostly flag is not set.
+
+    If you see any living/active creatures with a cursetype of "unknown", then
+    it is most likely a new type of curse introduced by a mod.
+
+Options
+-------
+
+``detail``
+   Print full name, date of birth, date of curse, and some status info (some
+   vampires might use fake identities in-game, though).
+``nick``
+   Set the type of curse as nickname (does not always show up in-game; some
+   vamps don't like nicknames).
+``ids``
+   Print the creature and race IDs.
+``all``
+   Include dead and passive cursed creatures (this can result in quite a long
+   list after having !!FUN!! with necromancers).
+``verbose``
+   Print all curse tags (if you really want to know it all).

docs/plugins/cxxrandom.rst

@@ -0,0 +1,9 @@
+cxxrandom
+=========
+
+.. dfhack-tool::
+    :summary: Provides a Lua API for random distributions.
+    :tags: dev
+    :no-command:
+
+See `cxxrandom-api` for details.

docs/plugins/debug.rst

@@ -0,0 +1,77 @@
+debug
+=====
+
+.. dfhack-tool::
+    :summary: Provides commands for controlling debug log verbosity.
+    :tags: dev
+    :no-command:
+
+.. dfhack-command:: debugfilter
+    :summary: Configure verbosity of DFHack debug output.
+
+Debug output is grouped by plugin name, category name, and verbosity level.
+
+The verbosity levels are:
+
+- ``Trace``
+    Possibly very noisy messages which can be printed many times per second.
+- ``Debug``
+    Messages that happen often but they should happen only a couple of times per
+    second.
+- ``Info``
+    Important state changes that happen rarely during normal execution.
+- ``Warning``
+    Enabled by default. Shows warnings about unexpected events which code
+    managed to handle correctly.
+- ``Error``
+    Enabled by default. Shows errors which code can't handle without user
+    intervention.
+
+The runtime message printing is controlled using filters. Filters set the
+visible messages of all matching categories. Matching uses regular expression
+syntax, which allows listing multiple alternative matches or partial name
+matches. This syntax is a C++ version of the ECMA-262 grammar (Javascript
+regular expressions). Details of differences can be found at
+https://en.cppreference.com/w/cpp/regex/ecmascript
+
+Persistent filters are stored in ``dfhack-config/runtime-debug.json``. Oldest
+filters are applied first. That means a newer filter can override the older
+printing level selection.
+
+Usage
+-----
+
+``debugfilter category [<plugin regex>] [<category regex>]``
+    List available debug plugin and category names. If filters aren't givenm
+    then all plugins/categories are matched. This command is a good way to test
+    regex parameters before you pass them to ``set``.
+``debugfilter filter [<id>]``
+    List active and passive debug print level changes. The optional ``id``
+    parameter is the id listed as first column in the filter list. If ``id`` is
+    given, then the command shows extended information for the given filter
+    only.
+``debugfilter set [<level>] [<plugin regex>] [<category regex>]``
+    Create a new debug filter to set category verbosity levels. This filter
+    will not be saved when the DF process exists or the plugin is unloaded.
+``debugfilter set persistent [<level>] [<plugin regex>] [<category regex>]``
+    Store the filter in the configuration file to until ``unset`` is used to
+    remove it.
+``debugfilter unset <id> [<id> ...]``
+    Delete a space separated list of filters.
+``debugfilter disable <id> [<id> ...]``
+    Disable a space separated list of filters but keep it in the filter list.
+``debugfilter enable <id> [<id> ...]``
+    Enable a space sperate list of filters.
+``debugfilter header [enable] | [disable] [<element> ...]``
+    Control which header metadata is shown along with each log message. Run it
+    without parameters to see the list of configurable elements. Include an
+    ``enable`` or ``disable``  keyword to change whether specific elements are
+    shown.
+
+Example
+-------
+
+``debugfilter set Warning core script``
+    Hide script execution log messages (e.g. "Loading script:
+    dfhack-config/dfhack.init"), which are normally output at Info verbosity
+    in the "core" plugin with the "script" category.

docs/plugins/deramp.rst

@@ -0,0 +1,15 @@
+deramp
+======
+
+.. dfhack-tool::
+    :summary: Removes all ramps designated for removal from the map.
+    :tags: fort armok map
+
+It also removes any "floating" down ramps that can remain after a cave-in.
+
+Usage
+-----
+
+::
+
+    deramp

docs/plugins/dig-now.rst

@@ -0,0 +1,67 @@
+dig-now
+=======
+
+.. dfhack-tool::
+    :summary: Instantly complete dig designations.
+    :tags: fort armok map
+
+This tool will magically complete non-marker dig designations, modifying tile
+shapes and creating boulders, ores, and gems as if a miner were doing the mining
+or engraving. By default, the entire map is processed and boulder generation
+follows standard game rules, but the behavior is configurable.
+
+Note that no units will get mining or engraving experience for the dug/engraved
+tiles.
+
+Trees and roots are not currently handled by this plugin and will be skipped.
+Requests for engravings are also skipped since they would depend on the skill
+and creative choices of individual engravers. Other types of engraving (i.e.
+smoothing and track carving) are handled.
+
+Usage
+-----
+
+::
+
+    dig-now [<pos> [<pos>]] [<options>]
+
+Where the optional ``<pos>`` pair can be used to specify the coordinate bounds
+within which ``dig-now`` will operate. If they are not specified, ``dig-now``
+will scan the entire map. If only one ``<pos>`` is specified, only the tile at
+that coordinate is processed.
+
+Any ``<pos>`` parameters can either be an ``<x>,<y>,<z>`` triple (e.g.
+``35,12,150``) or the string ``here``, which means the position of the active
+game cursor should be used. You can use the `position` command to get the
+current cursor position if you need it.
+
+Examples
+--------
+
+``dig-now``
+    Dig designated tiles according to standard game rules.
+``dig-now --clean``
+    Dig all designated tiles, but don't generate any boulders, ores, or gems.
+``dig-now --dump here``
+    Dig tiles and teleport all generated boulders, ores, and gems to the tile
+    under the game cursor.
+
+Options
+-------
+
+``-c``, ``--clean``
+    Don't generate any boulders, ores, or gems. Equivalent to
+    ``--percentages 0,0,0,0``.
+``-d``, ``--dump <pos>``
+    Dump any generated items at the specified coordinates. If the tile at those
+    coordinates is open space or is a wall, items will be generated on the
+    closest walkable tile below.
+``-e``, ``--everywhere``
+    Generate a boulder, ore, or gem for every tile that can produce one.
+    Equivalent to ``--percentages 100,100,100,100``.
+``-p``, ``--percentages <layer>,<vein>,<small cluster>,<deep>``
+    Set item generation percentages for each of the tile categories. The
+    ``vein`` category includes both the large oval clusters and the long stringy
+    mineral veins. Default is ``25,33,100,100``.
+``-z``, ``--cur-zlevel``
+    Restricts the bounds to the currently visible z-level.

docs/plugins/dig.rst

@@ -0,0 +1,177 @@
+.. _digv:
+.. _digtype:
+
+dig
+===
+
+.. dfhack-tool::
+    :summary: Provides commands for designating tiles for digging.
+    :tags: fort design productivity map
+    :no-command:
+
+.. dfhack-command:: digv
+    :summary: Designate all of the selected vein for digging.
+
+.. dfhack-command:: digvx
+    :summary: Dig a vein across z-levels, digging stairs as needed.
+
+.. dfhack-command:: digl
+    :summary: Dig all of the selected layer stone.
+
+.. dfhack-command:: diglx
+    :summary: Dig layer stone across z-levels, digging stairs as needed.
+
+.. dfhack-command:: digcircle
+    :summary: Designate circles.
+
+.. dfhack-command:: digtype
+    :summary: Designate all vein tiles of the selected type.
+
+.. dfhack-command:: digexp
+    :summary: Designate dig patterns for exploratory mining.
+
+This plugin provides commands to make complicated dig patterns easy.
+
+Usage
+-----
+
+``digv [x] [-p<number>]``
+    Designate all of the selected vein for digging.
+``digvx [-p<number>]``
+    Dig a vein across z-levels, digging stairs as needed. This is an alias for
+    ``digv x``.
+``digl [x] [undo] [-p<number>]``
+    Dig all of the selected layer stone. If ``undo`` is specified, removes the
+    designation instead (for if you accidentally set 50 levels at once).
+``diglx [-p<number>]``
+    Dig layer stone across z-levels, digging stairs as needed. This is an alias
+    for ``digl x``.
+``digcircle [<diameter>] [<solidity>] [<action>] [<designation>] [-p<number>]``
+    Designate circles. The diameter is the number of tiles across the center of
+    the circle that you want to dig. See the `digcircle`_ section below for
+    options.
+``digtype [<designation>] [-p<number>]``
+    Designate all vein tiles of the selected type. See the `digtype`_ section
+    below for options.
+``digexp [<pattern>] [<filter>] [-p<number>]``
+    Designate dig patterns for exploratory mining. See the `digexp`_ section
+    below for options.
+
+All commands support specifying the priority of the dig designations with
+``-p<number>``, where the number is from 1 to 7. If a priority is not specified,
+the priority selected in-game is used as the default.
+
+Examples
+--------
+
+``digcircle filled 3 -p2``
+    Dig a filled circle with a diameter of 3 tiles at dig priority 2.
+``digcircle``
+    Do it again (previous parameters are reused).
+``expdig diag5 hidden``
+    Designate the diagonal 5 pattern over all hidden tiles on the current
+    z-level.
+``expdig ladder designated``
+    Take existing designations on the current z-level and replace them with the
+    ladder pattern.
+``expdig``
+    Do it again (previous parameters are reused).
+
+digcircle
+---------
+
+The ``digcircle`` command can accept up to one option of each type below.
+
+Solidity options:
+
+``hollow``
+    Designates hollow circles (default).
+``filled``
+    Designates filled circles.
+
+Action options:
+
+``set``
+    Set designation (default).
+``unset``
+    Unset current designation.
+``invert``
+    Invert designations already present.
+
+Designation options:
+
+``dig``
+    Normal digging designation (default).
+``ramp``
+    Dig ramps.
+``ustair``
+    Dig up staircases.
+``dstair``
+    Dig down staircases.
+``xstair``
+    Dig up/down staircases.
+``chan``
+    Dig channels.
+
+After you have set the options, the command called with no options repeats with
+the last selected parameters.
+
+digtype
+-------
+
+For every tile on the map of the same vein type as the selected tile, this
+command designates it to have the same designation as the selected tile. If the
+selected tile has no designation, they will be dig designated.
+
+If an argument is given, the designation of the selected tile is ignored, and
+all appropriate tiles are set to the specified designation.
+
+Designation options:
+
+``dig``
+    Normal digging designation.
+``channel``
+    Dig channels.
+``ramp``
+    Dig ramps.
+``updown``
+    Dig up/down staircases.
+``up``
+    Dig up staircases.
+``down``
+    Dig down staircases.
+``clear``
+    Clear any designations.
+
+digexp
+------
+
+This command is for :wiki:`exploratory mining <Exploratory_mining>`.
+
+There are two variables that can be set: pattern and filter.
+
+Patterns:
+
+``diag5``
+    Diagonals separated by 5 tiles.
+``diag5r``
+    The diag5 pattern rotated 90 degrees.
+``ladder``
+    A 'ladder' pattern.
+``ladderr``
+    The ladder pattern rotated 90 degrees.
+``cross``
+    A cross, exactly in the middle of the map.
+``clear``
+    Just remove all dig designations.
+
+Filters:
+
+``hidden``
+    Designate only hidden tiles of z-level (default)
+``all``
+    Designate the whole z-level.
+``designated``
+    Take current designation and apply the selected pattern to it.
+
+After you have a pattern set, you can use ``expdig`` to apply it again.

docs/plugins/digFlood.rst

@@ -0,0 +1,42 @@
+digFlood
+========
+
+.. dfhack-tool::
+    :summary: Digs out veins as they are discovered.
+    :tags: fort auto map
+
+Once you register specific vein types, this tool will automatically designate
+tiles of those types of veins for digging as your miners complete adjacent
+mining jobs. Note that it will *only* dig out tiles that are adjacent to a
+just-finished dig job, so if you want to autodig a vein that has already been
+discovered, you may need to manually designate one tile of the tile for digging
+to get started.
+
+Usage
+-----
+
+``enable digflood``
+    Enable the plugin.
+``digflood 1 <vein type> [<vein type> ...]``
+    Start monitoring for the specified vein types.
+``digFlood 0 <vein type> [<vein type> ...] 1``
+    Stop monitoring for the specified vein types. Note the required ``1`` at the
+    end.
+``digFlood CLEAR``
+    Remove all inorganics from monitoring.
+``digFlood digAll1``
+    Ignore the monitor list and dig any vein.
+``digFlood digAll0``
+    Disable digAll mode.
+
+You can get the list of valid vein types with this command::
+
+    lua "for i,mat in ipairs(df.global.world.raws.inorganics) do if mat.material.flags.IS_STONE and not mat.material.flags.NO_STONE_STOCKPILE then print(i, mat.id) end end"
+
+Examples
+--------
+
+``digFlood 1 MICROCLINE COAL_BITUMINOUS``
+    Automatically dig microcline and bituminous coal veins.
+``digFlood 0 MICROCLINE 1``
+    Stop automatically digging microcline.

docs/plugins/diggingInvaders.rst

@@ -0,0 +1,60 @@
+diggingInvaders
+===============
+
+.. dfhack-tool::
+    :summary: Invaders dig and destroy to get to your dwarves.
+    :tags: fort gameplay military units
+
+Usage
+-----
+
+``enable diggingInvaders``
+    Enable the plugin.
+``diggingInvaders add <race>``
+    Register the specified race as a digging invader.
+``diggingInvaders remove <race>``
+    Unregisters the specified race as a digging invader.
+``diggingInvaders now``
+    Makes invaders try to dig now (if the plugin is enabled).
+``diggingInvaders clear``
+    Clears the registry of digging invader races.
+``diggingInvaders edgesPerTick <n>``
+    Makes the pathfinding algorithm work on at most n edges per tick. Set to 0
+    or lower to make it unlimited.
+``diggingInvaders setCost <race> <action> <n>``
+    Set the pathing cost per tile for a particular action. This determines what
+    invaders consider to be the shortest path to their target.
+``diggingInvaders setDelay <race> <action> <n>``
+    Set the time cost (in ticks) for performing a particular action. This
+    determines how long it takes for invaders to get to their target.
+
+Note that the race is case-sensitive. You can get a list of races for your world
+with this command::
+
+    devel/query --table df.global.world.raws.creatures.all --search creature_id --maxdepth 1 --maxlength 5000
+
+but in general, the race is what you'd expect, just capitalized (e.g. ``GOBLIN``
+or ``ELF``).
+
+Actions:
+
+``walk``
+    Default cost: 1, default delay: 0. This is the base cost for the pathing
+    algorithm.
+``destroyBuilding``
+    Default cost: 2, default delay: 1,000,
+``dig``
+    Default cost: 10,000, default delay: 1,000. This is for digging soil or
+    natural stone.
+``destroyRoughConstruction``
+    Default cost: 1,000, default delay: 1,000. This is for destroying
+    constructions made from boulders.
+``destroySmoothConstruction``
+    Default cost: 100, default delay: 100. This is for destroying constructions
+    made from blocks or bars.
+
+Example
+-------
+
+``diggingInvaders add GOBLIN``
+    Registers members of the GOBLIN race as a digging invader.

docs/plugins/dwarfmonitor.rst

@@ -0,0 +1,94 @@
+dwarfmonitor
+============
+
+.. dfhack-tool::
+    :summary: Measure fort happiness and efficiency.
+    :tags: fort inspection jobs units
+
+It can also show heads-up display widgets with live fort statistics.
+
+Usage
+-----
+
+``enable dwarfmonitor``
+    Enable the plugin.
+``dwarfmonitor enable <mode>``
+    Start tracking a specific facet of fortress life. The ``mode`` can be
+    "work", "misery", "date", "weather", or "all".  This will show the
+    corresponding on-screen widgets, if applicable.
+``dwarfmonitor disable <mode>``
+    Stop monitoring ``mode`` and disable corresponding widgets.
+``dwarfmonitor stats``
+    Show statistics summary.
+``dwarfmonitor prefs``
+    Show summary of dwarf preferences.
+``dwarfmonitor reload``
+    Reload the widget configuration file (``dfhack-config/dwarfmonitor.json``).
+
+Widget configuration
+--------------------
+
+The following types of widgets (defined in
+:file:`hack/lua/plugins/dwarfmonitor.lua`) can be displayed on the main fortress
+mode screen:
+
+``misery``
+    Show overall happiness levels of all dwarves.
+``date``
+    Show the in-game date.
+``weather``
+    Show current weather (e.g. rain/snow).
+``cursor``
+    Show the current mouse cursor position.
+
+The file :file:`dfhack-config/dwarfmonitor.json` can be edited to control the
+positions and settings of all widgets. This file should contain a JSON object
+with the key ``widgets`` containing an array of objects:
+
+.. code-block:: lua
+
+    {
+        "widgets": [
+            {
+                "type": "widget type (weather, misery, etc.)",
+                "x": X coordinate,
+                "y": Y coordinate
+                <...additional options...>
+            }
+        ]
+    }
+
+X and Y coordinates begin at zero (in the upper left corner of the screen).
+Negative coordinates will be treated as distances from the lower right corner,
+beginning at 1 - e.g. an x coordinate of 0 is the leftmost column, while an x
+coordinate of -1 is the rightmost column.
+
+By default, the x and y coordinates given correspond to the leftmost tile of
+the widget. Including an ``anchor`` option set to ``right`` will cause the
+rightmost tile of the widget to be located at this position instead.
+
+Some widgets support additional options:
+
+* ``date`` widget:
+
+  * ``format``: specifies the format of the date. The following characters
+    are replaced (all others, such as punctuation, are not modified)
+
+    * ``Y`` or ``y``: The current year
+    * ``M``: The current month, zero-padded if necessary
+    * ``m``: The current month, *not* zero-padded
+    * ``D``: The current day, zero-padded if necessary
+    * ``d``: The current day, *not* zero-padded
+
+    The default date format is ``Y-M-D``, per the ISO8601_ standard.
+
+    .. _ISO8601: https://en.wikipedia.org/wiki/ISO_8601
+
+* ``cursor`` widget:
+
+  * ``format``: Specifies the format. ``X``, ``x``, ``Y``, and ``y`` are
+    replaced with the corresponding cursor cordinates, while all other
+    characters are unmodified.
+  * ``show_invalid``: If set to ``true``, the mouse coordinates will both be
+    displayed as ``-1`` when the cursor is outside of the DF window; otherwise,
+    nothing will be displayed.

docs/plugins/dwarfvet.rst

@@ -0,0 +1,23 @@
+dwarfvet
+========
+
+.. dfhack-tool::
+    :summary: Allows animals to be treated at animal hospitals.
+    :tags: fort gameplay animals
+
+Annoyed your dragons become useless after a minor injury? Well, with dwarfvet,
+injured animals will be treated at an animal hospital, which is simply a hospital
+that is also an animal training zone. Dwarfs with the Animal Caretaker labor
+enabled will come to the hospital to treat animals. Normal medical skills are
+used (and trained), but no experience is given to the Animal Caretaker skill
+itself.
+
+Usage
+-----
+
+``enable dwarfvet``
+    Enables the plugin.
+``dwarfvet report``
+    Reports all zones that the game considers animal hospitals.
+``dwarfvet report-usage``
+    Reports on animals currently being treated.

docs/plugins/embark-assistant.rst

@@ -0,0 +1,26 @@
+embark-assistant
+================
+
+.. dfhack-tool::
+    :summary: Embark site selection support.
+    :tags: embark fort interface
+
+Run this command while the pre-embark screen is displayed to show extended (and
+reasonably correct) resource information for the embark rectangle as well as
+normally undisplayed sites in the current embark region. You will also have
+access to a site selection tool with far more options than DF's vanilla search
+tool.
+
+If you enable the plugin, you'll also be able to invoke ``embark-assistant``
+with the :kbd:`A` key on the pre-embark screen.
+
+Usage
+-----
+
+::
+
+    enable embark-assistant
+    embark-assistant
+
+Note the site selection tool requires a display height of at least 46 lines to
+display properly.

docs/plugins/embark-tools.rst

@@ -0,0 +1,34 @@
+embark-tools
+============
+
+.. dfhack-tool::
+    :summary: Extend the embark screen functionality.
+    :tags: embark fort interface
+
+Usage
+-----
+
+::
+
+    enable embark-tools
+    embark-tools enable|disable all
+    embark-tools enable|disable <tool> [<tool> ...]
+
+Avaliable tools are:
+
+``anywhere``
+    Allows embarking anywhere (including sites, mountain-only biomes, and
+    oceans). Use with caution.
+``mouse``
+    Implements mouse controls (currently in the local embark region only).
+``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.
+
+Example
+-------
+
+``embark-tools enable all``
+    Enable all embark screen extensions.

docs/plugins/eventful.rst

@@ -0,0 +1,9 @@
+eventful
+========
+
+.. dfhack-tool::
+    :summary: Provides a Lua API for reacting to in-game events.
+    :tags: dev gameplay
+    :no-command:
+
+See `eventful-api` for details.

docs/plugins/fastdwarf.rst

@@ -0,0 +1,38 @@
+fastdwarf
+=========
+
+.. dfhack-tool::
+    :summary: Dwarves teleport and/or finish jobs instantly.
+    :tags: fort armok units
+
+Usage
+-----
+
+::
+
+    enable fastdwarf
+    fastdwarf <speed mode> [<tele mode>]
+
+Examples
+--------
+
+``fastdwarf 1``
+    Make all your dwarves move and work at maximum speed.
+``fastdwarf 1 1``
+    In addition to working at maximum speed, dwarves also teleport to their
+    destinations.
+
+Options
+-------
+
+Speed modes:
+
+:0: Dwarves move and work at normal rates.
+:1: Dwarves move and work at maximum speed.
+:2: ALL units move (and work) at maximum speed, including creatures and
+    hostiles.
+
+Tele modes:
+
+:0: No teleportation.
+:1: Dwarves teleport to their destinations.

docs/plugins/filltraffic.rst

@@ -0,0 +1,53 @@
+.. _restrictice:
+.. _restrictliquids:
+
+filltraffic
+===========
+
+.. dfhack-tool::
+    :summary: Set traffic designations using flood-fill starting at the cursor.
+    :tags: fort design productivity map
+
+.. dfhack-command:: alltraffic
+    :summary: Set traffic designations for every single tile of the map.
+
+.. dfhack-command:: restrictice
+    :summary: Restrict traffic on all tiles on top of visible ice.
+
+.. dfhack-command:: restrictliquids
+    :summary: Restrict traffic on all visible tiles with liquid.
+
+Usage
+-----
+
+::
+
+    filltraffic <designation> [<options>]
+    alltraffic <designation>
+    restrictice
+    restrictliquids
+
+For ``filltraffic``, flood filling stops at walls and doors.
+
+Examples
+--------
+
+``filltraffic H``
+    When used in a room with doors, it will set traffic to HIGH in just that
+    room.
+
+Options
+-------
+
+Traffic designations:
+
+:H:     High Traffic.
+:N:     Normal Traffic.
+:L:     Low Traffic.
+:R:     Restricted Traffic.
+
+Filltraffic extra options:
+
+:X:     Fill across z-levels.
+:B:     Include buildings and stockpiles.
+:P:     Include empty space.

docs/plugins/fix-unit-occupancy.rst

@@ -0,0 +1,41 @@
+fix-unit-occupancy
+==================
+
+.. dfhack-tool::
+    :summary: Fix phantom unit occupancy issues.
+    :tags: fort bugfix map
+
+If you see "unit blocking tile" messages that you can't account for
+(:bug:`3499`), this tool can help.
+
+Usage
+-----
+
+::
+
+    enable fix-unit-occupancy
+    fix-unit-occupancy [here] [-n]
+    fix-unit-occupancy interval <num_ticks>
+
+When run without arguments (or with just the ``here`` or ``-n`` parameters),
+the fix just runs once. You can also have it run periodically by enbling the
+plugin.
+
+Examples
+--------
+
+``fix-unit-occupancy``
+    Run once and fix all occupancy issues on the map.
+``fix-unit-occupancy -n``
+    Report on, but do not fix, all occupancy issues on the map.
+
+Options
+-------
+
+``here``
+    Only operate on the tile at the cursor.
+``-n``
+    Report issues, but do not any write changes to the map.
+``interval <num_ticks>``
+    Set how often the plugin will check for and fix issues when it is enabled.
+    The default is 1200 ticks, or 1 game day.

docs/plugins/fixveins.rst

@@ -0,0 +1,16 @@
+fixveins
+========
+
+.. dfhack-tool::
+    :summary: Restore missing mineral inclusions.
+    :tags: fort bugfix map
+
+This tool can also remove invalid references to mineral inclusions if you broke
+your embark with tools like `tiletypes`.
+
+Usage
+-----
+
+::
+
+    fixveins

docs/plugins/flows.rst

@@ -0,0 +1,16 @@
+flows
+=====
+
+.. dfhack-tool::
+    :summary: Counts map blocks with flowing liquids.
+    :tags: fort inspection map
+
+If you suspect that your magma sea leaks into HFS, you can use this tool to be
+sure without revealing the map.
+
+Usage
+-----
+
+::
+
+    flows

docs/plugins/follow.rst

@@ -0,0 +1,17 @@
+follow
+======
+
+.. dfhack-tool::
+    :summary: Make the screen follow the selected unit.
+    :tags: fort interface units
+
+Once you exit from the current menu or cursor mode, the screen will stay
+centered on the unit. Handy for watching dwarves running around. Deactivated by
+moving the cursor manually.
+
+Usage
+-----
+
+::
+
+    follow

docs/plugins/forceequip.rst

@@ -0,0 +1,104 @@
+forceequip
+==========
+
+.. dfhack-tool::
+    :summary: Move items into a unit's inventory.
+    :tags: adventure fort animals items military units
+
+This tool 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. Make sure the unit you want to equip is standing
+on the target items, which must be on the ground and be unforbidden. If multiple
+units are standing on the same tile, the first one will be equipped.
+
+The most reliable way to set up the environment for this command is to pile
+target items on a tile of floor with a garbage dump activity zone or the
+`autodump` command, then walk/pasture a unit (or use `gui/teleport`) on top of
+the items. Be sure to unforbid the items that you want to work with!
+
+.. note::
+
+    Weapons are not currently supported.
+
+Usage
+-----
+
+::
+
+    forceequip [<options>]
+
+As mentioned above, this plugin can be used to equip items onto units (such as
+animals) who cannot normally equip gear. There's an important caveat here: such
+creatures will automatically drop inappropriate gear almost immediately (within
+10 game ticks). If you want them to retain their equipment, you must forbid it
+AFTER using forceequip to get it into their inventory. This technique can also
+be used to clothe dwarven infants, but only if you're able to separate them from
+their mothers.
+
+By default, the ``forceequip`` command will attempt to abide by game rules as
+closely as possible. For instance, it will skip any item which is flagged for
+use in a job, and will not equip more than one piece of clothing/armor onto any
+given body part. These restrictions can be overridden via options, but doing so
+puts you at greater risk of unexpected consequences. For instance, a dwarf who
+is wearing three breastplates will not be able to move very quickly.
+
+Items equipped by this plugin DO NOT become owned by the recipient. Adult
+dwarves are free to adjust their own wardrobe, and may promptly decide to doff
+your gear in favour of their owned items. Animals, as described above, will tend
+to discard ALL clothing immediately unless it is manually forbidden. Armor items
+seem to be an exception: an animal will tend to retain an equipped suit of mail
+even if you neglect to forbid it.
+
+Please note that armored animals are quite vulnerable to ranged attacks. Unlike
+dwarves, animals cannot block, dodge, or deflect arrows, and they are slowed by
+the weight of their armor.
+
+Examples
+--------
+
+``forceequip``
+    Attempts to equip all of the clothing and armor under the cursor onto the
+    unit under the cursor, following game rules regarding which item can be
+    equipped on which body part and only equipping 1 item onto each body part.
+    Items owned by other dwarves are ignored.
+``forceequip v bp QQQ``
+    List the bodyparts of the selected unit.
+``forceequip bp LH``
+    Equips an appopriate item onto the unit's left hand.
+``forceequip m bp LH``
+    Equips ALL appropriate items onto the unit's left hand. The unit may end up
+    wearing a dozen left-handed mittens. Use with caution, and remember that
+    dwarves tend to drop extra items ASAP.
+``forceequip i bp NECK``
+    Equips an item around the unit's neck, ignoring appropriateness
+    restrictions. If there's a millstone or an albatross carcass sitting on the
+    same square as the targeted unit, then there's a good chance that it will
+    end up around his neck. For precise control, remember that you can
+    selectively forbid some of the items that are piled on the ground.
+``forceequip s``
+    Equips the item currently selected in the k menu, if possible.
+``forceequip s m i bp HD``
+    Equips the selected item onto the unit's head. Ignores all restrictions and
+    conflicts. If you know exactly what you want to equip, and exactly where you
+    want it to go, then this is the most straightforward and reliable option.
+
+Options
+-------
+
+``i``, ``ignore``
+    Bypasses the usual item eligibility checks (such as "Never equip gear
+    belonging to another dwarf" and "Nobody is allowed to equip a Hive".
+``m``, ``multi``
+    Bypasses the 1-item-per-bodypart limit. Useful for equipping both a mitten
+    and a gauntlet on the same hand (or twelve breastplates on the upper body).
+``m2``, ``m3``, ``m4``
+    Modifies the 1-item-per-bodypart limit, allowing each part to receive 2, 3,
+    or 4 pieces of gear.
+``s``, ``selected``
+    Equip only the item currently selected in the k menu and ignore all other
+    items in the tile.
+``bp``, ``bodypart <body part code>``
+    Specify which body part should be equipped.
+``v``, ``verbose``
+    Provide detailed narration and error messages, including listing available
+    body parts when an invalid ``bodypart`` code is specified.

docs/plugins/generated-creature-renamer.rst

@@ -0,0 +1,32 @@
+generated-creature-renamer
+==========================
+
+.. dfhack-tool::
+    :summary: Automatically renames generated creatures.
+    :tags: adventure fort legends units
+    :no-command:
+
+.. dfhack-command:: list-generated
+    :summary: List the token names of all generated creatures.
+
+.. dfhack-command:: save-generated-raws
+    :summary: Export a creature graphics file for modding.
+
+Now, forgotten beasts, titans, necromancer experiments, etc. will have raw token
+names that match the description given in-game instead of unreadable generated
+strings.
+
+Usage
+-----
+
+``enable generated-creature-renamer``
+    Rename generated creatures when a world is loaded.
+``list-generated [detailed]``
+    List the token names of all generated creatures in the loaded save. If
+    ``detailed`` is specified, then also show the accompanying description.
+``save-generated-raws``
+    Save a sample creature graphics file in the Dwarf Fortress root directory to
+    use as a start for making a graphics set for generated creatures using the
+    new names that they get with this plugin.
+
+The new names are saved with the world.