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\t%s\n", $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.¶
- •
- 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, "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.
- •
- 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.