NAME

Pod::PseudoPod::CrossReference -- a framework for extracting information from PseudoPOD files for cross-referencing.

SYNOPSIS

#!/usr/bin/perl -w
use strict;

use Pod::PseudoPod::CrossReference;
use File::Spec;
use File::Basename;
use Storable;

my $id;
my $index = { };
my @head;
my $indir = $ARGV[0];
for my $file (<$indir/*pod>) {
    my $p = Pod::PseudoPod::CrossReference->new;
    $p->set_handlers('Z', \&Z); 
    $p->set_handlers('head0', \&head0); 
    $p->set_handlers('head1', \&head1); 
    $p->set_handlers('head2', \&head2); 
    $p->set_handlers('head3', \&head3); 
    $p->set_handlers('head4', \&head4); 
    $id = basename($file,'.pod');
    $p->parse_file($file);
}
store $index, File::Spec->catfile($indir,'ref.stor');

sub Z {
    $index->{$_[1]} = {
        title => $_[0]->{'title'},
        id => $id,
        type => $_[0]->{'reftype'},
    }
}

sub head0 { handler(0) }
sub head1 { handler(1) }
sub head2 { handler(2) }
sub head3 { handler(3) }
sub head4 { handler(4) }

sub handler { 
    my $index = shift;
    $head[$index]++; 
    for (my $i=$index-1; $i>0; $i--) {
        $head[$i] = 0;
    }
    "Section ".join('.',@head[0..$index]); 
}

DESCRIPTION

This module is a framework for extracting information from PseudoPOD files for cross-referencing. It implements a callback mechanism that developers can use to hook occurrences of certain PseudoPOD markup to create a data table of cross reference information. Rather the predetermining how an identifier is labeled, Pod::PseudoPod::CrossReference provides a framework that lets you decided how identifiers are labeled and stored. The data collected from this process can be used to create links that are more accurate and adaptable to document revisions.

The inline Z element is used to mark a section for cross-refencing. It's good form to place this marker immediately after the start of the block. For example:

=head0 In The Beginning

Z<the_beginning>

Here the section 'In The Beginning' is given a marker of 'the_beginning' which can be used to link back to this section.

Not placing the Z element right after the start of the section it is associated to may cause the cross reference processor to return incorrect results.

Typically the Z handler is used to record labels in a data structure. What information the Z handler has to work with is setup by all of the other block handlers.

METHODS

This is a subclass of Pod::PseudoPod and inherits all its methods. This module ads one important method that makes cross-referencing possible.

$ref->set_handlers(element,coderef[,element,coderef,...])

This method is used to register the callback handlers for the Z and recognized block element types for the parser to return. All block handlers must return a string that will be used (presumably) as the title for that section if a marker exists. The Z handler ignores any values that are returned.

element is the PseudoPOD block element name the callback is for. coderef is a reference to the subroutine that should be called as each instance of element is processed.

Multiple elements/coderef pairs can be passed with one call or each handler can be set individually.

No specific handler is required though without any handlers this module is rather pointless.

HANDLERS

The following handlers are recognized by the processor.

head0

head1

head2

head3

head4

table

figure

SEE ALSO

Pod::PseudoPod, Pod::PseudoPod::Tutorial

LICENSE

The software is released under the Artistic License. The terms of the Artistic License are described at http://www.perl.com/language/misc/Artistic.html.

AUTHOR & COPYRIGHT

Except where otherwise noted, Pod::PseudoPod::CrossReference is Copyright 2005, Timothy Appnel, tima@cpan.org. All rights reserved.