Updated rst-docs to match online wiki

docs/sphinx/source/wiki/HelpSystem.rst

@@ -8,7 +8,7 @@ players and staff alike to learn how to use the game's commands as well
 as other information pertinent to the game. The help system has many
 different aspects, from the normal editing of help entries from inside
 the game, to auto-generated help entries during code development using
-the *auto-help* system.
+the *auto-help system*.
 
 Viewing the help database
 -------------------------
@@ -31,18 +31,19 @@ Command Auto-help system
 
 One important use of the help system is to teach the use of in-game
 commands. Evennia offers a dynamically updated help system for all your
-commands, new and old, known simply as the *auto-help* system. Only
-commands that you can actually use are picked up by the auto-help
-system. That means an admin will see a considerably larger mass of help
-topics when using the ``help`` command than a normal player.
+commands, new and old, known simply as the *auto-help system*. Only
+commands that you and your character can actually currently use are
+picked up by the auto-help system. That means an admin will see a
+considerably larger amount of help topics than a normal player when
+using the ``help`` command.
 
 The auto-help system uses the ``__doc__`` strings of your command
 definitions and formats this to a nice-looking help entry. This makes
 for a very easy way to keep the help updated - just document your
-commands well - updating the help system is just a ``@reload`` away.
-There is no need to manually create help database entries for commands;
-as long as you keep the docstrings updated your help will be dynamically
-updated for you as well.
+commands well abd updating the help file is just a ``@reload`` away.
+There is no need to manually create and maintain help database entries
+for commands; as long as you keep the docstrings updated your help will
+be dynamically updated for you as well.
 
 Example (from a module with command definitions):
 
@@ -59,37 +60,38 @@ Example (from a module with command definitions):
        help_category = "Building"
         ...
 
-So the text at the very top of the command class definition is the
-class' ``__doc__``-string and what will be shown to users looking for
-help. Try to use a consistent formatting between your help strings (for
-example, all default commands have ``__doc__``-strings formatted in the
-way seen above). You should also supply the ``help_category`` class
-property if you can; this helps to group help entries together for
-easier finding (if you don't supply a help\_category, "General" will be
-assumed).
+The text at the very top of the command class definition is the class'
+``__doc__``-string and will be shown to users looking for help. Try to
+use a consistent format - all default commands are using the structure
+shown above. You should also supply the ``help_category`` class property
+if you can; this helps to group help entries together for easier finding
+(if you don't supply a help\_category, "General" will be assumed).
 
 Other help entries (entries stored in database)
 -----------------------------------------------
 
-The *Other help* section you see when using the ``help`` command shows
-all help entries that has been manually added to the database by staff.
-Instead of being generated from the code by Evennia, these are stored in
-the database using a model called *!HelpEntry*. HelpEntry topics are
-intended for world-game-info, tutorials and other types of useful
-information not directly tied to a command and covered by auto-help.
+Not all help entries concern commands. You will also probably need help
+entries describing how your particular game is played - its rules, world
+descriptions and other types of information not covered by the auto-help
+system. Such entries are manually added to the database by staff and
+will appear under a heading "Other help" whenever you have any. Instead
+of being generated from the code by Evennia, these entries are stored in
+the database as a ``HelpEntry``.
 
 A help entry consists of four parts:
 
 -  The *topic*. This is the name of the help entry. This is what players
    search for when they are looking for help. The topic can contain
-   spaces.
+   spaces and also partual matches will be found.
 -  The *help category*. Examples are *Administration*, *Building*,
    *Comms* or *General*. This is an overall grouping of similar help
    topics, used by the engine to give a better overview.
--  The *text* - the help text itself, of any length. This can also
-   include *markup*, see below.
--  locks - a `lock definition <Locks.html>`_. Help commands check for
-   access\_types ``examine`` and ``edit``.
+-  The *text* - the help text itself, of any length.
+-  locks - a `lock definition <Locks.html>`_. This can be used to limit
+   access to this help entry, maybe because it's staff-only or otherwise
+   meant to be restricted. Help commands check for ``access_type``s
+   ``view`` and ``edit``. An example of a lock string would be
+   ``view:perm(Builders)``.
 
 You can create new help entries in code by using
 ``src.utils.create.create_help_entry()``:
@@ -116,11 +118,13 @@ You can change this using a different form of the ``@sethelp`` command:
 
     > @sethelp/add emote, Roleplaying = Emoting is important because ...
 
-If the category *Roleplaying* did not exist it is created and will
-appear in the help index. You can, finally, define a lock for the help
-entry by following the category with a `lock definition <Locks.html>`_:
+If the category *Roleplaying* did not already exist, it is created and
+will appear in the help index.
+
+You can, finally, define a lock for the help entry by following the
+category with a `lock definition <Locks.html>`_:
 
 ::
 
-    > @sethelp/add emote, Roleplaying, view:all() = The emote command ...
+    > @sethelp/add emote, Roleplaying, view:all() = Emoting is important because ...