From 301c8e93a19a515a720a69c137a85e7640932290 Mon Sep 17 00:00:00 2001 From: myk002 Date: Mon, 18 Jul 2022 10:58:35 -0700 Subject: [PATCH] move builtin docs to individual files --- conf.py | 3 + docs/Builtin.rst | 280 ------------------------------- docs/Tags.rst | 2 + docs/builtins/alias.rst | 29 ++++ docs/builtins/clear.rst | 4 + docs/builtins/cls.rst | 5 + docs/builtins/devel/dump-rpc.rst | 8 + docs/builtins/die.rst | 4 + docs/builtins/dir.rst | 4 + docs/builtins/disable.rst | 20 +++ docs/builtins/enable.rst | 20 +++ docs/builtins/fpause.rst | 5 + docs/builtins/help.rst | 19 +++ docs/builtins/hide.rst | 8 + docs/builtins/keybinding.rst | 56 +++++++ docs/builtins/kill-lua.rst | 6 + docs/builtins/load.rst | 13 ++ docs/builtins/ls.rst | 34 ++++ docs/builtins/plug.rst | 12 ++ docs/builtins/reload.rst | 14 ++ docs/builtins/sc-script.rst | 9 + docs/builtins/script.rst | 19 +++ docs/builtins/show.rst | 9 + docs/builtins/tags.rst | 9 + docs/builtins/type.rst | 10 ++ docs/builtins/unload.rst | 11 ++ docs/index-tools.rst | 15 +- index.rst | 20 ++- library/lua/helpdb.lua | 74 ++++---- 29 files changed, 390 insertions(+), 332 deletions(-) delete mode 100644 docs/Builtin.rst create mode 100644 docs/builtins/alias.rst create mode 100644 docs/builtins/clear.rst create mode 100644 docs/builtins/cls.rst create mode 100644 docs/builtins/devel/dump-rpc.rst create mode 100644 docs/builtins/die.rst create mode 100644 docs/builtins/dir.rst create mode 100644 docs/builtins/disable.rst create mode 100644 docs/builtins/enable.rst create mode 100644 docs/builtins/fpause.rst create mode 100644 docs/builtins/help.rst create mode 100644 docs/builtins/hide.rst create mode 100644 docs/builtins/keybinding.rst create mode 100644 docs/builtins/kill-lua.rst create mode 100644 docs/builtins/load.rst create mode 100644 docs/builtins/ls.rst create mode 100644 docs/builtins/plug.rst create mode 100644 docs/builtins/reload.rst create mode 100644 docs/builtins/sc-script.rst create mode 100644 docs/builtins/script.rst create mode 100644 docs/builtins/show.rst create mode 100644 docs/builtins/tags.rst create mode 100644 docs/builtins/type.rst create mode 100644 docs/builtins/unload.rst diff --git a/conf.py b/conf.py index 831833e26..7cf4a3a32 100644 --- a/conf.py +++ b/conf.py @@ -105,6 +105,8 @@ def doc_all_dirs(): # TODO: as we scan the docs, parse out the tags and short descriptions and # build a map for use in generating the tags pages and links in the tool # 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'): @@ -266,6 +268,7 @@ exclude_patterns = [ 'depends/*', 'docs/html/*', 'docs/text/*', + 'docs/builtins/*', 'docs/plugins/*', 'scripts/docs/*', ] diff --git a/docs/Builtin.rst b/docs/Builtin.rst deleted file mode 100644 index 8e59840b4..000000000 --- a/docs/Builtin.rst +++ /dev/null @@ -1,280 +0,0 @@ -.. _built-in-commands: - -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 [arguments...]``: adds an alias -:``alias replace [arguments...]``: replaces an existing - alias with a new command, or adds the alias if it does not already exist -:``alias delete ``: 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 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. 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 `` built-in command to retrieve -further help without having to look online. ``? `` and ``man `` are -aliases. - -Some commands (including many scripts) instead take ``help`` or ``?`` as an -option on their command line - ie `` 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 `` - List bindings active for the key combination. -``keybinding clear ...`` - Remove bindings for the specified keys. -``keybinding add "cmdline" "cmdline"...`` - Add bindings for the specified key. -``keybinding set "cmdline" "cmdline"...`` - Clear, and then add bindings for the specified key. - -The ```` 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 explicitly enable -them. 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: -.. _dir: - -ls --- -``ls`` (or ``dir``) does not list files like the Unix command, but rather -available commands. In order to group related commands, each command is -associated with a list of tags. You can filter the listed commands by a -tag or a substring of the command name. Usage: - -:``ls``: Lists all available commands and the tags associated with them - (if any). -:``ls TAG``: Shows only commands that have the given tag. Use the `tags` command - to see the list of available tags. -:``ls STRING``: Shows commands that include the given string. E.g. ``ls auto`` - will show all the commands with "auto" in their names. If the string is also - the name of a tag, then it will be interpreted as a tag name. - -You can also pass some optional parameters to change how ``ls`` behaves: - -:``--notags``: Don't print out the tags associated with each command. -:``--dev``: Include commands intended for developers and modders. - - -.. _plug: - -plug ----- -Lists available plugins and whether they are enabled. - -``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 `. - -Some other tools, such as `autobutcher` and `workflow`, export their settings as -the commands to create them - which can later be reloaded with ``script``. - - -.. _show: - -show ----- -Shows the terminal window after it has been `hidden `. Only available on -Windows. You'll need to use it from a `keybinding` set beforehand, or the -in-game `command-prompt`. - - -.. _tags: - -tags ----- - -List the strings that the DFHack tools can be tagged with. You can find groups -of related tools by passing the tag name to `ls`. - -.. _type: - -type ----- -``type command`` shows where ``command`` is implemented. - -.. _devel/dump-rpc: - -devel/dump-rpc --------------- - -Writes RPC endpoint information to the specified file. - -Usage:: - - devel/dump-rpc FILENAME - -Other Commands --------------- -The following commands are *not* built-in, but offer similarly useful functions. - -* `command-prompt` -* `hotkeys` -* `lua` -* `multicmd` -* `nopause` -* `quicksave` -* `rb` -* `repeat` diff --git a/docs/Tags.rst b/docs/Tags.rst index effc0ad23..7a5288cbf 100644 --- a/docs/Tags.rst +++ b/docs/Tags.rst @@ -1,3 +1,5 @@ +.. _tags: + Tags ==== diff --git a/docs/builtins/alias.rst b/docs/builtins/alias.rst new file mode 100644 index 000000000..8ca1f014c --- /dev/null +++ b/docs/builtins/alias.rst @@ -0,0 +1,29 @@ +alias +----- + +Configure helper aliases for 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 [arguments...]`` + adds an alias +- ``alias replace [arguments...]`` + replaces an existing alias with a new command, or adds the alias if it does + not already exist +- ``alias delete `` + 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 diff --git a/docs/builtins/clear.rst b/docs/builtins/clear.rst new file mode 100644 index 000000000..b964a8b3f --- /dev/null +++ b/docs/builtins/clear.rst @@ -0,0 +1,4 @@ +clear +----- + +Clear the terminal screen. This command is an alias for `cls`. diff --git a/docs/builtins/cls.rst b/docs/builtins/cls.rst new file mode 100644 index 000000000..b05354d5a --- /dev/null +++ b/docs/builtins/cls.rst @@ -0,0 +1,5 @@ +cls +--- + +Clear the terminal screen. Can also be invoked as ``clear``. Note that this +command does not delete command history. It just clears the text on the screen. diff --git a/docs/builtins/devel/dump-rpc.rst b/docs/builtins/devel/dump-rpc.rst new file mode 100644 index 000000000..af173a179 --- /dev/null +++ b/docs/builtins/devel/dump-rpc.rst @@ -0,0 +1,8 @@ +devel/dump-rpc +-------------- + +Writes RPC endpoint information to the specified file. + +Usage:: + + devel/dump-rpc diff --git a/docs/builtins/die.rst b/docs/builtins/die.rst new file mode 100644 index 000000000..d2dae484f --- /dev/null +++ b/docs/builtins/die.rst @@ -0,0 +1,4 @@ +die +--- + +Instantly exits DF without saving. diff --git a/docs/builtins/dir.rst b/docs/builtins/dir.rst new file mode 100644 index 000000000..5c2059099 --- /dev/null +++ b/docs/builtins/dir.rst @@ -0,0 +1,4 @@ +dir +--- + +List available DFHack commands. This is an alias of the `ls` command. diff --git a/docs/builtins/disable.rst b/docs/builtins/disable.rst new file mode 100644 index 000000000..11077c883 --- /dev/null +++ b/docs/builtins/disable.rst @@ -0,0 +1,20 @@ +disable +------- + +Deactivate a DFHack tool that has some persistent effect. Many plugins and +scripts can be in a distinct enabled or disabled state. Some of them activate +and 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 disable the `manipulator` plugin:: + + disable manipulator + +It is also possible to enable or disable multiple plugins at once:: + + disable manipulator search diff --git a/docs/builtins/enable.rst b/docs/builtins/enable.rst new file mode 100644 index 000000000..eef76c45d --- /dev/null +++ b/docs/builtins/enable.rst @@ -0,0 +1,20 @@ +enable +------ + +Activate a DFHack tool that has some persistent effect. Many plugins and scripts +can be in a distinct enabled or disabled state. Some of them activate and +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 diff --git a/docs/builtins/fpause.rst b/docs/builtins/fpause.rst new file mode 100644 index 000000000..68e4eb07e --- /dev/null +++ b/docs/builtins/fpause.rst @@ -0,0 +1,5 @@ +fpause +------ + +Forces DF to pause. This is useful when your FPS drops below 1 and you lose +control of the game. diff --git a/docs/builtins/help.rst b/docs/builtins/help.rst new file mode 100644 index 000000000..aa9e4b170 --- /dev/null +++ b/docs/builtins/help.rst @@ -0,0 +1,19 @@ +help +---- + +Display help about a command or plugin. + +Usage:: + + help|?|man + help|?|man + +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``. diff --git a/docs/builtins/hide.rst b/docs/builtins/hide.rst new file mode 100644 index 000000000..5c8d08452 --- /dev/null +++ b/docs/builtins/hide.rst @@ -0,0 +1,8 @@ +hide +---- + +Hides the DFHack terminal window. You can show it again with the `show` +command, though you'll need to use it from a `keybinding` set beforehand or the +in-game `command-prompt`. + +Only available on Windows. diff --git a/docs/builtins/keybinding.rst b/docs/builtins/keybinding.rst new file mode 100644 index 000000000..bce450e46 --- /dev/null +++ b/docs/builtins/keybinding.rst @@ -0,0 +1,56 @@ +keybinding +---------- + +Create hotkeys that will run DFHack commands. Like any other command it can be +used at any time from the console, but bindings are not remembered between runs +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 +``\```. + +Usage: + +- ``keybinding`` + Show some useful information, including the current game context. +- ``keybinding list `` + List bindings active for the key combination. +- ``keybinding clear [...]`` + Remove bindings for the specified keys. +- ``keybinding add "cmdline" ["cmdline"...]`` + Add bindings for the specified key. +- ``keybinding set "cmdline" ["cmdline"...]`` + Clear, and then add bindings for the specified key. + +The ```` 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. + diff --git a/docs/builtins/kill-lua.rst b/docs/builtins/kill-lua.rst new file mode 100644 index 000000000..ee354846a --- /dev/null +++ b/docs/builtins/kill-lua.rst @@ -0,0 +1,6 @@ +kill-lua +-------- + +Gracefully stops any currently-running Lua scripts. Use this command to stop +a misbehaving script that appears to be stuck. Use ``kill-lua force`` if just +``kill-lua`` doesn't work. diff --git a/docs/builtins/load.rst b/docs/builtins/load.rst new file mode 100644 index 000000000..fb654b8a4 --- /dev/null +++ b/docs/builtins/load.rst @@ -0,0 +1,13 @@ +load +---- + +Load and register a plugin library. Also see `unload` and `reload` for related +actions. + +Usage:: + + load [ ...] + 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. diff --git a/docs/builtins/ls.rst b/docs/builtins/ls.rst new file mode 100644 index 000000000..5eaa9dc01 --- /dev/null +++ b/docs/builtins/ls.rst @@ -0,0 +1,34 @@ +ls +-- + +List available DFHack commands. In order to group related commands, each command +is associated with a list of tags. You can filter the listed commands by a tag +or a substring of the command name. The `dir` command is an alias of this +command. + +Usage: + +- ``ls []`` + Lists all available commands and the tags associated with them. +- ``ls []`` + Shows only commands that have the given tag. Use the `tags` command to see + the list of available tags. +- ``ls []`` + 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. + +You can also pass some optional parameters to change how ``ls`` behaves: + +- ``--notags`` + Don't print out the tags associated with each command. +- ``--dev`` + Include commands intended for developers and modders. + +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" diff --git a/docs/builtins/plug.rst b/docs/builtins/plug.rst new file mode 100644 index 000000000..da0adb657 --- /dev/null +++ b/docs/builtins/plug.rst @@ -0,0 +1,12 @@ +plug +---- + +Lists available plugins and whether they are enabled. + +Usage: + +- ``plug`` + Lists available plugins and whether they are enabled. +- ``plug [ ...]`` + Shows the commands implemented by the named plugins and whether the plugins + are enabled. diff --git a/docs/builtins/reload.rst b/docs/builtins/reload.rst new file mode 100644 index 000000000..8f28e5ca6 --- /dev/null +++ b/docs/builtins/reload.rst @@ -0,0 +1,14 @@ +reload +------ + +Reload a loaded plugin. Developer use this command to reload a plugin that they +are actively modifying. Also see `load` and `unload` for related actions. + +Usage:: + + reload [ ...] + 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. diff --git a/docs/builtins/sc-script.rst b/docs/builtins/sc-script.rst new file mode 100644 index 000000000..1d5d177c7 --- /dev/null +++ b/docs/builtins/sc-script.rst @@ -0,0 +1,9 @@ +sc-script +--------- + +Runs commands when game state changes occur. This is similar to the static +`init-files` but can be set dynamically. + +Usage:: + + sc-script diff --git a/docs/builtins/script.rst b/docs/builtins/script.rst new file mode 100644 index 000000000..ae2b9f0f4 --- /dev/null +++ b/docs/builtins/script.rst @@ -0,0 +1,19 @@ +script +------ + +Executes a batch file of DFHack commands. It reads a text file and runs each +line as a DFHack command as if it had been typed in by the user - treating the +input like `an init file `. + +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 + +Examples: + +- ``script startup.txt`` + Executes the commands in ``startup.txt``, which exists in your DF game + directory. diff --git a/docs/builtins/show.rst b/docs/builtins/show.rst new file mode 100644 index 000000000..8a6f9b446 --- /dev/null +++ b/docs/builtins/show.rst @@ -0,0 +1,9 @@ +show +---- + +Unhides the DFHack terminal window. Useful if you have hidden the terminal with +`hide` and you want it back. Since the terminal window won't be available to run +this command, you'll need to use it from a `keybinding` set beforehand or the +in-game `command-prompt`. + +Only available on Windows. diff --git a/docs/builtins/tags.rst b/docs/builtins/tags.rst new file mode 100644 index 000000000..9de0f8df3 --- /dev/null +++ b/docs/builtins/tags.rst @@ -0,0 +1,9 @@ +tags +---- + +List the strings that DFHack tools can be tagged with. You can find groups of +related tools by passing the tag name to the `ls` command. + +Usage:: + + tags diff --git a/docs/builtins/type.rst b/docs/builtins/type.rst new file mode 100644 index 000000000..c4c752bef --- /dev/null +++ b/docs/builtins/type.rst @@ -0,0 +1,10 @@ +type +---- + +Describes how a command is implemented. DFHack commands can be provided by +plugins, scripts, or by the core library itself. The ``type`` command can tell +you which is the source of a particular command. + +Usage:: + + type diff --git a/docs/builtins/unload.rst b/docs/builtins/unload.rst new file mode 100644 index 000000000..f4069ed88 --- /dev/null +++ b/docs/builtins/unload.rst @@ -0,0 +1,11 @@ +unload +------ + +Unload a plugin from memory. Also see `load` and `reload` for related actions. + +Usage:: + + unload [ ...] + unload -a|--all + +You can unload individual named plugins or all plugins at once. diff --git a/docs/index-tools.rst b/docs/index-tools.rst index dca14ae3b..a9c540d66 100644 --- a/docs/index-tools.rst +++ b/docs/index-tools.rst @@ -1,24 +1,15 @@ .. _tools-index: -============ -DFHack Tools -============ +================== +DFHack Tools Index +================== These pages contain information about the plugins, scripts, and built-in commands distributed with DFHack. -.. 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. - .. toctree:: :titlesonly: :glob: - /docs/Tags - /docs/Builtin /docs/tools/* /docs/tools/*/* diff --git a/index.rst b/index.rst index 29ac3c129..3e5cdec5d 100644 --- a/index.rst +++ b/index.rst @@ -30,7 +30,25 @@ User Manual /docs/Installing /docs/Support /docs/Core - /docs/index-tools /docs/guides/index /docs/index-about /docs/index-dev + +Tools +===== + +DFHack commands, plugins, and scripts are grouped by tags to make it easier to +find groups of related tools. + +.. 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. + +.. toctree:: + :maxdepth: 1 + + /docs/Tags + /docs/index-tools diff --git a/library/lua/helpdb.lua b/library/lua/helpdb.lua index b52f91f22..18ba5b746 100644 --- a/library/lua/helpdb.lua +++ b/library/lua/helpdb.lua @@ -16,7 +16,6 @@ local _ENV = mkmodule('helpdb') -- paths local RENDERED_PATH = 'hack/docs/docs/tools/' -local BUILTIN_HELP = 'hack/docs/docs/Builtin.txt' local TAG_DEFINITIONS = 'hack/docs/docs/Tags.txt' -- used when reading help text embedded in script sources @@ -25,6 +24,7 @@ local SCRIPT_DOC_END = ']====]' local SCRIPT_DOC_BEGIN_RUBY = '=begin' local SCRIPT_DOC_END_RUBY = '=end' +-- enums local ENTRY_TYPES = { BUILTIN='builtin', PLUGIN='plugin', @@ -38,6 +38,33 @@ local HELP_SOURCES = { SCRIPT='script', } +-- builtins +local BUILTINS = { + 'alias', + 'clear', + 'cls', + 'devel/dump-rpc', + 'die', + 'dir', + 'disable', + 'enable', + 'fpause', + 'help', + 'hide', + 'keybinding', + 'kill-lua', + 'load', + 'ls', + 'plug', + 'reload', + 'script', + 'sc-script', + 'show', + 'tags', + 'type', + 'unload', +} + -- entry name -> { -- entry_types (set of ENTRY_TYPES), -- short_help (string), @@ -246,46 +273,15 @@ local function update_db(old_db, db, source, entry_name, kwargs) end end -local BUILTINS = { - alias='Configure helper aliases for other DFHack commands.', - cls='Clear the console screen.', - clear='Clear the console screen.', - ['devel/dump-rpc']='Write RPC endpoint information to a file.', - die='Force DF to close immediately, without saving.', - enable='Enable a plugin or persistent script.', - disable='Disable a plugin or persistent script.', - fpause='Force DF to pause.', - help='Usage help for the given plugin, command, or script.', - hide='Hide the terminal window (Windows only).', - keybinding='Modify bindings of commands to in-game key shortcuts.', - ['kill-lua']='Stop a misbehaving Lua script.', - ['load']='Load and register a plugin library.', - unload='Unregister and unload a plugin.', - reload='Unload and reload a plugin library.', - ls='List commands, optionally filtered by a tag or substring.', - dir='List commands, optionally filtered by a tag or substring.', - plug='List plugins and whether they are enabled.', - ['sc-script']='Automatically run specified scripts on state change events.', - script='Run commands specified in a file.', - show='Show a hidden terminal window (Windows only).', - tags='List the tags that the DFHack tools are grouped by.', - ['type']='Discover how a command is implemented.', -} - -- add the builtin commands to the db local function scan_builtins(old_db, db) - local entry = make_default_entry('builtin', - {[ENTRY_TYPES.BUILTIN]=true, [ENTRY_TYPES.COMMAND]=true}, - HELP_SOURCES.RENDERED, 0, BUILTIN_HELP) - -- read in builtin help - local f = io.open(BUILTIN_HELP) - if f then - entry.long_help = f:read('*all') - end - for b,short_help in pairs(BUILTINS) do - local builtin_entry = copyall(entry) - builtin_entry.short_help = short_help - db[b] = builtin_entry + local entry_types = {[ENTRY_TYPES.BUILTIN]=true, [ENTRY_TYPES.COMMAND]=true} + for _,builtin in ipairs(BUILTINS) do + update_db(old_db, db, + has_rendered_help(builtin) and + HELP_SOURCES.RENDERED or HELP_SOURCES.STUB, + builtin, + {entry_types=entry_types}) end end