Ivan Tubert-Brohman > Pod-Index > Pod::Index

Download:
Pod-Index-0.14.tar.gz

Dependencies

Annotate this POD

Related Modules

Pod::Select
more...
By perlmonks.org
View/Report Bugs
Module Version: 0.14   Source  

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.

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.

syntax highlighting: