in reply to Who's afraid of the manual?

As a one-liner I would prefer something like this: perl -nle 'print "\t"x($1-1),$2 if /^=head(\d)\s+(.*)/' /somepath/perlop.pod Or as a short program:
#!/usr/bin/perl -l # Call the program as follows: # perl perlop # perl Parse::RecDescent my $podfile = `perldoc -l @ARGV[0]`; exit if $?; open POD, $podfile or die "$podfile: $!.\n"; while (<POD>) { print " " x ($1-1), $2 if /^=head(\d)\s+(.*)/; }
What do you think: should all lengthy Perl documentation have a table of contents?

Unfortunately, it is too late to add a table of contents as a requirement for Perl documentation. However, it shouldn't be difficult to extend the above methodology to read a pod file, generate a table of contents, add it to a copy of the original pod as a section after NAME and redirect it to pod2text.