Updated HTML docs

docs/1.0-dev/_modules/evennia/commands/cmdhandler.html

@@ -614,7 +614,7 @@
             <span class="n">cmd</span><span class="o">.</span><span class="n">raw_string</span> <span class="o">=</span> <span class="n">unformatted_raw_string</span>
             <span class="c1"># cmd.obj  # set via on-object cmdset handler for each command,</span>
             <span class="c1"># since this may be different for every command when</span>
-            <span class="c1"># merging multuple cmdsets</span>
+            <span class="c1"># merging multiple cmdsets</span>
 
             <span class="k">if</span> <span class="n">_testing</span><span class="p">:</span>
                 <span class="c1"># only return the command instance</span>

docs/1.0-dev/_modules/evennia/commands/default/account.html

@@ -563,11 +563,11 @@
                     <span class="k">continue</span>
                 <span class="n">delta_cmd</span> <span class="o">=</span> <span class="n">time</span><span class="o">.</span><span class="n">time</span><span class="p">()</span> <span class="o">-</span> <span class="n">session</span><span class="o">.</span><span class="n">cmd_last_visible</span>
                 <span class="n">delta_conn</span> <span class="o">=</span> <span class="n">time</span><span class="o">.</span><span class="n">time</span><span class="p">()</span> <span class="o">-</span> <span class="n">session</span><span class="o">.</span><span class="n">conn_time</span>
-                <span class="n">account</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">get_account</span><span class="p">()</span>
+                <span class="n">session_account</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">get_account</span><span class="p">()</span>
                 <span class="n">puppet</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">get_puppet</span><span class="p">()</span>
                 <span class="n">location</span> <span class="o">=</span> <span class="n">puppet</span><span class="o">.</span><span class="n">location</span><span class="o">.</span><span class="n">key</span> <span class="k">if</span> <span class="n">puppet</span> <span class="ow">and</span> <span class="n">puppet</span><span class="o">.</span><span class="n">location</span> <span class="k">else</span> <span class="s2">&quot;None&quot;</span>
                 <span class="n">table</span><span class="o">.</span><span class="n">add_row</span><span class="p">(</span>
-                    <span class="n">utils</span><span class="o">.</span><span class="n">crop</span><span class="p">(</span><span class="n">account</span><span class="o">.</span><span class="n">get_display_name</span><span class="p">(</span><span class="n">account</span><span class="p">),</span> <span class="n">width</span><span class="o">=</span><span class="mi">25</span><span class="p">),</span>
+                    <span class="n">utils</span><span class="o">.</span><span class="n">crop</span><span class="p">(</span><span class="n">session_account</span><span class="o">.</span><span class="n">get_display_name</span><span class="p">(</span><span class="n">account</span><span class="p">),</span> <span class="n">width</span><span class="o">=</span><span class="mi">25</span><span class="p">),</span>
                     <span class="n">utils</span><span class="o">.</span><span class="n">time_format</span><span class="p">(</span><span class="n">delta_conn</span><span class="p">,</span> <span class="mi">0</span><span class="p">),</span>
                     <span class="n">utils</span><span class="o">.</span><span class="n">time_format</span><span class="p">(</span><span class="n">delta_cmd</span><span class="p">,</span> <span class="mi">1</span><span class="p">),</span>
                     <span class="n">utils</span><span class="o">.</span><span class="n">crop</span><span class="p">(</span><span class="n">puppet</span><span class="o">.</span><span class="n">get_display_name</span><span class="p">(</span><span class="n">account</span><span class="p">)</span> <span class="k">if</span> <span class="n">puppet</span> <span class="k">else</span> <span class="s2">&quot;None&quot;</span><span class="p">,</span> <span class="n">width</span><span class="o">=</span><span class="mi">25</span><span class="p">),</span>
@@ -584,9 +584,9 @@
                     <span class="k">continue</span>
                 <span class="n">delta_cmd</span> <span class="o">=</span> <span class="n">time</span><span class="o">.</span><span class="n">time</span><span class="p">()</span> <span class="o">-</span> <span class="n">session</span><span class="o">.</span><span class="n">cmd_last_visible</span>
                 <span class="n">delta_conn</span> <span class="o">=</span> <span class="n">time</span><span class="o">.</span><span class="n">time</span><span class="p">()</span> <span class="o">-</span> <span class="n">session</span><span class="o">.</span><span class="n">conn_time</span>
-                <span class="n">account</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">get_account</span><span class="p">()</span>
+                <span class="n">session_account</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">get_account</span><span class="p">()</span>
                 <span class="n">table</span><span class="o">.</span><span class="n">add_row</span><span class="p">(</span>
-                    <span class="n">utils</span><span class="o">.</span><span class="n">crop</span><span class="p">(</span><span class="n">account</span><span class="o">.</span><span class="n">get_display_name</span><span class="p">(</span><span class="n">account</span><span class="p">),</span> <span class="n">width</span><span class="o">=</span><span class="mi">25</span><span class="p">),</span>
+                    <span class="n">utils</span><span class="o">.</span><span class="n">crop</span><span class="p">(</span><span class="n">session_account</span><span class="o">.</span><span class="n">get_display_name</span><span class="p">(</span><span class="n">account</span><span class="p">),</span> <span class="n">width</span><span class="o">=</span><span class="mi">25</span><span class="p">),</span>
                     <span class="n">utils</span><span class="o">.</span><span class="n">time_format</span><span class="p">(</span><span class="n">delta_conn</span><span class="p">,</span> <span class="mi">0</span><span class="p">),</span>
                     <span class="n">utils</span><span class="o">.</span><span class="n">time_format</span><span class="p">(</span><span class="n">delta_cmd</span><span class="p">,</span> <span class="mi">1</span><span class="p">),</span>
                 <span class="p">)</span>

docs/1.0-dev/_modules/evennia/commands/default/general.html

@@ -45,7 +45,7 @@
 <span class="sd">&quot;&quot;&quot;</span>
 <span class="kn">import</span> <span class="nn">re</span>
 <span class="kn">from</span> <span class="nn">django.conf</span> <span class="kn">import</span> <span class="n">settings</span>
-<span class="kn">from</span> <span class="nn">evennia.utils</span> <span class="kn">import</span> <span class="n">utils</span><span class="p">,</span> <span class="n">evtable</span>
+<span class="kn">from</span> <span class="nn">evennia.utils</span> <span class="kn">import</span> <span class="n">utils</span>
 <span class="kn">from</span> <span class="nn">evennia.typeclasses.attributes</span> <span class="kn">import</span> <span class="n">NickTemplateInvalid</span>
 
 <span class="n">COMMAND_DEFAULT_CLASS</span> <span class="o">=</span> <span class="n">utils</span><span class="o">.</span><span class="n">class_from_module</span><span class="p">(</span><span class="n">settings</span><span class="o">.</span><span class="n">COMMAND_DEFAULT_CLASS</span><span class="p">)</span>
@@ -442,7 +442,7 @@
 
     <span class="n">key</span> <span class="o">=</span> <span class="s2">&quot;get&quot;</span>
     <span class="n">aliases</span> <span class="o">=</span> <span class="s2">&quot;grab&quot;</span>
-    <span class="n">locks</span> <span class="o">=</span> <span class="s2">&quot;cmd:all()&quot;</span>
+    <span class="n">locks</span> <span class="o">=</span> <span class="s2">&quot;cmd:all();view:perm(Developer);read:perm(Developer)&quot;</span>
     <span class="n">arg_regex</span> <span class="o">=</span> <span class="sa">r</span><span class="s2">&quot;\s|$&quot;</span>
 
 <div class="viewcode-block" id="CmdGet.func"><a class="viewcode-back" href="../../../../api/evennia.commands.default.general.html#evennia.commands.default.general.CmdGet.func">[docs]</a>    <span class="k">def</span> <span class="nf">func</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>

docs/1.0-dev/_modules/evennia/commands/default/help.html

@@ -50,16 +50,16 @@
 
 <span class="sd">&quot;&quot;&quot;</span>
 
-<span class="kn">import</span> <span class="nn">re</span>
 <span class="kn">from</span> <span class="nn">dataclasses</span> <span class="kn">import</span> <span class="n">dataclass</span>
 <span class="kn">from</span> <span class="nn">django.conf</span> <span class="kn">import</span> <span class="n">settings</span>
 <span class="kn">from</span> <span class="nn">collections</span> <span class="kn">import</span> <span class="n">defaultdict</span>
-<span class="kn">from</span> <span class="nn">evennia.utils.utils</span> <span class="kn">import</span> <span class="n">fill</span><span class="p">,</span> <span class="n">dedent</span>
+<span class="kn">from</span> <span class="nn">evennia.utils.utils</span> <span class="kn">import</span> <span class="n">dedent</span>
 <span class="kn">from</span> <span class="nn">evennia.help.models</span> <span class="kn">import</span> <span class="n">HelpEntry</span>
 <span class="kn">from</span> <span class="nn">evennia.utils</span> <span class="kn">import</span> <span class="n">create</span><span class="p">,</span> <span class="n">evmore</span>
 <span class="kn">from</span> <span class="nn">evennia.utils.ansi</span> <span class="kn">import</span> <span class="n">ANSIString</span>
 <span class="kn">from</span> <span class="nn">evennia.help.filehelp</span> <span class="kn">import</span> <span class="n">FILE_HELP_ENTRIES</span>
 <span class="kn">from</span> <span class="nn">evennia.utils.eveditor</span> <span class="kn">import</span> <span class="n">EvEditor</span>
+<span class="kn">from</span> <span class="nn">evennia.utils.evmenu</span> <span class="kn">import</span> <span class="n">ask_yes_no</span>
 <span class="kn">from</span> <span class="nn">evennia.utils.utils</span> <span class="kn">import</span> <span class="p">(</span>
     <span class="n">class_from_module</span><span class="p">,</span>
     <span class="n">inherits_from</span><span class="p">,</span>
@@ -301,46 +301,165 @@
 
         <span class="k">return</span> <span class="n">help_index</span></div>
 
-<div class="viewcode-block" id="CmdHelp.check_show_help"><a class="viewcode-back" href="../../../../api/evennia.commands.default.help.html#evennia.commands.default.help.CmdHelp.check_show_help">[docs]</a>    <span class="k">def</span> <span class="nf">check_show_help</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">cmd</span><span class="p">,</span> <span class="n">caller</span><span class="p">):</span>
+<div class="viewcode-block" id="CmdHelp.can_read_topic"><a class="viewcode-back" href="../../../../api/evennia.commands.default.help.html#evennia.commands.default.help.CmdHelp.can_read_topic">[docs]</a>    <span class="k">def</span> <span class="nf">can_read_topic</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">cmd_or_topic</span><span class="p">,</span> <span class="n">caller</span><span class="p">):</span>
         <span class="sd">&quot;&quot;&quot;</span>
-<span class="sd">        Helper method. If this return True, the given cmd</span>
-<span class="sd">        auto-help will be viewable in the help listing.</span>
-<span class="sd">        Override this to easily select what is shown to</span>
-<span class="sd">        the account. Note that only commands available</span>
-<span class="sd">        in the caller&#39;s merged cmdset are available.</span>
+<span class="sd">        Helper method. If this return True, the given help topic</span>
+<span class="sd">        be viewable in the help listing. Note that even if this returns False,</span>
+<span class="sd">        the entry will still be visible in the help index unless `should_list_topic`</span>
+<span class="sd">        is also returning False.</span>
 
 <span class="sd">        Args:</span>
-<span class="sd">            cmd (Command): Command class from the merged cmdset</span>
-<span class="sd">            caller (Character, Account or Session): The current caller</span>
-<span class="sd">                executing the help command.</span>
+<span class="sd">            cmd_or_topic (Command, HelpEntry or FileHelpEntry): The topic/command to test.</span>
+<span class="sd">            caller: the caller checking for access.</span>
+
+<span class="sd">        Returns:</span>
+<span class="sd">            bool: If command can be viewed or not.</span>
+
+<span class="sd">        Notes:</span>
+<span class="sd">            This uses the &#39;read&#39; lock. If no &#39;read&#39; lock is defined, the topic is assumed readable</span>
+<span class="sd">            by all.</span>
 
 <span class="sd">        &quot;&quot;&quot;</span>
-        <span class="c1"># return only those with auto_help set and passing the cmd: lock</span>
-        <span class="k">return</span> <span class="n">cmd</span><span class="o">.</span><span class="n">auto_help</span> <span class="ow">and</span> <span class="n">cmd</span><span class="o">.</span><span class="n">access</span><span class="p">(</span><span class="n">caller</span><span class="p">)</span></div>
+        <span class="k">if</span> <span class="n">inherits_from</span><span class="p">(</span><span class="n">cmd_or_topic</span><span class="p">,</span> <span class="s2">&quot;evennia.commands.command.Command&quot;</span><span class="p">):</span>
+            <span class="k">return</span> <span class="n">cmd_or_topic</span><span class="o">.</span><span class="n">auto_help</span> <span class="ow">and</span> <span class="n">cmd_or_topic</span><span class="o">.</span><span class="n">access</span><span class="p">(</span><span class="n">caller</span><span class="p">,</span> <span class="s1">&#39;read&#39;</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
+        <span class="k">else</span><span class="p">:</span>
+            <span class="k">return</span> <span class="n">cmd_or_topic</span><span class="o">.</span><span class="n">access</span><span class="p">(</span><span class="n">caller</span><span class="p">,</span> <span class="s1">&#39;read&#39;</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span></div>
 
-<div class="viewcode-block" id="CmdHelp.should_list_cmd"><a class="viewcode-back" href="../../../../api/evennia.commands.default.help.html#evennia.commands.default.help.CmdHelp.should_list_cmd">[docs]</a>    <span class="k">def</span> <span class="nf">should_list_cmd</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">cmd</span><span class="p">,</span> <span class="n">caller</span><span class="p">):</span>
+<div class="viewcode-block" id="CmdHelp.can_list_topic"><a class="viewcode-back" href="../../../../api/evennia.commands.default.help.html#evennia.commands.default.help.CmdHelp.can_list_topic">[docs]</a>    <span class="k">def</span> <span class="nf">can_list_topic</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">cmd_or_topic</span><span class="p">,</span> <span class="n">caller</span><span class="p">):</span>
         <span class="sd">&quot;&quot;&quot;</span>
 <span class="sd">        Should the specified command appear in the help table?</span>
 
-<span class="sd">        This method only checks whether a specified command should</span>
-<span class="sd">        appear in the table of topics/commands.  The command can be</span>
-<span class="sd">        used by the caller (see the &#39;check_show_help&#39; method) and</span>
-<span class="sd">        the command will still be available, for instance, if a</span>
-<span class="sd">        character type &#39;help name of the command&#39;.  However, if</span>
-<span class="sd">        you return False, the specified command will not appear in</span>
-<span class="sd">        the table.  This is sometimes useful to &quot;hide&quot; commands in</span>
-<span class="sd">        the table, but still access them through the help system.</span>
+<span class="sd">        This method only checks whether a specified command should appear in the table of</span>
+<span class="sd">        topics/commands.  The command can be used by the caller (see the &#39;should_show_help&#39; method)</span>
+<span class="sd">        and the command will still be available, for instance, if a character type &#39;help name of the</span>
+<span class="sd">        command&#39;.  However, if you return False, the specified command will not appear in the table.</span>
+<span class="sd">        This is sometimes useful to &quot;hide&quot; commands in the table, but still access them through the</span>
+<span class="sd">        help system.</span>
 
 <span class="sd">        Args:</span>
-<span class="sd">            cmd: the command to be tested.</span>
-<span class="sd">            caller: the caller of the help system.</span>
+<span class="sd">            cmd_or_topic (Command, HelpEntry or FileHelpEntry): The topic/command to test.</span>
+<span class="sd">            caller: the caller checking for access.</span>
 
-<span class="sd">        Return:</span>
-<span class="sd">            True: the command should appear in the table.</span>
-<span class="sd">            False: the command shouldn&#39;t appear in the table.</span>
+<span class="sd">        Returns:</span>
+<span class="sd">            bool: If command should be listed or not.</span>
+
+<span class="sd">        Notes:</span>
+<span class="sd">            By default, the &#39;view&#39; lock will be checked, and if no such lock is defined, the &#39;read&#39;</span>
+<span class="sd">            lock will be used. If neither lock is defined, the help entry is assumed to be</span>
+<span class="sd">            accessible to all.</span>
 
 <span class="sd">        &quot;&quot;&quot;</span>
-        <span class="k">return</span> <span class="kc">True</span></div>
+        <span class="n">has_view</span> <span class="o">=</span> <span class="p">(</span>
+            <span class="s2">&quot;view:&quot;</span> <span class="ow">in</span> <span class="n">cmd_or_topic</span><span class="o">.</span><span class="n">locks</span>
+            <span class="k">if</span> <span class="n">inherits_from</span><span class="p">(</span><span class="n">cmd_or_topic</span><span class="p">,</span> <span class="s2">&quot;evennia.commands.command.Command&quot;</span><span class="p">)</span>
+            <span class="k">else</span> <span class="n">cmd_or_topic</span><span class="o">.</span><span class="n">locks</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;view&quot;</span><span class="p">)</span>
+        <span class="p">)</span>
+
+        <span class="k">if</span> <span class="n">has_view</span><span class="p">:</span>
+            <span class="k">return</span> <span class="n">cmd_or_topic</span><span class="o">.</span><span class="n">access</span><span class="p">(</span><span class="n">caller</span><span class="p">,</span> <span class="s1">&#39;view&#39;</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
+        <span class="k">else</span><span class="p">:</span>
+            <span class="c1"># no explicit &#39;view&#39; lock - use the &#39;read&#39; lock</span>
+            <span class="k">return</span> <span class="n">cmd_or_topic</span><span class="o">.</span><span class="n">access</span><span class="p">(</span><span class="n">caller</span><span class="p">,</span> <span class="s1">&#39;read&#39;</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span></div>
+
+<div class="viewcode-block" id="CmdHelp.collect_topics"><a class="viewcode-back" href="../../../../api/evennia.commands.default.help.html#evennia.commands.default.help.CmdHelp.collect_topics">[docs]</a>    <span class="k">def</span> <span class="nf">collect_topics</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">caller</span><span class="p">,</span> <span class="n">mode</span><span class="o">=</span><span class="s1">&#39;list&#39;</span><span class="p">):</span>
+        <span class="sd">&quot;&quot;&quot;</span>
+<span class="sd">        Collect help topics from all sources (cmd/db/file).</span>
+
+<span class="sd">        Args:</span>
+<span class="sd">            caller (Object or Account): The user of the Command.</span>
+<span class="sd">            mode (str): One of &#39;list&#39; or &#39;query&#39;, where the first means we are collecting to view</span>
+<span class="sd">                the help index and the second because of wanting to search for a specific help</span>
+<span class="sd">                entry/cmd to read. This determines which access should be checked.</span>
+
+<span class="sd">        Returns:</span>
+<span class="sd">            tuple: A tuple of three dicts containing the different types of help entries</span>
+<span class="sd">            in the order cmd-help, db-help, file-help:</span>
+<span class="sd">                `({key: cmd,...}, {key: dbentry,...}, {key: fileentry,...}`</span>
+
+<span class="sd">        &quot;&quot;&quot;</span>
+        <span class="c1"># start with cmd-help</span>
+        <span class="n">cmdset</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">cmdset</span>
+        <span class="c1"># removing doublets in cmdset, caused by cmdhandler</span>
+        <span class="c1"># having to allow doublet commands to manage exits etc.</span>
+        <span class="n">cmdset</span><span class="o">.</span><span class="n">make_unique</span><span class="p">(</span><span class="n">caller</span><span class="p">)</span>
+        <span class="c1"># retrieve all available commands and database / file-help topics.</span>
+        <span class="c1"># also check the &#39;cmd:&#39; lock here</span>
+        <span class="n">cmd_help_topics</span> <span class="o">=</span> <span class="p">[</span><span class="n">cmd</span> <span class="k">for</span> <span class="n">cmd</span> <span class="ow">in</span> <span class="n">cmdset</span> <span class="k">if</span> <span class="n">cmd</span> <span class="ow">and</span> <span class="n">cmd</span><span class="o">.</span><span class="n">access</span><span class="p">(</span><span class="n">caller</span><span class="p">,</span> <span class="s1">&#39;cmd&#39;</span><span class="p">)]</span>
+        <span class="c1"># get all file-based help entries, checking perms</span>
+        <span class="n">file_help_topics</span> <span class="o">=</span> <span class="p">{</span>
+            <span class="n">topic</span><span class="o">.</span><span class="n">key</span><span class="o">.</span><span class="n">lower</span><span class="p">()</span><span class="o">.</span><span class="n">strip</span><span class="p">():</span> <span class="n">topic</span>
+            <span class="k">for</span> <span class="n">topic</span> <span class="ow">in</span> <span class="n">FILE_HELP_ENTRIES</span><span class="o">.</span><span class="n">all</span><span class="p">()</span>
+        <span class="p">}</span>
+        <span class="c1"># get db-based help entries, checking perms</span>
+        <span class="n">db_help_topics</span> <span class="o">=</span> <span class="p">{</span>
+            <span class="n">topic</span><span class="o">.</span><span class="n">key</span><span class="o">.</span><span class="n">lower</span><span class="p">()</span><span class="o">.</span><span class="n">strip</span><span class="p">():</span> <span class="n">topic</span>
+            <span class="k">for</span> <span class="n">topic</span> <span class="ow">in</span> <span class="n">HelpEntry</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">all</span><span class="p">()</span>
+        <span class="p">}</span>
+        <span class="k">if</span> <span class="n">mode</span> <span class="o">==</span> <span class="s1">&#39;list&#39;</span><span class="p">:</span>
+            <span class="c1"># check the view lock for all help entries/commands and determine key</span>
+            <span class="n">cmd_help_topics</span> <span class="o">=</span> <span class="p">{</span>
+                <span class="n">cmd</span><span class="o">.</span><span class="n">auto_help_display_key</span>
+                <span class="k">if</span> <span class="nb">hasattr</span><span class="p">(</span><span class="n">cmd</span><span class="p">,</span> <span class="s2">&quot;auto_help_display_key&quot;</span><span class="p">)</span> <span class="k">else</span> <span class="n">cmd</span><span class="o">.</span><span class="n">key</span><span class="p">:</span> <span class="n">cmd</span>
+                <span class="k">for</span> <span class="n">cmd</span> <span class="ow">in</span> <span class="n">cmd_help_topics</span> <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">can_list_topic</span><span class="p">(</span><span class="n">cmd</span><span class="p">,</span> <span class="n">caller</span><span class="p">)}</span>
+            <span class="n">db_help_topics</span> <span class="o">=</span> <span class="p">{</span>
+                <span class="n">key</span><span class="p">:</span> <span class="n">entry</span> <span class="k">for</span> <span class="n">key</span><span class="p">,</span> <span class="n">entry</span> <span class="ow">in</span> <span class="n">db_help_topics</span><span class="o">.</span><span class="n">items</span><span class="p">()</span>
+                <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">can_list_topic</span><span class="p">(</span><span class="n">entry</span><span class="p">,</span> <span class="n">caller</span><span class="p">)</span>
+            <span class="p">}</span>
+            <span class="n">file_help_topics</span> <span class="o">=</span> <span class="p">{</span>
+                <span class="n">key</span><span class="p">:</span> <span class="n">entry</span> <span class="k">for</span> <span class="n">key</span><span class="p">,</span> <span class="n">entry</span> <span class="ow">in</span> <span class="n">file_help_topics</span><span class="o">.</span><span class="n">items</span><span class="p">()</span>
+                <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">can_list_topic</span><span class="p">(</span><span class="n">entry</span><span class="p">,</span> <span class="n">caller</span><span class="p">)}</span>
+        <span class="k">else</span><span class="p">:</span>
+            <span class="c1"># query</span>
+            <span class="n">cmd_help_topics</span> <span class="o">=</span> <span class="p">{</span>
+                <span class="n">cmd</span><span class="o">.</span><span class="n">auto_help_display_key</span>
+                <span class="k">if</span> <span class="nb">hasattr</span><span class="p">(</span><span class="n">cmd</span><span class="p">,</span> <span class="s2">&quot;auto_help_display_key&quot;</span><span class="p">)</span> <span class="k">else</span> <span class="n">cmd</span><span class="o">.</span><span class="n">key</span><span class="p">:</span> <span class="n">cmd</span>
+                <span class="k">for</span> <span class="n">cmd</span> <span class="ow">in</span> <span class="n">cmd_help_topics</span> <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">can_read_topic</span><span class="p">(</span><span class="n">cmd</span><span class="p">,</span> <span class="n">caller</span><span class="p">)}</span>
+            <span class="n">db_help_topics</span> <span class="o">=</span> <span class="p">{</span>
+                <span class="n">key</span><span class="p">:</span> <span class="n">entry</span> <span class="k">for</span> <span class="n">key</span><span class="p">,</span> <span class="n">entry</span> <span class="ow">in</span> <span class="n">db_help_topics</span><span class="o">.</span><span class="n">items</span><span class="p">()</span>
+                <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">can_read_topic</span><span class="p">(</span><span class="n">entry</span><span class="p">,</span> <span class="n">caller</span><span class="p">)</span>
+            <span class="p">}</span>
+            <span class="n">file_help_topics</span> <span class="o">=</span> <span class="p">{</span>
+                <span class="n">key</span><span class="p">:</span> <span class="n">entry</span> <span class="k">for</span> <span class="n">key</span><span class="p">,</span> <span class="n">entry</span> <span class="ow">in</span> <span class="n">file_help_topics</span><span class="o">.</span><span class="n">items</span><span class="p">()</span>
+                <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">can_read_topic</span><span class="p">(</span><span class="n">entry</span><span class="p">,</span> <span class="n">caller</span><span class="p">)}</span>
+
+        <span class="k">return</span> <span class="n">cmd_help_topics</span><span class="p">,</span> <span class="n">db_help_topics</span><span class="p">,</span> <span class="n">file_help_topics</span></div>
+
+<div class="viewcode-block" id="CmdHelp.do_search"><a class="viewcode-back" href="../../../../api/evennia.commands.default.help.html#evennia.commands.default.help.CmdHelp.do_search">[docs]</a>    <span class="k">def</span> <span class="nf">do_search</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">query</span><span class="p">,</span> <span class="n">entries</span><span class="p">,</span> <span class="n">search_fields</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
+        <span class="sd">&quot;&quot;&quot;</span>
+<span class="sd">        Perform a help-query search, default using Lunr search engine.</span>
+
+<span class="sd">        Args:</span>
+<span class="sd">            query (str): The help entry to search for.</span>
+<span class="sd">            entries (list): All possibilities. A mix of commands, HelpEntries and FileHelpEntries.</span>
+<span class="sd">            search_fields (list): A list of dicts defining how Lunr will find the</span>
+<span class="sd">                search data on the elements. If not given, will use a default.</span>
+
+<span class="sd">        Returns:</span>
+<span class="sd">            tuple: A tuple (match, suggestions).</span>
+
+<span class="sd">        &quot;&quot;&quot;</span>
+        <span class="k">if</span> <span class="ow">not</span> <span class="n">search_fields</span><span class="p">:</span>
+            <span class="c1"># lunr search fields/boosts</span>
+            <span class="n">search_fields</span> <span class="o">=</span> <span class="p">[</span>
+                <span class="p">{</span><span class="s2">&quot;field_name&quot;</span><span class="p">:</span> <span class="s2">&quot;key&quot;</span><span class="p">,</span> <span class="s2">&quot;boost&quot;</span><span class="p">:</span> <span class="mi">10</span><span class="p">},</span>
+                <span class="p">{</span><span class="s2">&quot;field_name&quot;</span><span class="p">:</span> <span class="s2">&quot;aliases&quot;</span><span class="p">,</span> <span class="s2">&quot;boost&quot;</span><span class="p">:</span> <span class="mi">9</span><span class="p">},</span>
+                <span class="p">{</span><span class="s2">&quot;field_name&quot;</span><span class="p">:</span> <span class="s2">&quot;category&quot;</span><span class="p">,</span> <span class="s2">&quot;boost&quot;</span><span class="p">:</span> <span class="mi">8</span><span class="p">},</span>
+                <span class="p">{</span><span class="s2">&quot;field_name&quot;</span><span class="p">:</span> <span class="s2">&quot;tags&quot;</span><span class="p">,</span> <span class="s2">&quot;boost&quot;</span><span class="p">:</span> <span class="mi">1</span><span class="p">},</span>  <span class="c1"># tags are not used by default</span>
+            <span class="p">]</span>
+        <span class="n">match</span><span class="p">,</span> <span class="n">suggestions</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span> <span class="kc">None</span>
+        <span class="k">for</span> <span class="n">match_query</span> <span class="ow">in</span> <span class="p">(</span><span class="n">query</span><span class="p">,</span> <span class="sa">f</span><span class="s2">&quot;</span><span class="si">{</span><span class="n">query</span><span class="si">}</span><span class="s2">*&quot;</span><span class="p">):</span>
+            <span class="c1"># We first do an exact word-match followed by a start-by query. The</span>
+            <span class="c1"># return of this will either be a HelpCategory, a Command or a</span>
+            <span class="c1"># HelpEntry/FileHelpEntry.</span>
+            <span class="n">matches</span><span class="p">,</span> <span class="n">suggestions</span> <span class="o">=</span> <span class="n">help_search_with_index</span><span class="p">(</span>
+                <span class="n">match_query</span><span class="p">,</span> <span class="n">entries</span><span class="p">,</span>
+                <span class="n">suggestion_maxnum</span><span class="o">=</span><span class="bp">self</span><span class="o">.</span><span class="n">suggestion_maxnum</span><span class="p">,</span>
+                <span class="n">fields</span><span class="o">=</span><span class="n">search_fields</span>
+            <span class="p">)</span>
+            <span class="k">if</span> <span class="n">matches</span><span class="p">:</span>
+                <span class="n">match</span> <span class="o">=</span> <span class="n">matches</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
+                <span class="k">break</span>
+        <span class="k">return</span> <span class="n">match</span><span class="p">,</span> <span class="n">suggestions</span></div>
 
 <div class="viewcode-block" id="CmdHelp.parse"><a class="viewcode-back" href="../../../../api/evennia.commands.default.help.html#evennia.commands.default.help.CmdHelp.parse">[docs]</a>    <span class="k">def</span> <span class="nf">parse</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
         <span class="sd">&quot;&quot;&quot;</span>
@@ -373,75 +492,52 @@
         <span class="n">caller</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">caller</span>
         <span class="n">query</span><span class="p">,</span> <span class="n">subtopics</span><span class="p">,</span> <span class="n">cmdset</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">topic</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">subtopics</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">cmdset</span>
 
-        <span class="c1"># removing doublets in cmdset, caused by cmdhandler</span>
-        <span class="c1"># having to allow doublet commands to manage exits etc.</span>
-        <span class="n">cmdset</span><span class="o">.</span><span class="n">make_unique</span><span class="p">(</span><span class="n">caller</span><span class="p">)</span>
-
-        <span class="c1"># retrieve all available commands and database / file-help topics</span>
-        <span class="n">all_cmds</span> <span class="o">=</span> <span class="p">[</span><span class="n">cmd</span> <span class="k">for</span> <span class="n">cmd</span> <span class="ow">in</span> <span class="n">cmdset</span> <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">check_show_help</span><span class="p">(</span><span class="n">cmd</span><span class="p">,</span> <span class="n">caller</span><span class="p">)]</span>
-
-        <span class="c1"># we group the file-help topics with the db ones, giving the db ones priority</span>
-        <span class="n">file_help_topics</span> <span class="o">=</span> <span class="n">FILE_HELP_ENTRIES</span><span class="o">.</span><span class="n">all</span><span class="p">(</span><span class="n">return_dict</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
-        <span class="n">db_topics</span> <span class="o">=</span> <span class="p">{</span>
-            <span class="n">topic</span><span class="o">.</span><span class="n">key</span><span class="o">.</span><span class="n">lower</span><span class="p">()</span><span class="o">.</span><span class="n">strip</span><span class="p">():</span> <span class="n">topic</span> <span class="k">for</span> <span class="n">topic</span> <span class="ow">in</span> <span class="n">HelpEntry</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">all</span><span class="p">()</span>
-            <span class="k">if</span> <span class="n">topic</span><span class="o">.</span><span class="n">access</span><span class="p">(</span><span class="n">caller</span><span class="p">,</span> <span class="s2">&quot;view&quot;</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
-        <span class="p">}</span>
-        <span class="n">all_db_topics</span> <span class="o">=</span> <span class="nb">list</span><span class="p">({</span><span class="o">**</span><span class="n">file_help_topics</span><span class="p">,</span> <span class="o">**</span><span class="n">db_topics</span><span class="p">}</span><span class="o">.</span><span class="n">values</span><span class="p">())</span>
-
-        <span class="n">all_categories</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="nb">set</span><span class="p">(</span>
-            <span class="p">[</span><span class="n">HelpCategory</span><span class="p">(</span><span class="n">cmd</span><span class="o">.</span><span class="n">help_category</span><span class="p">)</span> <span class="k">for</span> <span class="n">cmd</span> <span class="ow">in</span> <span class="n">all_cmds</span><span class="p">]</span>
-            <span class="o">+</span> <span class="p">[</span><span class="n">HelpCategory</span><span class="p">(</span><span class="n">topic</span><span class="o">.</span><span class="n">help_category</span><span class="p">)</span> <span class="k">for</span> <span class="n">topic</span> <span class="ow">in</span> <span class="n">all_db_topics</span><span class="p">]</span>
-        <span class="p">))</span>
-
         <span class="k">if</span> <span class="ow">not</span> <span class="n">query</span><span class="p">:</span>
             <span class="c1"># list all available help entries, grouped by category. We want to</span>
             <span class="c1"># build dictionaries {category: [topic, topic, ...], ...}</span>
-            <span class="n">cmd_help_dict</span> <span class="o">=</span> <span class="n">defaultdict</span><span class="p">(</span><span class="nb">list</span><span class="p">)</span>
-            <span class="n">db_help_dict</span> <span class="o">=</span> <span class="n">defaultdict</span><span class="p">(</span><span class="nb">list</span><span class="p">)</span>
 
-            <span class="c1"># Filter commands that should be reached by the help</span>
-            <span class="c1"># system, but not be displayed in the table, or be displayed differently.</span>
-            <span class="k">for</span> <span class="n">cmd</span> <span class="ow">in</span> <span class="n">all_cmds</span><span class="p">:</span>
-                <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">should_list_cmd</span><span class="p">(</span><span class="n">cmd</span><span class="p">,</span> <span class="n">caller</span><span class="p">):</span>
-                    <span class="n">key</span> <span class="o">=</span> <span class="p">(</span><span class="n">cmd</span><span class="o">.</span><span class="n">auto_help_display_key</span>
-                           <span class="k">if</span> <span class="nb">hasattr</span><span class="p">(</span><span class="n">cmd</span><span class="p">,</span> <span class="s2">&quot;auto_help_display_key&quot;</span><span class="p">)</span> <span class="k">else</span> <span class="n">cmd</span><span class="o">.</span><span class="n">key</span><span class="p">)</span>
-                    <span class="n">cmd_help_dict</span><span class="p">[</span><span class="n">cmd</span><span class="o">.</span><span class="n">help_category</span><span class="p">]</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">key</span><span class="p">)</span>
+            <span class="n">cmd_help_topics</span><span class="p">,</span> <span class="n">db_help_topics</span><span class="p">,</span> <span class="n">file_help_topics</span> <span class="o">=</span> \
+                <span class="bp">self</span><span class="o">.</span><span class="n">collect_topics</span><span class="p">(</span><span class="n">caller</span><span class="p">,</span> <span class="n">mode</span><span class="o">=</span><span class="s1">&#39;list&#39;</span><span class="p">)</span>
 
-            <span class="k">for</span> <span class="n">db_topic</span> <span class="ow">in</span> <span class="n">all_db_topics</span><span class="p">:</span>
-                <span class="n">db_help_dict</span><span class="p">[</span><span class="n">db_topic</span><span class="o">.</span><span class="n">help_category</span><span class="p">]</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">db_topic</span><span class="o">.</span><span class="n">key</span><span class="p">)</span>
+            <span class="c1"># db-topics override file-based ones</span>
+            <span class="n">file_db_help_topics</span> <span class="o">=</span> <span class="p">{</span><span class="o">**</span><span class="n">file_help_topics</span><span class="p">,</span> <span class="o">**</span><span class="n">db_help_topics</span><span class="p">}</span>
 
-            <span class="n">output</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">format_help_index</span><span class="p">(</span><span class="n">cmd_help_dict</span><span class="p">,</span> <span class="n">db_help_dict</span><span class="p">)</span>
+            <span class="c1"># group by category (cmds are listed separately)</span>
+            <span class="n">cmd_help_by_category</span> <span class="o">=</span> <span class="n">defaultdict</span><span class="p">(</span><span class="nb">list</span><span class="p">)</span>
+            <span class="n">file_db_help_by_category</span> <span class="o">=</span> <span class="n">defaultdict</span><span class="p">(</span><span class="nb">list</span><span class="p">)</span>
+            <span class="k">for</span> <span class="n">key</span><span class="p">,</span> <span class="n">cmd</span> <span class="ow">in</span> <span class="n">cmd_help_topics</span><span class="o">.</span><span class="n">items</span><span class="p">():</span>
+                <span class="n">cmd_help_by_category</span><span class="p">[</span><span class="n">cmd</span><span class="o">.</span><span class="n">help_category</span><span class="p">]</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">key</span><span class="p">)</span>
+            <span class="k">for</span> <span class="n">key</span><span class="p">,</span> <span class="n">entry</span> <span class="ow">in</span> <span class="n">file_db_help_topics</span><span class="o">.</span><span class="n">items</span><span class="p">():</span>
+                <span class="n">file_db_help_by_category</span><span class="p">[</span><span class="n">entry</span><span class="o">.</span><span class="n">help_category</span><span class="p">]</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">key</span><span class="p">)</span>
+
+            <span class="c1"># generate the index and display</span>
+            <span class="n">output</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">format_help_index</span><span class="p">(</span><span class="n">cmd_help_by_category</span><span class="p">,</span>
+                                            <span class="n">file_db_help_by_category</span><span class="p">)</span>
             <span class="bp">self</span><span class="o">.</span><span class="n">msg_help</span><span class="p">(</span><span class="n">output</span><span class="p">)</span>
 
             <span class="k">return</span>
 
-        <span class="c1"># We have a query - try to find a specific topic/category using the</span>
-        <span class="c1"># Lunr search engine</span>
+        <span class="c1"># search for a specific entry. We need to check for &#39;read&#39; access here before # building the</span>
+        <span class="c1"># set of possibilities.</span>
+        <span class="n">cmd_help_topics</span><span class="p">,</span> <span class="n">db_help_topics</span><span class="p">,</span> <span class="n">file_help_topics</span> <span class="o">=</span> \
+            <span class="bp">self</span><span class="o">.</span><span class="n">collect_topics</span><span class="p">(</span><span class="n">caller</span><span class="p">,</span> <span class="n">mode</span><span class="o">=</span><span class="s1">&#39;query&#39;</span><span class="p">)</span>
 
-        <span class="c1"># all available options</span>
-        <span class="n">entries</span> <span class="o">=</span> <span class="p">[</span><span class="n">cmd</span> <span class="k">for</span> <span class="n">cmd</span> <span class="ow">in</span> <span class="n">all_cmds</span> <span class="k">if</span> <span class="n">cmd</span><span class="p">]</span> <span class="o">+</span> <span class="n">all_db_topics</span> <span class="o">+</span> <span class="n">all_categories</span>
+        <span class="c1"># db-help topics takes priority over file-help</span>
+        <span class="n">file_db_help_topics</span> <span class="o">=</span> <span class="p">{</span><span class="o">**</span><span class="n">file_help_topics</span><span class="p">,</span> <span class="o">**</span><span class="n">db_help_topics</span><span class="p">}</span>
+
+        <span class="c1"># commands take priority over the other types</span>
+        <span class="n">all_topics</span> <span class="o">=</span> <span class="p">{</span><span class="o">**</span><span class="n">file_db_help_topics</span><span class="p">,</span> <span class="o">**</span><span class="n">cmd_help_topics</span><span class="p">}</span>
+
+        <span class="c1"># get all categories</span>
+        <span class="n">all_categories</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="nb">set</span><span class="p">(</span>
+            <span class="n">HelpCategory</span><span class="p">(</span><span class="n">topic</span><span class="o">.</span><span class="n">help_category</span><span class="p">)</span> <span class="k">for</span> <span class="n">topic</span> <span class="ow">in</span> <span class="n">all_topics</span><span class="o">.</span><span class="n">values</span><span class="p">()))</span>
+
+        <span class="c1"># all available help options - will be searched in order. We also check # the</span>
+        <span class="c1"># read-permission here.</span>
+        <span class="n">entries</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="n">all_topics</span><span class="o">.</span><span class="n">values</span><span class="p">())</span> <span class="o">+</span> <span class="n">all_categories</span>
 
         <span class="c1"># lunr search fields/boosts</span>
-        <span class="n">search_fields</span> <span class="o">=</span> <span class="p">[</span>
-            <span class="p">{</span><span class="s2">&quot;field_name&quot;</span><span class="p">:</span> <span class="s2">&quot;key&quot;</span><span class="p">,</span> <span class="s2">&quot;boost&quot;</span><span class="p">:</span> <span class="mi">10</span><span class="p">},</span>
-            <span class="p">{</span><span class="s2">&quot;field_name&quot;</span><span class="p">:</span> <span class="s2">&quot;aliases&quot;</span><span class="p">,</span> <span class="s2">&quot;boost&quot;</span><span class="p">:</span> <span class="mi">9</span><span class="p">},</span>
-            <span class="p">{</span><span class="s2">&quot;field_name&quot;</span><span class="p">:</span> <span class="s2">&quot;category&quot;</span><span class="p">,</span> <span class="s2">&quot;boost&quot;</span><span class="p">:</span> <span class="mi">8</span><span class="p">},</span>
-            <span class="p">{</span><span class="s2">&quot;field_name&quot;</span><span class="p">:</span> <span class="s2">&quot;tags&quot;</span><span class="p">,</span> <span class="s2">&quot;boost&quot;</span><span class="p">:</span> <span class="mi">1</span><span class="p">},</span>  <span class="c1"># tags are not used by default</span>
-        <span class="p">]</span>
-        <span class="n">match</span><span class="p">,</span> <span class="n">suggestions</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span> <span class="kc">None</span>
-
-        <span class="k">for</span> <span class="n">match_query</span> <span class="ow">in</span> <span class="p">(</span><span class="n">query</span><span class="p">,</span> <span class="sa">f</span><span class="s2">&quot;</span><span class="si">{</span><span class="n">query</span><span class="si">}</span><span class="s2">*&quot;</span><span class="p">):</span>
-            <span class="c1"># We first do an exact word-match followed by a start-by query. The</span>
-            <span class="c1"># return of this will either be a HelpCategory, a Command or a</span>
-            <span class="c1"># HelpEntry/FileHelpEntry.</span>
-            <span class="n">matches</span><span class="p">,</span> <span class="n">suggestions</span> <span class="o">=</span> <span class="n">help_search_with_index</span><span class="p">(</span>
-                <span class="n">match_query</span><span class="p">,</span> <span class="n">entries</span><span class="p">,</span>
-                <span class="n">suggestion_maxnum</span><span class="o">=</span><span class="bp">self</span><span class="o">.</span><span class="n">suggestion_maxnum</span><span class="p">,</span>
-                <span class="n">fields</span><span class="o">=</span><span class="n">search_fields</span>
-            <span class="p">)</span>
-            <span class="k">if</span> <span class="n">matches</span><span class="p">:</span>
-                <span class="n">match</span> <span class="o">=</span> <span class="n">matches</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
-                <span class="k">break</span>
+        <span class="n">match</span><span class="p">,</span> <span class="n">suggestions</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">do_search</span><span class="p">(</span><span class="n">query</span><span class="p">,</span> <span class="n">entries</span><span class="p">)</span>
 
         <span class="k">if</span> <span class="ow">not</span> <span class="n">match</span><span class="p">:</span>
             <span class="c1"># no topic matches found. Only give suggestions.</span>
@@ -480,24 +576,15 @@
 
         <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">match</span><span class="p">,</span> <span class="n">HelpCategory</span><span class="p">):</span>
             <span class="c1"># no subtopics for categories - these are just lists of topics</span>
-
-            <span class="n">output</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">format_help_index</span><span class="p">(</span>
-                <span class="p">{</span>
-                    <span class="n">match</span><span class="o">.</span><span class="n">key</span><span class="p">:</span> <span class="p">[</span>
-                        <span class="n">cmd</span><span class="o">.</span><span class="n">key</span>
-                        <span class="k">for</span> <span class="n">cmd</span> <span class="ow">in</span> <span class="n">all_cmds</span>
-                        <span class="k">if</span> <span class="n">match</span><span class="o">.</span><span class="n">key</span><span class="o">.</span><span class="n">lower</span><span class="p">()</span> <span class="o">==</span> <span class="n">cmd</span><span class="o">.</span><span class="n">help_category</span>
-                    <span class="p">]</span>
-                <span class="p">},</span>
-                <span class="p">{</span>
-                    <span class="n">match</span><span class="o">.</span><span class="n">key</span><span class="p">:</span> <span class="p">[</span>
-                        <span class="n">topic</span><span class="o">.</span><span class="n">key</span>
-                        <span class="k">for</span> <span class="n">topic</span> <span class="ow">in</span> <span class="n">all_db_topics</span>
-                        <span class="k">if</span> <span class="n">match</span><span class="o">.</span><span class="n">key</span><span class="o">.</span><span class="n">lower</span><span class="p">()</span> <span class="o">==</span> <span class="n">topic</span><span class="o">.</span><span class="n">help_category</span>
-                    <span class="p">]</span>
-                <span class="p">},</span>
-                <span class="n">title_lone_category</span><span class="o">=</span><span class="kc">True</span>
-            <span class="p">)</span>
+            <span class="n">category</span> <span class="o">=</span> <span class="n">match</span><span class="o">.</span><span class="n">key</span>
+            <span class="n">category_lower</span> <span class="o">=</span> <span class="n">category</span><span class="o">.</span><span class="n">lower</span><span class="p">()</span>
+            <span class="n">cmds_in_category</span> <span class="o">=</span> <span class="p">[</span><span class="n">key</span> <span class="k">for</span> <span class="n">key</span><span class="p">,</span> <span class="n">cmd</span> <span class="ow">in</span> <span class="n">cmd_help_topics</span><span class="o">.</span><span class="n">items</span><span class="p">()</span>
+                                <span class="k">if</span> <span class="n">category_lower</span> <span class="o">==</span> <span class="n">cmd</span><span class="o">.</span><span class="n">help_category</span><span class="p">]</span>
+            <span class="n">topics_in_category</span> <span class="o">=</span> <span class="p">[</span><span class="n">key</span> <span class="k">for</span> <span class="n">key</span><span class="p">,</span> <span class="n">topic</span> <span class="ow">in</span> <span class="n">file_db_help_topics</span><span class="o">.</span><span class="n">items</span><span class="p">()</span>
+                                  <span class="k">if</span> <span class="n">category_lower</span> <span class="o">==</span> <span class="n">topic</span><span class="o">.</span><span class="n">help_category</span><span class="p">]</span>
+            <span class="n">output</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">format_help_index</span><span class="p">({</span><span class="n">category</span><span class="p">:</span> <span class="n">cmds_in_category</span><span class="p">},</span>
+                                            <span class="p">{</span><span class="n">category</span><span class="p">:</span> <span class="n">topics_in_category</span><span class="p">},</span>
+                                            <span class="n">title_lone_category</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
             <span class="bp">self</span><span class="o">.</span><span class="n">msg_help</span><span class="p">(</span><span class="n">output</span><span class="p">)</span>
             <span class="k">return</span>
 
@@ -597,7 +684,7 @@
     <span class="k">del</span> <span class="n">caller</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">_editing_help</span>
 
 
-<div class="viewcode-block" id="CmdSetHelp"><a class="viewcode-back" href="../../../../api/evennia.commands.default.help.html#evennia.commands.default.help.CmdSetHelp">[docs]</a><span class="k">class</span> <span class="nc">CmdSetHelp</span><span class="p">(</span><span class="n">COMMAND_DEFAULT_CLASS</span><span class="p">):</span>
+<div class="viewcode-block" id="CmdSetHelp"><a class="viewcode-back" href="../../../../api/evennia.commands.default.help.html#evennia.commands.default.help.CmdSetHelp">[docs]</a><span class="k">class</span> <span class="nc">CmdSetHelp</span><span class="p">(</span><span class="n">CmdHelp</span><span class="p">):</span>
     <span class="sd">&quot;&quot;&quot;</span>
 <span class="sd">    Edit the help database.</span>
 
@@ -661,9 +748,15 @@
 <span class="sd">    &quot;&quot;&quot;</span>
 
     <span class="n">key</span> <span class="o">=</span> <span class="s2">&quot;sethelp&quot;</span>
+    <span class="n">aliases</span> <span class="o">=</span> <span class="p">[]</span>
     <span class="n">switch_options</span> <span class="o">=</span> <span class="p">(</span><span class="s2">&quot;edit&quot;</span><span class="p">,</span> <span class="s2">&quot;replace&quot;</span><span class="p">,</span> <span class="s2">&quot;append&quot;</span><span class="p">,</span> <span class="s2">&quot;extend&quot;</span><span class="p">,</span> <span class="s2">&quot;delete&quot;</span><span class="p">)</span>
     <span class="n">locks</span> <span class="o">=</span> <span class="s2">&quot;cmd:perm(Helper)&quot;</span>
     <span class="n">help_category</span> <span class="o">=</span> <span class="s2">&quot;Building&quot;</span>
+    <span class="n">arg_regex</span> <span class="o">=</span> <span class="kc">None</span>
+
+<div class="viewcode-block" id="CmdSetHelp.parse"><a class="viewcode-back" href="../../../../api/evennia.commands.default.help.html#evennia.commands.default.help.CmdSetHelp.parse">[docs]</a>    <span class="k">def</span> <span class="nf">parse</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+        <span class="sd">&quot;&quot;&quot;We want to use the default parser rather than the CmdHelp.parse&quot;&quot;&quot;</span>
+        <span class="k">return</span> <span class="n">COMMAND_DEFAULT_CLASS</span><span class="o">.</span><span class="n">parse</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span></div>
 
 <div class="viewcode-block" id="CmdSetHelp.func"><a class="viewcode-back" href="../../../../api/evennia.commands.default.help.html#evennia.commands.default.help.CmdSetHelp.func">[docs]</a>    <span class="k">def</span> <span class="nf">func</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
         <span class="sd">&quot;&quot;&quot;Implement the function&quot;&quot;&quot;</span>
@@ -691,18 +784,63 @@
         <span class="n">old_entry</span> <span class="o">=</span> <span class="kc">None</span>
 
         <span class="c1"># check if we have an old entry with the same name</span>
-        <span class="k">try</span><span class="p">:</span>
-            <span class="k">for</span> <span class="n">querystr</span> <span class="ow">in</span> <span class="n">topicstrlist</span><span class="p">:</span>
-                <span class="n">old_entry</span> <span class="o">=</span> <span class="n">HelpEntry</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">find_topicmatch</span><span class="p">(</span><span class="n">querystr</span><span class="p">)</span>  <span class="c1"># also search by alias</span>
-                <span class="k">if</span> <span class="n">old_entry</span><span class="p">:</span>
-                    <span class="n">old_entry</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="n">old_entry</span><span class="p">)[</span><span class="mi">0</span><span class="p">]</span>
+
+        <span class="n">cmd_help_topics</span><span class="p">,</span> <span class="n">db_help_topics</span><span class="p">,</span> <span class="n">file_help_topics</span> <span class="o">=</span> \
+            <span class="bp">self</span><span class="o">.</span><span class="n">collect_topics</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">caller</span><span class="p">,</span> <span class="n">mode</span><span class="o">=</span><span class="s1">&#39;query&#39;</span><span class="p">)</span>
+        <span class="c1"># db-help topics takes priority over file-help</span>
+        <span class="n">file_db_help_topics</span> <span class="o">=</span> <span class="p">{</span><span class="o">**</span><span class="n">file_help_topics</span><span class="p">,</span> <span class="o">**</span><span class="n">db_help_topics</span><span class="p">}</span>
+        <span class="c1"># commands take priority over the other types</span>
+        <span class="n">all_topics</span> <span class="o">=</span> <span class="p">{</span><span class="o">**</span><span class="n">file_db_help_topics</span><span class="p">,</span> <span class="o">**</span><span class="n">cmd_help_topics</span><span class="p">}</span>
+        <span class="c1"># get all categories</span>
+        <span class="n">all_categories</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="nb">set</span><span class="p">(</span>
+            <span class="n">HelpCategory</span><span class="p">(</span><span class="n">topic</span><span class="o">.</span><span class="n">help_category</span><span class="p">)</span> <span class="k">for</span> <span class="n">topic</span> <span class="ow">in</span> <span class="n">all_topics</span><span class="o">.</span><span class="n">values</span><span class="p">()))</span>
+        <span class="c1"># all available help options - will be searched in order. We also check # the</span>
+        <span class="c1"># read-permission here.</span>
+        <span class="n">entries</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="n">all_topics</span><span class="o">.</span><span class="n">values</span><span class="p">())</span> <span class="o">+</span> <span class="n">all_categories</span>
+
+        <span class="c1"># default setup</span>
+        <span class="n">category</span> <span class="o">=</span> <span class="n">lhslist</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span> <span class="k">if</span> <span class="n">nlist</span> <span class="o">&gt;</span> <span class="mi">1</span> <span class="k">else</span> <span class="n">DEFAULT_HELP_CATEGORY</span>
+        <span class="n">lockstring</span> <span class="o">=</span> <span class="s2">&quot;,&quot;</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">lhslist</span><span class="p">[</span><span class="mi">2</span><span class="p">:])</span> <span class="k">if</span> <span class="n">nlist</span> <span class="o">&gt;</span> <span class="mi">2</span> <span class="k">else</span> <span class="s2">&quot;read:all()&quot;</span>
+
+        <span class="c1"># search for existing entries of this or other types</span>
+        <span class="n">old_entry</span> <span class="o">=</span> <span class="kc">None</span>
+        <span class="k">for</span> <span class="n">querystr</span> <span class="ow">in</span> <span class="n">topicstrlist</span><span class="p">:</span>
+            <span class="n">match</span><span class="p">,</span> <span class="n">_</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">do_search</span><span class="p">(</span><span class="n">querystr</span><span class="p">,</span> <span class="n">entries</span><span class="p">)</span>
+            <span class="k">if</span> <span class="n">match</span><span class="p">:</span>
+                <span class="n">warning</span> <span class="o">=</span> <span class="kc">None</span>
+                <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">match</span><span class="p">,</span> <span class="n">HelpCategory</span><span class="p">):</span>
+                    <span class="n">warning</span> <span class="o">=</span> <span class="p">(</span><span class="sa">f</span><span class="s2">&quot;&#39;</span><span class="si">{</span><span class="n">querystr</span><span class="si">}</span><span class="s2">&#39; matches (or partially matches) the name of &quot;</span>
+                               <span class="s2">&quot;help-category &#39;</span><span class="si">{match.key}</span><span class="s2">&#39;. If you continue, your help entry will &quot;</span>
+                               <span class="s2">&quot;take precedence and the category (or part of its name) *may* not &quot;</span>
+                               <span class="s2">&quot;be usable for grouping help entries anymore.&quot;</span><span class="p">)</span>
+                <span class="k">elif</span> <span class="n">inherits_from</span><span class="p">(</span><span class="n">match</span><span class="p">,</span> <span class="s2">&quot;evennia.commands.command.Command&quot;</span><span class="p">):</span>
+                    <span class="n">warning</span> <span class="o">=</span> <span class="p">(</span><span class="sa">f</span><span class="s2">&quot;&#39;</span><span class="si">{</span><span class="n">querystr</span><span class="si">}</span><span class="s2">&#39; matches (or partially matches) the key/alias of &quot;</span>
+                               <span class="s2">&quot;Command &#39;</span><span class="si">{match.key}</span><span class="s2">&#39;. Command-help take precedence over other &quot;</span>
+                               <span class="s2">&quot;help entries so your help *may* be impossible to reach for those &quot;</span>
+                               <span class="s2">&quot;with access to that command.&quot;</span><span class="p">)</span>
+                <span class="k">elif</span> <span class="n">inherits_from</span><span class="p">(</span><span class="n">match</span><span class="p">,</span> <span class="s2">&quot;evennia.help.filehelp.FileHelpEntry&quot;</span><span class="p">):</span>
+                    <span class="n">warning</span> <span class="o">=</span> <span class="p">(</span><span class="sa">f</span><span class="s2">&quot;&#39;</span><span class="si">{</span><span class="n">querystr</span><span class="si">}</span><span class="s2">&#39; matches (or partially matches) the name/alias of the &quot;</span>
+                               <span class="s2">&quot;file-based help file &#39;</span><span class="si">{match.key}</span><span class="s2">&#39;. File-help entries cannot be &quot;</span>
+                               <span class="s2">&quot;modified from in-game (they are files on-disk). If you continue, &quot;</span>
+                               <span class="s2">&quot;your help entry *may* shadow the file-based one&#39;s name partly or &quot;</span>
+                               <span class="s2">&quot;completely.&quot;</span><span class="p">)</span>
+                <span class="k">if</span> <span class="n">warning</span><span class="p">:</span>
+                    <span class="c1"># show a warning for a clashing help-entry type. Even if user accepts this</span>
+                    <span class="c1"># we don&#39;t break here since we may need to show warnings for other inputs.</span>
+                    <span class="c1"># We don&#39;t count this as an old-entry hit because we can&#39;t edit these</span>
+                    <span class="c1"># types of entries.</span>
+                    <span class="bp">self</span><span class="o">.</span><span class="n">msg</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;|rWarning:</span><span class="se">\n</span><span class="s2">|r</span><span class="si">{</span><span class="n">warning</span><span class="si">}</span><span class="s2">|n&quot;</span><span class="p">)</span>
+                    <span class="n">repl</span> <span class="o">=</span> <span class="k">yield</span><span class="p">(</span><span class="s2">&quot;|wDo you still want to continue? Y/[N]?|n&quot;</span><span class="p">)</span>
+                    <span class="k">if</span> <span class="n">repl</span><span class="o">.</span><span class="n">lower</span><span class="p">()</span> <span class="ow">not</span> <span class="ow">in</span> <span class="p">(</span><span class="s1">&#39;y&#39;</span><span class="p">,</span> <span class="s1">&#39;yes&#39;</span><span class="p">):</span>
+                        <span class="bp">self</span><span class="o">.</span><span class="n">msg</span><span class="p">(</span><span class="s2">&quot;Aborted.&quot;</span><span class="p">)</span>
+                        <span class="k">return</span>
+                <span class="k">else</span><span class="p">:</span>
+                    <span class="c1"># a db-based help entry - this is OK</span>
+                    <span class="n">old_entry</span> <span class="o">=</span> <span class="n">match</span>
+                    <span class="n">category</span> <span class="o">=</span> <span class="n">lhslist</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span> <span class="k">if</span> <span class="n">nlist</span> <span class="o">&gt;</span> <span class="mi">1</span> <span class="k">else</span> <span class="n">old_entry</span><span class="o">.</span><span class="n">help_category</span>
+                    <span class="n">lockstring</span> <span class="o">=</span> <span class="s2">&quot;,&quot;</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">lhslist</span><span class="p">[</span><span class="mi">2</span><span class="p">:])</span> <span class="k">if</span> <span class="n">nlist</span> <span class="o">&gt;</span> <span class="mi">2</span> <span class="k">else</span> <span class="n">old_entry</span><span class="o">.</span><span class="n">locks</span><span class="o">.</span><span class="n">get</span><span class="p">()</span>
                     <span class="k">break</span>
-            <span class="n">category</span> <span class="o">=</span> <span class="n">lhslist</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span> <span class="k">if</span> <span class="n">nlist</span> <span class="o">&gt;</span> <span class="mi">1</span> <span class="k">else</span> <span class="n">old_entry</span><span class="o">.</span><span class="n">help_category</span>
-            <span class="n">lockstring</span> <span class="o">=</span> <span class="s2">&quot;,&quot;</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">lhslist</span><span class="p">[</span><span class="mi">2</span><span class="p">:])</span> <span class="k">if</span> <span class="n">nlist</span> <span class="o">&gt;</span> <span class="mi">2</span> <span class="k">else</span> <span class="n">old_entry</span><span class="o">.</span><span class="n">locks</span><span class="o">.</span><span class="n">get</span><span class="p">()</span>
-        <span class="k">except</span> <span class="ne">Exception</span><span class="p">:</span>
-            <span class="n">old_entry</span> <span class="o">=</span> <span class="kc">None</span>
-            <span class="n">category</span> <span class="o">=</span> <span class="n">lhslist</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span> <span class="k">if</span> <span class="n">nlist</span> <span class="o">&gt;</span> <span class="mi">1</span> <span class="k">else</span> <span class="n">DEFAULT_HELP_CATEGORY</span>
-            <span class="n">lockstring</span> <span class="o">=</span> <span class="s2">&quot;,&quot;</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">lhslist</span><span class="p">[</span><span class="mi">2</span><span class="p">:])</span> <span class="k">if</span> <span class="n">nlist</span> <span class="o">&gt;</span> <span class="mi">2</span> <span class="k">else</span> <span class="s2">&quot;view:all()&quot;</span>
+
         <span class="n">category</span> <span class="o">=</span> <span class="n">category</span><span class="o">.</span><span class="n">lower</span><span class="p">()</span>
 
         <span class="k">if</span> <span class="s2">&quot;edit&quot;</span> <span class="ow">in</span> <span class="n">switches</span><span class="p">:</span>
@@ -771,8 +909,8 @@
                 <span class="bp">self</span><span class="o">.</span><span class="n">msg</span><span class="p">(</span><span class="s2">&quot;Overwrote the old topic &#39;</span><span class="si">%s</span><span class="s2">&#39;</span><span class="si">%s</span><span class="s2">.&quot;</span> <span class="o">%</span> <span class="p">(</span><span class="n">topicstr</span><span class="p">,</span> <span class="n">aliastxt</span><span class="p">))</span>
             <span class="k">else</span><span class="p">:</span>
                 <span class="bp">self</span><span class="o">.</span><span class="n">msg</span><span class="p">(</span>
-                    <span class="s2">&quot;Topic &#39;</span><span class="si">%s</span><span class="s2">&#39;</span><span class="si">%s</span><span class="s2"> already exists. Use /replace to overwrite &quot;</span>
-                    <span class="s2">&quot;or /append or /merge to add text to it.&quot;</span> <span class="o">%</span> <span class="p">(</span><span class="n">topicstr</span><span class="p">,</span> <span class="n">aliastxt</span><span class="p">)</span>
+                    <span class="sa">f</span><span class="s2">&quot;Topic &#39;</span><span class="si">{</span><span class="n">topicstr</span><span class="si">}</span><span class="s2">&#39;</span><span class="si">{</span><span class="n">aliastxt</span><span class="si">}</span><span class="s2"> already exists. Use /edit to open in editor, or &quot;</span>
+                    <span class="s2">&quot;/replace, /append and /merge to modify it directly.&quot;</span>
                 <span class="p">)</span>
         <span class="k">else</span><span class="p">:</span>
             <span class="c1"># no old entry. Create a new one.</span>
@@ -780,7 +918,7 @@
                 <span class="n">topicstr</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">rhs</span><span class="p">,</span> <span class="n">category</span><span class="o">=</span><span class="n">category</span><span class="p">,</span> <span class="n">locks</span><span class="o">=</span><span class="n">lockstring</span><span class="p">,</span> <span class="n">aliases</span><span class="o">=</span><span class="n">aliases</span>
             <span class="p">)</span>
             <span class="k">if</span> <span class="n">new_entry</span><span class="p">:</span>
-                <span class="bp">self</span><span class="o">.</span><span class="n">msg</span><span class="p">(</span><span class="s2">&quot;Topic &#39;</span><span class="si">%s</span><span class="s2">&#39;</span><span class="si">%s</span><span class="s2"> was successfully created.&quot;</span> <span class="o">%</span> <span class="p">(</span><span class="n">topicstr</span><span class="p">,</span> <span class="n">aliastxt</span><span class="p">))</span>
+                <span class="bp">self</span><span class="o">.</span><span class="n">msg</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Topic &#39;</span><span class="si">{</span><span class="n">topicstr</span><span class="si">}</span><span class="s2">&#39;</span><span class="si">{</span><span class="n">aliastxt</span><span class="si">}</span><span class="s2"> was successfully created.&quot;</span><span class="p">)</span>
                 <span class="k">if</span> <span class="s2">&quot;edit&quot;</span> <span class="ow">in</span> <span class="n">switches</span><span class="p">:</span>
                     <span class="c1"># open the line editor to edit the helptext</span>
                     <span class="bp">self</span><span class="o">.</span><span class="n">caller</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">_editing_help</span> <span class="o">=</span> <span class="n">new_entry</span>
@@ -795,7 +933,7 @@
                     <span class="k">return</span>
             <span class="k">else</span><span class="p">:</span>
                 <span class="bp">self</span><span class="o">.</span><span class="n">msg</span><span class="p">(</span>
-                    <span class="s2">&quot;Error when creating topic &#39;</span><span class="si">%s</span><span class="s2">&#39;</span><span class="si">%s</span><span class="s2">! Contact an admin.&quot;</span> <span class="o">%</span> <span class="p">(</span><span class="n">topicstr</span><span class="p">,</span> <span class="n">aliastxt</span><span class="p">)</span>
+                    <span class="sa">f</span><span class="s2">&quot;Error when creating topic &#39;</span><span class="si">{</span><span class="n">topicstr</span><span class="si">}</span><span class="s2">&#39;</span><span class="si">{</span><span class="n">aliastxt</span><span class="si">}</span><span class="s2">! Contact an admin.&quot;</span>
                 <span class="p">)</span></div></div>
 </pre></div>
 

docs/1.0-dev/_modules/evennia/commands/default/syscommands.html

@@ -112,7 +112,7 @@
 
 
 <span class="c1">#</span>
-<span class="c1"># Command called when there were mulitple matches to the command.</span>
+<span class="c1"># Command called when there were multiple matches to the command.</span>
 <span class="c1">#</span>
 <div class="viewcode-block" id="SystemMultimatch"><a class="viewcode-back" href="../../../../api/evennia.commands.default.syscommands.html#evennia.commands.default.syscommands.SystemMultimatch">[docs]</a><span class="k">class</span> <span class="nc">SystemMultimatch</span><span class="p">(</span><span class="n">COMMAND_DEFAULT_CLASS</span><span class="p">):</span>
     <span class="sd">&quot;&quot;&quot;</span>

docs/1.0-dev/_modules/evennia/commands/default/tests.html

@@ -473,6 +473,7 @@
             <span class="n">help_module</span><span class="o">.</span><span class="n">CmdSetHelp</span><span class="p">(),</span>
             <span class="s2">&quot;testhelp, General = This is a test&quot;</span><span class="p">,</span>
             <span class="s2">&quot;Topic &#39;testhelp&#39; was successfully created.&quot;</span><span class="p">,</span>
+            <span class="n">cmdset</span><span class="o">=</span><span class="n">CharacterCmdSet</span><span class="p">()</span>
         <span class="p">)</span>
         <span class="bp">self</span><span class="o">.</span><span class="n">call</span><span class="p">(</span><span class="n">help_module</span><span class="o">.</span><span class="n">CmdHelp</span><span class="p">(),</span> <span class="s2">&quot;testhelp&quot;</span><span class="p">,</span> <span class="s2">&quot;Help for testhelp&quot;</span><span class="p">,</span> <span class="n">cmdset</span><span class="o">=</span><span class="n">CharacterCmdSet</span><span class="p">())</span></div>
 

docs/1.0-dev/_modules/evennia/contrib/building_menu.html

@@ -619,7 +619,7 @@
     <span class="n">keys_go_back</span> <span class="o">=</span> <span class="p">[</span><span class="s2">&quot;@&quot;</span><span class="p">]</span>  <span class="c1"># The keys allowing to go back in the menu tree</span>
     <span class="n">sep_keys</span> <span class="o">=</span> <span class="s2">&quot;.&quot;</span>  <span class="c1"># The key separator for menus with more than 2 levels</span>
     <span class="n">joker_key</span> <span class="o">=</span> <span class="s2">&quot;*&quot;</span>  <span class="c1"># The special key meaning &quot;anything&quot; in a choice key</span>
-    <span class="n">min_shortcut</span> <span class="o">=</span> <span class="mi">1</span>  <span class="c1"># The minimum length of shorcuts when `key` is not set</span>
+    <span class="n">min_shortcut</span> <span class="o">=</span> <span class="mi">1</span>  <span class="c1"># The minimum length of shortcuts when `key` is not set</span>
 
 <div class="viewcode-block" id="BuildingMenu.__init__"><a class="viewcode-back" href="../../../api/evennia.contrib.building_menu.html#evennia.contrib.building_menu.BuildingMenu.__init__">[docs]</a>    <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span>
         <span class="bp">self</span><span class="p">,</span>

docs/1.0-dev/_modules/evennia/help/filehelp.html

@@ -55,12 +55,13 @@
 <span class="sd">::</span>
 
 <span class="sd">    {&#39;key&#39;: &lt;str&gt;,</span>
+<span class="sd">     &#39;text&#39;: &lt;str&gt;,</span>
 <span class="sd">     &#39;category&#39;: &lt;str&gt;,   # optional, otherwise settings.DEFAULT_HELP_CATEGORY</span>
 <span class="sd">     &#39;aliases&#39;: &lt;list&gt;,   # optional</span>
-<span class="sd">     &#39;text&#39;: &lt;str&gt;}</span>
+<span class="sd">     &#39;locks&#39;: &lt;str&gt;}      # optional, use access-type &#39;view&#39;. Default is view:all()</span>
 
-<span class="sd">where the `category` is optional and the `text`` should be formatted on the</span>
-<span class="sd">same form as other help entry-texts and contain ``# subtopics`` as normal.</span>
+<span class="sd">The `text`` should be formatted on the same form as other help entry-texts and</span>
+<span class="sd">can contain ``# subtopics`` as normal.</span>
 
 <span class="sd">New help-entry modules are added to the system by providing the python-path to</span>
 <span class="sd">the module to `settings.FILE_HELP_ENTRY_MODULES`. Note that if same-key entries are</span>
@@ -75,6 +76,7 @@
 <span class="sd">        &quot;key&quot;: &quot;The Gods&quot;,   # case-insensitive, also partial-matching (&#39;gods&#39;) works</span>
 <span class="sd">        &quot;aliases&quot;: [&#39;pantheon&#39;, &#39;religion&#39;],</span>
 <span class="sd">        &quot;category&quot;: &quot;Lore&quot;,</span>
+<span class="sd">        &quot;locks&quot;: &quot;view:all()&quot;,   # this is optional unless restricting access</span>
 <span class="sd">        &quot;text&quot;: &#39;&#39;&#39;</span>
 <span class="sd">            The gods formed the world ...</span>
 
@@ -110,6 +112,8 @@
 <span class="kn">from</span> <span class="nn">evennia.utils.utils</span> <span class="kn">import</span> <span class="p">(</span>
     <span class="n">variable_from_module</span><span class="p">,</span> <span class="n">make_iter</span><span class="p">,</span> <span class="n">all_from_module</span><span class="p">)</span>
 <span class="kn">from</span> <span class="nn">evennia.utils</span> <span class="kn">import</span> <span class="n">logger</span>
+<span class="kn">from</span> <span class="nn">evennia.utils.utils</span> <span class="kn">import</span> <span class="n">lazy_property</span>
+<span class="kn">from</span> <span class="nn">evennia.locks.lockhandler</span> <span class="kn">import</span> <span class="n">LockHandler</span>
 
 <span class="n">_DEFAULT_HELP_CATEGORY</span> <span class="o">=</span> <span class="n">settings</span><span class="o">.</span><span class="n">DEFAULT_HELP_CATEGORY</span>
 
@@ -126,6 +130,7 @@
     <span class="n">aliases</span><span class="p">:</span> <span class="nb">list</span>
     <span class="n">help_category</span><span class="p">:</span> <span class="nb">str</span>
     <span class="n">entrytext</span><span class="p">:</span> <span class="nb">str</span>
+    <span class="n">lock_storage</span><span class="p">:</span> <span class="nb">str</span>
 
     <span class="nd">@property</span>
     <span class="k">def</span> <span class="nf">search_index_entry</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
@@ -138,6 +143,7 @@
             <span class="s2">&quot;aliases&quot;</span><span class="p">:</span> <span class="s2">&quot; &quot;</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">aliases</span><span class="p">),</span>
             <span class="s2">&quot;category&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">help_category</span><span class="p">,</span>
             <span class="s2">&quot;tags&quot;</span><span class="p">:</span> <span class="s2">&quot;&quot;</span><span class="p">,</span>
+            <span class="s2">&quot;locks&quot;</span><span class="p">:</span> <span class="s2">&quot;&quot;</span><span class="p">,</span>
             <span class="s2">&quot;text&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">entrytext</span><span class="p">,</span>
         <span class="p">}</span>
 
@@ -145,7 +151,23 @@
         <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">key</span>
 
     <span class="k">def</span> <span class="fm">__repr__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-        <span class="k">return</span> <span class="sa">f</span><span class="s2">&quot;&lt;FileHelpEntry </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">key</span><span class="si">}</span><span class="s2">&gt;&quot;</span></div>
+        <span class="k">return</span> <span class="sa">f</span><span class="s2">&quot;&lt;FileHelpEntry </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">key</span><span class="si">}</span><span class="s2">&gt;&quot;</span>
+
+<div class="viewcode-block" id="FileHelpEntry.locks"><a class="viewcode-back" href="../../../api/evennia.help.filehelp.html#evennia.help.filehelp.FileHelpEntry.locks">[docs]</a>    <span class="nd">@lazy_property</span>
+    <span class="k">def</span> <span class="nf">locks</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+        <span class="k">return</span> <span class="n">LockHandler</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span></div>
+
+<div class="viewcode-block" id="FileHelpEntry.access"><a class="viewcode-back" href="../../../api/evennia.help.filehelp.html#evennia.help.filehelp.FileHelpEntry.access">[docs]</a>    <span class="k">def</span> <span class="nf">access</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">accessing_obj</span><span class="p">,</span> <span class="n">access_type</span><span class="o">=</span><span class="s2">&quot;view&quot;</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="kc">True</span><span class="p">):</span>
+        <span class="sd">&quot;&quot;&quot;</span>
+<span class="sd">        Determines if another object has permission to access this help entry.</span>
+
+<span class="sd">        Args:</span>
+<span class="sd">            accessing_obj (Object or Account): Entity trying to access this one.</span>
+<span class="sd">            access_type (str): type of access sought.</span>
+<span class="sd">            default (bool): What to return if no lock of `access_type` was found.</span>
+
+<span class="sd">        &quot;&quot;&quot;</span>
+        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">locks</span><span class="o">.</span><span class="n">check</span><span class="p">(</span><span class="n">accessing_obj</span><span class="p">,</span> <span class="n">access_type</span><span class="o">=</span><span class="n">access_type</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="n">default</span><span class="p">)</span></div></div>
 
 
 <div class="viewcode-block" id="FileHelpStorageHandler"><a class="viewcode-back" href="../../../api/evennia.help.filehelp.html#evennia.help.filehelp.FileHelpStorageHandler">[docs]</a><span class="k">class</span> <span class="nc">FileHelpStorageHandler</span><span class="p">:</span>
@@ -196,14 +218,15 @@
             <span class="n">key</span> <span class="o">=</span> <span class="n">dct</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;key&#39;</span><span class="p">)</span><span class="o">.</span><span class="n">lower</span><span class="p">()</span><span class="o">.</span><span class="n">strip</span><span class="p">()</span>
             <span class="n">category</span> <span class="o">=</span> <span class="n">dct</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;category&#39;</span><span class="p">,</span> <span class="n">_DEFAULT_HELP_CATEGORY</span><span class="p">)</span><span class="o">.</span><span class="n">strip</span><span class="p">()</span>
             <span class="n">aliases</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="n">dct</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;aliases&#39;</span><span class="p">,</span> <span class="p">[]))</span>
-            <span class="n">entrytext</span> <span class="o">=</span> <span class="n">dct</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;text&#39;</span><span class="p">)</span>
+            <span class="n">entrytext</span> <span class="o">=</span> <span class="n">dct</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;text&#39;</span><span class="p">,</span> <span class="s1">&#39;&#39;</span><span class="p">)</span>
+            <span class="n">locks</span> <span class="o">=</span> <span class="n">dct</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;locks&#39;</span><span class="p">,</span> <span class="s1">&#39;&#39;</span><span class="p">)</span>
 
             <span class="k">if</span> <span class="ow">not</span> <span class="n">key</span> <span class="ow">and</span> <span class="n">entrytext</span><span class="p">:</span>
                 <span class="n">logger</span><span class="o">.</span><span class="n">error</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Cannot load file-help-entry (missing key or text): </span><span class="si">{</span><span class="n">dct</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
                 <span class="k">continue</span>
 
             <span class="n">unique_help_entries</span><span class="p">[</span><span class="n">key</span><span class="p">]</span> <span class="o">=</span> <span class="n">FileHelpEntry</span><span class="p">(</span>
-                <span class="n">key</span><span class="o">=</span><span class="n">key</span><span class="p">,</span> <span class="n">help_category</span><span class="o">=</span><span class="n">category</span><span class="p">,</span> <span class="n">aliases</span><span class="o">=</span><span class="n">aliases</span><span class="p">,</span>
+                <span class="n">key</span><span class="o">=</span><span class="n">key</span><span class="p">,</span> <span class="n">help_category</span><span class="o">=</span><span class="n">category</span><span class="p">,</span> <span class="n">aliases</span><span class="o">=</span><span class="n">aliases</span><span class="p">,</span> <span class="n">lock_storage</span><span class="o">=</span><span class="n">locks</span><span class="p">,</span>
                 <span class="n">entrytext</span><span class="o">=</span><span class="n">entrytext</span><span class="p">)</span>
 
         <span class="bp">self</span><span class="o">.</span><span class="n">help_entries_dict</span> <span class="o">=</span> <span class="n">unique_help_entries</span>

docs/1.0-dev/_modules/evennia/help/models.html

@@ -51,7 +51,6 @@
 <span class="sd">game world, policy info, rules and similar.</span>
 
 <span class="sd">&quot;&quot;&quot;</span>
-<span class="kn">from</span> <span class="nn">datetime</span> <span class="kn">import</span> <span class="n">datetime</span>
 <span class="kn">from</span> <span class="nn">django.contrib.contenttypes.models</span> <span class="kn">import</span> <span class="n">ContentType</span>
 <span class="kn">from</span> <span class="nn">django.db</span> <span class="kn">import</span> <span class="n">models</span>
 <span class="kn">from</span> <span class="nn">django.urls</span> <span class="kn">import</span> <span class="n">reverse</span>
@@ -156,12 +155,19 @@
     <span class="k">def</span> <span class="fm">__repr__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
         <span class="k">return</span> <span class="sa">f</span><span class="s2">&quot;&lt;HelpEntry </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">key</span><span class="si">}</span><span class="s2">&gt;&quot;</span>
 
-<div class="viewcode-block" id="HelpEntry.access"><a class="viewcode-back" href="../../../api/evennia.help.models.html#evennia.help.models.HelpEntry.access">[docs]</a>    <span class="k">def</span> <span class="nf">access</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">accessing_obj</span><span class="p">,</span> <span class="n">access_type</span><span class="o">=</span><span class="s2">&quot;read&quot;</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="kc">False</span><span class="p">):</span>
+<div class="viewcode-block" id="HelpEntry.access"><a class="viewcode-back" href="../../../api/evennia.help.models.html#evennia.help.models.HelpEntry.access">[docs]</a>    <span class="k">def</span> <span class="nf">access</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">accessing_obj</span><span class="p">,</span> <span class="n">access_type</span><span class="o">=</span><span class="s2">&quot;read&quot;</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="kc">True</span><span class="p">):</span>
         <span class="sd">&quot;&quot;&quot;</span>
-<span class="sd">        Determines if another object has permission to access.</span>
-<span class="sd">        accessing_obj - object trying to access this one</span>
-<span class="sd">        access_type - type of access sought</span>
-<span class="sd">        default - what to return if no lock of access_type was found</span>
+<span class="sd">        Determines if another object has permission to access this help entry.</span>
+
+<span class="sd">        Accesses used by default:</span>
+<span class="sd">            &#39;read&#39; - read the help entry itself.</span>
+<span class="sd">            &#39;view&#39; - see help entry in help index.</span>
+
+<span class="sd">        Args:</span>
+<span class="sd">            accessing_obj (Object or Account): Entity trying to access this one.</span>
+<span class="sd">            access_type (str): type of access sought.</span>
+<span class="sd">            default (bool): What to return if no lock of `access_type` was found.</span>
+
 <span class="sd">        &quot;&quot;&quot;</span>
         <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">locks</span><span class="o">.</span><span class="n">check</span><span class="p">(</span><span class="n">accessing_obj</span><span class="p">,</span> <span class="n">access_type</span><span class="o">=</span><span class="n">access_type</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="n">default</span><span class="p">)</span></div>
 

docs/1.0-dev/_modules/evennia/help/utils.html

@@ -51,9 +51,9 @@
 
 <span class="c1"># these are words that Lunr normally ignores but which we want to find</span>
 <span class="c1"># since we use them (e.g. as command names).</span>
-<span class="c1"># Lunr&#39;s default word list is found here:</span>
+<span class="c1"># Lunr&#39;s default ignore-word list is found here:</span>
 <span class="c1"># https://github.com/yeraydiazdiaz/lunr.py/blob/master/lunr/stop_word_filter.py</span>
-<span class="n">_LUNR_STOP_WORD_FILTER_EXCEPTIONS</span> <span class="o">=</span> <span class="p">(</span><span class="s2">&quot;about&quot;</span><span class="p">,</span> <span class="s2">&quot;might&quot;</span><span class="p">)</span>
+<span class="n">_LUNR_STOP_WORD_FILTER_EXCEPTIONS</span> <span class="o">=</span> <span class="p">(</span><span class="s2">&quot;about&quot;</span><span class="p">,</span> <span class="s2">&quot;might&quot;</span><span class="p">,</span> <span class="s2">&quot;get&quot;</span><span class="p">)</span>
 
 <span class="n">_LUNR</span> <span class="o">=</span> <span class="kc">None</span>
 <span class="n">_LUNR_EXCEPTION</span> <span class="o">=</span> <span class="kc">None</span>

docs/1.0-dev/_modules/evennia/prototypes/prototypes.html

@@ -733,7 +733,7 @@
                       <span class="n">err</span><span class="o">=</span><span class="n">err</span><span class="p">,</span> <span class="n">protkey</span><span class="o">=</span><span class="n">protkey</span><span class="p">,</span> <span class="n">typeclass</span><span class="o">=</span><span class="n">typeclass</span><span class="p">)</span>
             <span class="p">)</span>
 
-    <span class="c1"># recursively traverese prototype_parent chain</span>
+    <span class="c1"># recursively traverse prototype_parent chain</span>
 
     <span class="k">for</span> <span class="n">protstring</span> <span class="ow">in</span> <span class="n">make_iter</span><span class="p">(</span><span class="n">prototype_parent</span><span class="p">):</span>
         <span class="n">protstring</span> <span class="o">=</span> <span class="n">protstring</span><span class="o">.</span><span class="n">lower</span><span class="p">()</span>