diff --git a/docs/changelog.txt b/docs/changelog.txt index 5e114c5e2..073837eff 100644 --- a/docs/changelog.txt +++ b/docs/changelog.txt @@ -40,6 +40,7 @@ changelog.txt uses a syntax similar to RST, with a few special sequences: ## Misc Improvements - A new cross-compile build script was added for building the Windows files from a Linux Docker builder (see the Compile instructions in the docs) - `hotkeys`: clicking on the DFHack logo no longer closes the popup menu +- `gui/launcher`: sped up initialization time for faster load of the UI - `orders`: orders plugin functionality is now offered via an overlay widget when the manager orders screen is open ## Documentation @@ -47,6 +48,8 @@ changelog.txt uses a syntax similar to RST, with a few special sequences: ## API ## Lua +- `helpdb`: new function: ``helpdb.refresh()`` to force a refresh of the database. Call if you are a developer adding new scripts, loading new plugins, or changing help text during play +- `helpdb`: changed from auto-refreshing every 60 seconds to only refreshing on explicit call to ``helpdb.refresh()``. docs very rarely change during a play session, and the automatic database refreshes were slowing down the startup of `gui/launcher` - ``widgets.Label``: ``label.scroll()`` now understands ``home`` and ``end`` keywords for scrolling to the top or bottom ## Removed diff --git a/docs/dev/Lua API.rst b/docs/dev/Lua API.rst index c696248ab..cc590b179 100644 --- a/docs/dev/Lua API.rst +++ b/docs/dev/Lua API.rst @@ -3319,17 +3319,20 @@ function: argument specifies the indentation step size in spaces. For the other arguments see the original documentation link above. +.. _helpdb: + helpdb ====== Unified interface for DFHack tool help text. Help text is read from the rendered -text in ``hack/docs/docs/``. If no rendered text exists, help is read from the -script sources (for scripts) or the string passed to the ``PluginCommand`` +text in ``hack/docs/docs/tools``. If no rendered text exists, help is read from +the script sources (for scripts) or the string passed to the ``PluginCommand`` initializer (for plugins). See `documentation` for details on how DFHack's help system works. -The database is lazy-loaded when an API method is called. It rechecks its help -sources for updates if an API method has not been called in the last 60 seconds. +The database is loaded when DFHack initializes, but can be explicitly refreshed +with a call to ``helpdb.refresh()`` if docs are added/changed during a play +session. Each entry has several properties associated with it: @@ -3345,6 +3348,10 @@ Each entry has several properties associated with it: - Long help, the entire contents of the associated help file. - A list of tags that define the groups that the entry belongs to. +* ``helpdb.refresh()`` + + Scan for changes in available commands and their documentation. + * ``helpdb.is_entry(str)``, ``helpdb.is_entry(list)`` Returns whether the given string (or list of strings) is an entry (are all diff --git a/library/Core.cpp b/library/Core.cpp index e2c983116..bdd38799f 100644 --- a/library/Core.cpp +++ b/library/Core.cpp @@ -2114,6 +2114,7 @@ void Core::onStateChange(color_ostream &out, state_change_event event) { auto L = Lua::Core::State; Lua::StackUnwinder top(L); + Lua::CallLuaModuleFunction(con, L, "helpdb", "refresh"); Lua::CallLuaModuleFunction(con, L, "script-manager", "reload"); } break; diff --git a/library/lua/helpdb.lua b/library/lua/helpdb.lua index 711555a78..df5482aec 100644 --- a/library/lua/helpdb.lua +++ b/library/lua/helpdb.lua @@ -1,23 +1,9 @@ -- The help text database and query interface. --- --- Help text is read from the rendered text in hack/docs/docs/. If no rendered --- text exists, it is read from the script sources (for scripts) or the string --- passed to the PluginCommand initializer (for plugins). --- --- There should be one help file for each plugin that contains a summary for the --- plugin itself and help for all the commands that plugin provides (if any). --- Each script should also have one documentation file. --- --- The database is lazy-loaded when an API method is called. It rechecks its --- help sources for updates if an API method has not been called in the last --- 60 seconds. local _ENV = mkmodule('helpdb') local argparse = require('argparse') -local MAX_STALE_MS = 60000 - -- paths local RENDERED_PATH = 'hack/docs/docs/tools/' local TAG_DEFINITIONS = 'hack/docs/docs/Tags.txt' @@ -415,13 +401,12 @@ local function index_tags() end end --- ensures the db is up to date by scanning all help sources. does not do --- anything if it has already been run within the last MAX_STALE_MS milliseconds -local last_refresh_ms = 0 +local needs_refresh = true + +-- ensures the db is loaded local function ensure_db() - local now_ms = dfhack.getTickCount() - if now_ms - last_refresh_ms <= MAX_STALE_MS then return end - last_refresh_ms = now_ms + if not needs_refresh then return end + needs_refresh = false local old_db = textdb textdb, entrydb, tag_index = {}, {}, {} @@ -433,6 +418,11 @@ local function ensure_db() index_tags() end +function refresh() + needs_refresh = true + ensure_db() +end + local function parse_blocks(text) local blocks = {} for line in text:gmatch('[^\n]*') do