pod::index::search(3pm) [debian man page]
Pod::Index::Search(3pm) User Contributed Perl Documentation Pod::Index::Search(3pm) NAME
Pod::Index::Search - Search for keywords in an indexed pod SYNOPSIS
use Pod::Index::Search; my $q = Pod::Index::Search->new; my @results = $q->search('getprotobyname'); for my $r (@results) { printf "%s %s ", $r->podname, $r->line; print $r->pod; } my @subtopics = $q->subtopics('operator'); DESCRIPTION
This module searches an index created by Pod::Index::Builder. Search results are returned as Pod::Index::Entry objects. It is also possible to search for subtopics for a keyword. For example, a search for "operator" might return things like operator, conditional operator, filetest operator, logical operator, precedence operator, relational The subtopics returned are simple strings. METHODS
new my $q = Pod::Index::Search->new(%args); Create a new search object. Possible arguments are: "fh" The filehandle of the index to use. If omitted, "perlindex::DATA" is used. "filename" The filename of the index to use. Note that you can specify either "fh" or filename, but not both. "filemap" A subroutine reference that takes a podname and returns a filename. A simple example might be: sub { my $podname = shift; return "/usr/lib/perl5/5.8.7/pod/$podname.pod"; } The podname is in colon-delimited Perl package syntax. The default "filemap" returns the first file in @INC that seems to have the proper documentation (either a .pod or .pm file). "nocase" If true, the search will be case-insensitive. search($keyword) Do the actual search in the index. Returns a list of search results, as Pod::Index::Entry objects. subtopics($keyword, %options) my @topics = $q->subtopics('operator'); my @topics = $q->subtopics('operator', deep => 1); Lists the subtopics for a given keyword. If "deep" is given, it includes all subtopics; otherwise, only the first level of subtopics is included. VERSION
0.14 SEE ALSO
Pod::Index::Entry, Pod::Index::Builder AUTHOR
Ivan Tubert-Brohman <itub@cpan.org> COPYRIGHT
Copyright (c) 2005 Ivan Tubert-Brohman. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. perl v5.10.0 2005-10-16 Pod::Index::Search(3pm)
Check Out this Related Man Page
Pod::Index(3pm) User Contributed Perl Documentation Pod::Index(3pm) NAME
Pod::Index - Index and search PODs using X<> entries. SYNOPSIS
### to create an index: use Pod::Index::Builder; my $p = Pod::Index::Builder->new; for my $file (@ARGV) { $p->parse_from_file($file); } $p->print_index("index.txt"); ### to search for a keyword in the index: use Pod::Index::Search; my $q = Pod::Index::Search->new( filename => 'index.txt', ); my @results = $q->search('getprotobyname'); for my $r (@results) { printf "%s %s ", $r->podname, $r->line; print $r->pod; } DESCRIPTION
The Pod-Index distribution includes various modules for indexing and searching POD that is appropriately marked with X<> POD codes. "Pod::Index", as a module, does nothing. Everything is done by Pod::Index::Builder, Pod::Index::Search, and other helper modules. This document discusses some of the general issues with POD indexing; specifically, the recommended conventions for the use of X<> codes. BACKGROUND
The little-known (or at least little-used) X<> formatting code is described in perlpod: "X<topic name>" -- an index entry This is ignored by most formatters, but some may use it for build- ing indexes. It always renders as empty-string. Example: "X<abso- lutizing relative URLs>" CONVENTIONS FOR THE USE OF X<;> CODES Placement of the X<> entries First, a definition. By "scope", I mean the part of the document that is deemed relevant to an index entry, and that may be extracted and shown in isolation by a processing or display tool. For example, perldoc -f considers the scope of a function to end at the beginning of the next =item, or at the end of the enclosing =over. The X<> entries should be added at the end of a command or textblock paragraph (verbatim paragraphs are excluded). The scope of the index entry starts at the beginning of the paragraph to which it was attached; the end of the scope depends on the command type: 1) if the X<> is at the end of a textblock, the scope is that paragraph and zero or more verbatim paragraphs immediately following it. 2) if the X<> is at the end of a command paragraph, it depends on the type of command: =head1, head2, etc. The scope ends right before the next heading with equal or higher level. That is, a =head1 ends at the next =head1, and a =head2 ends at the next =head2 or =head1. =item The scope ends right before the next =item, or the =back that terminates the containing list. Note: "empty" items are not counted for terminating scopes, to allow for cases where multiple =items head a block of text. For example, =item function X<function> X<otherfunction> =item otherfunction C<function> and C<otherfunction> do the same thing, even if they have different names... =item lemonade Here the scope of the X<function> and X<otherfunction> entries starts with "=item function", and ends right before "=item lemonade". 3) other command paragraphs, such as =back, =over, =begin, =end, and =for should not be used for attaching X<> entries. Content of the X<> entry. o It should contain plain text without further formatting codes (with the possible exception of E<>). o It should be in lowercase, unless caps are required due to case-sensitivity or correctness. o Non-word characters are allowed, so one can list things like operators and special variables. o Use of synonyms is encouraged, to make things easier to find. o To be consistent, words should be normalized to the singular whenever possible. For example, use X<operator> instead of X<operators>. o The use of a comma in an index entry has a special meaning: it separates levels of hierarchy (or namespaces), as a way of classifying entries in more specific ways. For example, "X<operator, logical>", or "X<operator, logical, xor>". This information may be used by processing programs to arrange the entries, or for listing results when a user searches for a namespace that contains several entries. o There's no limitation as to the number of times that a given entry can appear in a document or collection of documents. That is, it is not an error to have X<whatever> appear twice in the same file. VERSION
0.14 SEE ALSO
Pod::Index::Builder, Pod::Index::Search, Pod::Index::Entry, perlpod AUTHOR
Ivan Tubert-Brohman <itub@cpan.org> COPYRIGHT
Copyright (c) 2005 Ivan Tubert-Brohman. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. perl v5.10.0 2005-10-16 Pod::Index(3pm)