Genezzo::BasicHelp - Genezzo Help Facility
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.
Return the BasicHelp pod document as a formatted text string.
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:
A case-insensitve prefix match for a particular group or area. Default is "Basic_Commands".
A case-insensitive regex to match a specific set of topics in the group. Defaults to all topics if not specified.
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".
Take a raw pod help document (as a string) and parse it, updating the searchable BasicHelp data structure.
Jeffrey I. Cohen, firstname.lastname@example.org
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: email@example.com
For more information, please visit the Genezzo homepage at http://www.genezzo.com