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)