---------------
When a player types help, the following list of objects is consulted for .help properties: the player itself, all ancestors of player up to and including $player, and, if the current location is a room, the current location together with all ancestors of the current location back to and including $room. Each help property should have as value either an object or a list of objects (otherwise we just ignore it). These objects are then strung together as a list of `help databases' to be searched in order for the requested topic.
A help database (in the sense of anything that is usable by $player:help()) is any object having the following three verbs:
:find_topics([string])
where string is a supposed help topic, returns a list of strings,
i.e., actual help topics that this db knows about, or some boolean
false value in the event that this db is clueless...
If no arguments are given, this should return a list of all topics
in the db
:get_topic(string)
given one of the strings returned by :find_topics this either
returns a list of strings (text to be spewed to the player) or
returns 1 to indicate that it has already taken care of printing
information to the player.
:dump_topic(string)
like get_topic, but instead returns the raw text of a help topic
as a (download/upload) script
In short if :find_topic reports that a particular db knows about a given topic
it returns the full topic name, so that :get_topic may be called on it later.
:dump_topic is used by maintainers (see $wiz:@gethelp) to edit help topics.
$generic_help and $help
-----------------------
The Generic Help Database, $generic_help, is the parent class of a particular kind of help database of which $help is an instance. On help databases of this type, every help topic has a corresponding property, interpreted as follows:
this.(topic) = string
one-line help text.
this.(topic) = {"*
call this:
help objects that would have been consulted had the topic not been found
on this object.
this.(topic) = other list of strings
multi-line help text
For the {"*
{"*forward*", topic, @rest}
- get help text for topic and then append the lines of `rest'.
rest may, in turn, begin with a "*
{"*pass*", topic, @rest}
- get help text for topic from the first help database after this one
that actually has help text for topic, and then append lines of `rest'.
As with "*forward*" rest may, in turn, begin with a "*
{"*subst*", @lines}
- All occurences of %[exp] in lines are replaced with the value of exp
which is assumed to evaluate to a string.
All lines beginning with %;exp are replaced with the value of exp
which is assumed to evaluate to a list of strings.
Evaluation is done using $no_one's permissions so exp in either case
can only refer to public information.
{"*index*", title}
- returns a list of all topics in this database, arranged in columns.
title is used as a heading for this index.
In order for your help database to appear in the list presented
by 'help index', your db object must be set to +r.
{"*objectdoc*", object}
- gets the documentation for the given object (i.e., object:help_msg())
N.B. as with all other *verb* arguments, object must be a string.
{"*verbdoc*", object, verbname}
- gets the documentation for the named verb on the given object
(i.e., any strings at the beginning of said verbcode)
Individual help dbs are free to define additional verbs that may be used in this context. $help itself defines the following additional such verbs:
{"*index_list*"}
- returns a list of all index topics in all databases in the search list.
An index topic is one whose actual text is {"*index*", something}.
When creating a help db, you should be sure to make an index topic.
{"*full_index*"}
- prints indices for all help databases in the search list.
It should be noted (once again) that help databases need not be children of $generic_help, so long as they have :find_topics/:get_topic/:dump_topic working as specified above.