LPC MANUAL - PROVIDING "HELP" FUNCTIONALITY
===========================================

    1. Introduction
    2. Setup
    3. Examples
    4. Implementation

1. INTRODUCTION
===============

This manual describes the global help framework. It can be used by guilds and
generally all objects that want to provide a help function. The help command
has the following form:

    help [category] <topic>

The [category] is optional and can be used by players to indicate that they
want help associated with a specific guild, e.g. "help myguild members" to
describe membership information, even if other guilds may also provide an
entry "members".

When a player does "help <category>" it provides an index of all help entries
known for that category (that is: all help files that are in the directory),
or shows a default topic, if one is set.

Providing help can be done by any room or object. The mudlib automatically
checks the room the player is in, as well as any object in its environment
or inventory for the availability of help topics.

2. SETUP
========

The help functionality is provided by: inherit "/lib/help"

For guilds and other situations where multiple help topics are needed, the help
files can be stored in a directory with files named: xxx.help

    set_help_dir(string dir)  - sets the path to the dir where the xxx.help
                                files are located.
    set_help_category(mixed)  - set a category or array of categories (unique
                                names) that we recognize.
    set_help_default(topic)   - optional - sets a default topic do display for
                                "help <category>" instead of showing the index.

In addition, and for simpler help needs, a single help topic can be set up with
a description. Multiple calls can be made to add multiple topics.

    add_help_topic(topic,text) - adds a topic and the text to display when a
                                 player asks to see the topic.
    add_help_topic(topic,file) - adds a topic and the filename of the help file
                                 to display to the player.

No further setup is needed. The help command processing is done automatically
from the mudlib. The /lib/help does provide some hook functions to make custom
descriptions and to check for elegibility to display a certain help topic.

3. Examples
===========

/d/Genesis/doc/examples/obj/backpack.c

    This backpack shows the use of the add_help_topic() routine in both forms.

/d/Genesis/doc/examples/guild/occ_fighter/emblem.c

    This guild emblem shows the use of a category + directory of help files.

4. Implementation
=================

The routine int process_help(string category, string topic) is called in the
room, as well as in any object in the player's environment or inventory (in
that order). If you have a need to redefine this routine, consider the two
basic rules for help processing:

- If a <category> is provided by the player, you may only handle the help 
  request if you recognize the help category. If another category is used,
  you may not handle the request and must return 0.
- If a category is not provided, you may handle the request if you recognize
  the topic. If you do not recognize the topic, you may NOT give a response
  and must return 0.

While it is possible to shadow the routine process_help(), it is strongly
discourged, unless you really know what you are doing.
