/ 
Genezzo-0.72
River stage zero No dependents
/ Genezzo::BasicHelp

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
hierarchical topic groups and searches

AUTHOR

Jeffrey I. Cohen, jcohen@genezzo.com

SEE ALSO

perl(1).

Copyright (c) 2006, 2007 Jeffrey I Cohen. All rights reserved.

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