#!/usr/bin/perl -w

# Simple minded extension to pod2text to include a Table of Contents (TOC)
# You can specify a path to the pod file or the module name:
#
# usage: perl toc.pl /libpath/Some/Module.pm
#      : perl toc.pl Some::Module
#
# reverse('©'), MMII, John McNamara, jmcnamara@cpan.org

use strict;

# Get the Pod filename from the absolute path or the module name
my $podfile = shift || die "usage: perl toc.pl filename [or module]\n";
$podfile    = `perldoc -l $podfile`;
exit if $?;


# Check that the Pod is readable/exists
open  TMP, $podfile or die "$podfile: $!.\n";
close TMP;


# Separate the NAME section from the rest of the Pod
my @name = `podselect -section  NAME $podfile`;
my @pod  = `podselect -section !NAME $podfile`;


# Create a TOC Pod section
my @toc  = ("\n=head1 TABLE OF CONTENTS\n\n");

# Create the TOC from the Pod headings as a verbatim paragraph
foreach (@name, @pod) {
    if (/^=head(\d)\s+(.*)/) {
        push @toc, "    " x $1 . $2 . "\n";
    }
}
push  @toc, "\n";


# Redirect the updated Pod to pod2text
open  POD2TEXT, "| pod2text"  or die "Cannot fork: $!.\n";
print POD2TEXT @name, @toc, @pod;
close POD2TEXT;

__END__

Sample output from "perl toc.pl Parse::RecDescent"

NAME
    Parse::RecDescent - Generate Recursive-Descent Parsers

TABLE OF CONTENTS
        NAME
        VERSION
        SYNOPSIS
        DESCRIPTION
            Overview
            Using C<Parse::RecDescent>
            Rules
            Subrules
            Tokens
            Terminal Separators
            Actions
            Start-up Actions
            Autoactions
            Autotrees
            Autostubbing
            Look-ahead
            Directives
            Subrule argument lists
            Alternations
            Incremental Parsing
            Precompiling parsers
            A Metagrammar for C<Parse::RecDescent>
        GOTCHAS
            1. Expecting an error to always invalidate a parse
        DIAGNOSTICS
        AUTHOR
        BUGS AND IRRITATIONS
        ON-GOING ISSUES AND FUTURE DIRECTIONS
        COPYRIGHT

VERSION
    This document describes version 1.80 of Parse::RecDescent, released
    January 20, 2001.

SYNOPSIS

..... etc