move helpdb from autorefresh to explicit refresh

this greatly speeds up the launch time of `gui/launcher`

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

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

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;

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