NAME

Genezzo::BasicHelp - Genezzo Help Facility

SYNOPSIS

use Genezzo::BasicHelp;

DESCRIPTION

BasicHelp builds searchable data structures out of Pod documents which are used for the Genezzo Help system. The help system is composed of a collection of topic groups or areas, with multiple topics in each group.

BasicHelp Pod documents must follow a specific format -- please see the following example:

perl -Iblib/lib
-e "use Genezzo::BasicHelp; print Genezzo::BasicHelp::getpod();"

The document must start with a "head1" command which designates the topic group or area, followed by a paragraph describing the area. The primary heading is followed by any number of "head2" commands which list the specific help topics. The format for the topic headings is:

  "head2" topic name [, topic alias] : short description
      [long description...]

Topics are alphabetically sorted by name, but the alias is a valid search pattern as well. Note that topic name matching is case-insensitive.

The "head3" command is reserved for future use -- examples are a "SEE ALSO" heading which hyperlinks to a related topic, or a "TAGS" field which groups related help topics.

ARGUMENTS

none

FUNCTIONS

getpod2text: Return the BasicHelp pod document as a formatted text string.
search_topic: Find the topics which match the search pattern in a particular group, and return the results as a formatted string.
The search_topic function takes the following optional named arguments:

topic_group: A case-insensitve prefix match for a particular group or area. Default is "Basic_Commands".
topic_pattern: A case-insensitive regex to match a specific set of topics in the group. Defaults to all topics if not specified.
option: Output formatting option: LIST (default), SHORT, or LONG.
LIST simply lists the matching topics in a series of columns (similar to "ls"). SHORT lists the matching topics and then outputs a brief description for each one. LONG lists the matching topics and then outputs a full description for each one. Note that if only a single topic matches then the listing is suppressed and a full description is always performed.

If no arguments are supplied, search_topic simply lists the available topics for the default topic group "Basic_Commands".

pod2gnzhelp: Take a raw pod help document (as a string) and parse it, updating the searchable BasicHelp data structure.

EXPORT

LIMITATIONS

TODO

convert hashes back to pod
hyperlink "SEE ALSO" headings
TAG search
hierarchical topic groups and searches

AUTHOR

Jeffrey I. Cohen, jcohen@genezzo.com

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    any later version.
    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.
    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA

Address bug reports and comments to: jcohen@genezzo.com

For more information, please visit the Genezzo homepage at <http://www.genezzo.com>