Index and search pods using x entries.
### 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\t%s\n", $r->podname, $r->line;
print $r->pod;
}
The Pod-Index distribution includes various modules for indexing and searching \s-1POD\s0 that is appropriately marked with X<> \s-1POD\s0 codes.
\*(C`Pod::Index\*(C', 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 \s-1POD\s0 indexing; specifically, the recommended conventions for the use of X<> codes.
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>"
First, a definition. By \*(L"scope\*(R", 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:
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.
The scope ends right before the next =item, or the =back that terminates the containing list. Note: \*(L"empty\*(R" 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 \*(L"=item function\*(R", and ends right before \*(L"=item lemonade\*(R".
3) other command paragraphs, such as =back, =over, =begin, =end, and =for should not be used for attaching X<> entries.
It should contain plain text without further formatting codes (with the possible exception of E<>).
It should be in lowercase, unless caps are required due to case-sensitivity or correctness.
Non-word characters are allowed, so one can list things like operators and special variables.
Use of synonyms is encouraged, to make things easier to find.
To be consistent, words should be normalized to the singular whenever possible. For example, use X<operator> instead of X<operators>.
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, \*(L"X<operator, logical>\*(R", or \*(L"X<operator, logical, xor>\*(R". 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.
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.
0.14
Pod::Index::Builder, Pod::Index::Search, Pod::Index::Entry, perlpod
Ivan Tubert-Brohman <[email protected]>
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.