Merge the refactoring that abolishes pod.lst to blead.

12 files changed, 124 insertions, 370 deletions

diff --git a/MANIFEST b/MANIFEST
index 9f0b5d1fb4..e535dcd016 100644
--- a/MANIFEST
+++ b/MANIFEST
@@ -4572,8 +4572,7 @@ plan9/plan9.c			Plan9 port: Plan9-specific C routines
 plan9/plan9ish.h		Plan9 port: Plan9-specific C header file
 plan9/setup.rc			Plan9 port: script for easy build+install
 plan9/versnum			Plan9 port: script to print version number
-pod/buildtoc			Update files based on pod.lst
-pod.lst				List the pods and their roles
+pod/buildtoc			Generate pod/perltoc.pod and pod/roffitall
 pod/Makefile.SH			generate Makefile which makes pods into something else
 pod/perl5004delta.pod		Perl changes in version 5.004
 pod/perl5005delta.pod		Perl changes in version 5.005
@@ -4747,7 +4746,7 @@ Porting/new-perldelta.pl	Generate a new perldelta
 Porting/newtests-perldelta.pl	Generate Perldelta stub for newly added tests
 Porting/perldelta_template.pod	Template for creating new perldelta.pod files
 Porting/perlhist_calculate.pl		Perform calculations to update perlhist
-Porting/pod_lib.pl		Code for handling pod.lst
+Porting/pod_lib.pl		Code for handling generated pods
 Porting/pod_rules.pl		generate lists of pod files for Makefiles
 Porting/podtidy			Reformat pod using Pod::Tidy
 Porting/pumpkin.pod		Guidelines and hints for Perl maintainers
diff --git a/Porting/bump-perl-version b/Porting/bump-perl-version
index a0b83110f3..b867414fb1 100644
--- a/Porting/bump-perl-version
+++ b/Porting/bump-perl-version
@@ -217,7 +217,6 @@ my %SKIP_FILES = map { ($_ => 1) } qw(
     Porting/release_managers_guide.pod
     Porting/release_schedule.pod
     Porting/bump-perl-version
-    pod.lst
     pp_ctl.c
 );
 my @SKIP_DIRS = qw(
diff --git a/Porting/new-perldelta.pl b/Porting/new-perldelta.pl
index 4fa7fd13f2..d4fb5936ee 100644
--- a/Porting/new-perldelta.pl
+++ b/Porting/new-perldelta.pl
@@ -82,11 +82,11 @@ foreach([rXXX => $was_major],
 write_or_die('pod/perldelta.pod', $newdelta);
 git_add_modified('pod/perldelta.pod');
 
-$filename = 'pod.lst';
+$filename = 'pod/perl.pod';
 my $pod_master = slurp_or_die($filename);
 
-$pod_master =~ s{^(\s*perl5)($old_major$old_minor)(delta\s+Perl changes in version )(5\.\d+\.\d+)(.*)}
-    {$1 . $new_major . $new_minor .$3 . "5.$new_major.$new_minor" . $5 . "\n" .
+$pod_master =~ s{^(\s*perl5)($was_major$was_minor)(delta\s+Perl changes in version )(5\.\d+\.\d+)(.*)}
+    {$1 . $old_major . $old_minor .$3 . "5.$old_major.$old_minor" . $5 . "\n" .
          "$1$2$3$4$5"}me
     or die "Can't find perldelta line in $filename";
 
diff --git a/Porting/pod_lib.pl b/Porting/pod_lib.pl
index 95bea6114b..a87c3ee048 100644
--- a/Porting/pod_lib.pl
+++ b/Porting/pod_lib.pl
@@ -56,12 +56,12 @@ my %state = (
         unless (%Lengths) {
             __prime_state() unless $state{master};
             foreach (@{$state{master}}) {
-                next if !$_ || @$_ < 4 || $_->[1] eq $_->[4];
+                next unless $_->[2]{dual};
                 # This is a dual-life perl*.pod file, which will have be copied
                 # to lib/ by the build process, and hence also found there.
                 # These are the only pod files that might become duplicated.
-                ++$Lengths{-s $_->[2]};
-                ++$MD5s{md5(slurp_or_die($_->[2]))};
+                ++$Lengths{-s $_->[1]};
+                ++$MD5s{md5(slurp_or_die($_->[1]))};
             }
         }
 
@@ -79,7 +79,8 @@ sub __prime_state {
     my @want =
         $contents =~ /perldelta - what is new for perl v(5)\.(\d+)\.(\d+)\n/;
     die "Can't extract version from $filename" unless @want;
-    $state{delta_target} = join '', 'perl', @want, 'delta.pod';
+    my $delta_leaf = join '', 'perl', @want, 'delta';
+    $state{delta_target} = "$delta_leaf.pod";
     $state{delta_version} = \@want;
 
     # This way round so that keys can act as a MANIFEST skip list
@@ -87,35 +88,71 @@ sub __prime_state {
     # with sources being in the same directory.
     $state{copies}{$state{delta_target}} = $source;
 
+    # The default flags if none explicitly set for the current file.
+    my $current_flags = '';
+    my (%flag_set, @paths);
 
-    # process pod.lst
-    my $master = open_or_die('pod.lst');
+    my $master = open_or_die('pod/perl.pod');
+
+    while (<$master>) {
+        last if /^=begin buildtoc$/;
+    }
+    die "Can't find '=begin buildtoc':" if eof $master;
+
+    while (<$master>) {
+        next if /^$/ or /^#/;
+        last if /^=end buildtoc/;
+        my ($command, @args) = split ' ';
+        if ($command eq 'flag') {
+            # For the named pods, use these flags, instead of $current_flags
+            my $flags = shift @args;
+            my_die("Malformed flag $flags")
+                unless $flags =~ /\A=([a-z]*)\z/;
+            $flag_set{$_} = $1 foreach @args;
+        } elsif ($command eq 'path') {
+            # If the pod's name matches the regex, prepend the given path.
+            my_die("Malformed path for /$args[0]/")
+                unless @args == 2;
+            push @paths, [qr/\A$args[0]\z/, $args[1]];
+        } elsif ($command eq 'aux') {
+            # The contents of perltoc.pod's "AUXILIARY DOCUMENTATION" section
+            $state{aux} = [sort @args];
+        } else {
+            my_die("Unknown buildtoc command '$command'");
+        }
+    }
 
     foreach (<$master>) {
-        next if /^\#/;
-
-        # At least one upper case letter somewhere in the first group
-        if (/^(\S+)\s(.*)/ && $1 =~ tr/h//) {
-            # it's a heading
-            my $flags = $1;
-            $flags =~ tr/h//d;
-            my %flags = (header => 1);
-            $flags{toc_omit} = 1 if $flags =~ tr/o//d;
-            $flags{aux} = 1 if $flags =~ tr/a//d;
-            my_die "Unknown flag found in heading line: $_" if length $flags;
-
-            push @{$state{master}}, [\%flags, $2];
-        } elsif (/^(\S*)\s+(\S+)\s+(.*)/) {
-            # it's a section
-            my ($flags, $podname, $desc) = ($1, $2, $3);
-            my $filename = "${podname}.pod";
-            $filename = "pod/${filename}" if $filename !~ m{/};
-
-            my %flags = (indent => 0);
-            $flags{indent} = $1 if $flags =~ s/(\d+)//;
+        next if /^$/ or /^#/;
+        next if /^=head2/;
+        last if /^=for buildtoc __END__$/;
+
+        if (my ($action, $flags) = /^=for buildtoc flag ([-+])([a-z]+)/) {
+            if ($action eq '+') {
+                $current_flags .= $flags;
+            } else {
+                my_die("Attempt to unset [$flags] failed - flags are '$current_flags")
+                    unless $current_flags =~ s/[\Q$flags\E]//g;
+            }
+        } elsif (my ($leafname, $desc) = /^\s+(\S+)\s+(.*)/) {
+            my $podname = $leafname;
+            my $filename = "pod/$podname.pod";
+            foreach (@paths) {
+                my ($re, $path) = @$_;
+                if ($leafname =~ $re) {
+                    $podname = $path . $leafname;
+                    $filename = "$podname.pod";
+                    last;
+                }
+            }
+
+            # Keep this compatible with pre-5.10
+            my $flags = delete $flag_set{$leafname};
+            $flags = $current_flags unless defined $flags;
+
+            my %flags;
             $flags{toc_omit} = 1 if $flags =~ tr/o//d;
-            $flags{aux} = 1 if $flags =~ tr/a//d;
-            $flags{perlpod_omit} = "$podname.pod" eq $state{delta_target};
+            $flags{dual} = $podname ne $leafname;
 
             $state{generated}{"$podname.pod"}++ if $flags =~ tr/g//d;
 
@@ -124,23 +161,30 @@ sub __prime_state {
                 $readme =~ s/^perl//;
                 $state{readmes}{$readme} = $desc;
                 $flags{readme} = 1;
-            } elsif ($flags{aux}) {
-                $state{aux}{$podname} = $desc;
             } else {
                 $state{pods}{$podname} = $desc;
             }
             my_die "Unknown flag found in section line: $_" if length $flags;
-            my ($leafname) = $podname =~ m!([^/]+)$!;
 
             push @{$state{master}},
-                [\%flags, $podname, $filename, $desc, $leafname];
-        } elsif (/^$/) {
-            push @{$state{master}}, undef;
+                [$leafname, $filename, \%flags];
+
+            if ($podname eq 'perldelta') {
+                local $" = '.';
+                push @{$state{master}},
+                    [$delta_leaf, "pod/$state{delta_target}"];
+                $state{pods}{$delta_leaf} = "Perl changes in version @want";
+            }
+
         } else {
-            my_die "Malformed line: $_" if $1 =~ tr/A-Z//;
+            my_die("Malformed line: $_");
         }
     }
-    close $master or my_die "close pod.lst: $!";
+    close $master or my_die("close pod/perl.pod: $!");
+
+    my_die("perl.pod sets flags for unknown pods: "
+           . join ' ', sort keys %flag_set)
+        if keys %flag_set;
 }
 
 sub get_pod_metadata {
@@ -161,7 +205,7 @@ sub get_pod_metadata {
 
     # Sanity cross check
 
-    my (%disk_pods, %manipods, %manireadmes, %perlpods);
+    my (%disk_pods, %manipods, %manireadmes);
     my (%cpanpods, %cpanpods_leaf);
     my (%our_pods);
 
@@ -174,8 +218,8 @@ sub get_pod_metadata {
     # Convert these to a list of filenames.
     ++$our_pods{"$_.pod"} foreach keys %{$state{pods}};
     foreach (@{$state{master}}) {
-        ++$our_pods{"$_->[1].pod"}
-            if defined $_ && @$_ == 5 && $_->[0]{readme};
+        ++$our_pods{"$_->[0].pod"}
+            if $_->[2]{readme};
     }
 
     opendir my $dh, 'pod';
@@ -206,18 +250,6 @@ sub get_pod_metadata {
     }
     close $mani or my_die "close MANIFEST: $!\n";
 
-    my $perlpod = open_or_die('pod/perl.pod');
-    while (<$perlpod>) {
-        if (/^For ease of access, /../^\(If you're intending /) {
-            if (/^\s+(perl\S*)\s+\w/) {
-                ++$perlpods{"$1.pod"};
-            }
-        }
-    }
-    close $perlpod or my_die "close perlpod: $!\n";
-    my_die "could not find the pod listing of perl.pod\n"
-        unless %perlpods;
-
     # Are we running before known generated files have been generated?
     # (eg in a clean checkout)
     my %not_yet_there;
@@ -234,10 +266,6 @@ sub get_pod_metadata {
             if !$BuildFiles{'MANIFEST'} # Ignore if we're rebuilding MANIFEST
                 && !$manipods{$i} && !$manireadmes{$i} && !$state{copies}{$i}
                     && !$state{generated}{$i} && !$cpanpods{$i};
-        push @inconsistent, "$0: $i exists but is unknown by perl.pod\n"
-            if !$BuildFiles{'perl.pod'} # Ignore if we're rebuilding perl.pod
-                && !$perlpods{$i} && !exists $state{copies}{$i}
-                    && !$cpanpods{$i} && !$ignoredpods{$i};
     }
     foreach my $i (sort keys %our_pods) {
         push @inconsistent, "$0: $i is known by buildtoc but does not exist\n"
@@ -252,14 +280,6 @@ sub get_pod_metadata {
                 if $state{generated}{$i};
         }
     }
-    unless ($BuildFiles{'perl.pod'}) {
-        # Again, ignore these if we're about to rebuild perl.pod
-        foreach my $i (sort keys %perlpods) {
-            push @inconsistent, "$0: $i is known by perl.pod but does not exist\n"
-                unless $disk_pods{$i} or $BuildFiles{$i} or $cpanpods_leaf{$i}
-                    or $not_yet_there{$i};
-        }
-    }
     &$callback(@inconsistent);
     return \%state;
 }
diff --git a/Porting/pod_rules.pl b/Porting/pod_rules.pl
index 689219a794..838601597e 100644
--- a/Porting/pod_rules.pl
+++ b/Porting/pod_rules.pl
@@ -7,19 +7,18 @@ use Text::Wrap;
 use Getopt::Long;
 use Carp;
 
-# Generate the sections of files listed in %Targets from pod.lst
+# Generate the sections of files listed in %Targets from pod/perl.pod
 # Mostly these are rules in Makefiles
 #
 # --verbose gives slightly more output
 # --build-all tries to build everything
 # --build-foo updates foo as follows
 # --showfiles shows the files to be changed
-# --test exit if perl.pod, pod.lst, MANIFEST are consistent, and regenerated
+# --test exit if perl.pod, MANIFEST are consistent, and regenerated
 #   files are up to date, die otherwise.
 
 %Targets = (
             manifest => 'MANIFEST',
-            perlpod => 'pod/perl.pod',
             vms => 'vms/descrip_mms.template',
             nmake => 'win32/Makefile',
             dmake => 'win32/makefile.mk',
@@ -77,37 +76,6 @@ my $state = $Test
                        })
     : get_pod_metadata(1, sub { warn @_ if @_ }, values %Build);
 
-sub generate_perlpod {
-    my @output;
-    my $maxlength = 0;
-    foreach (@{$state->{master}}) {
-        my $flags = $_->[0];
-        next if $flags->{aux};
-        next if $flags->{perlpod_omit};
-
-        if (@$_ == 2) {
-            # Heading
-            push @output, "=head2 $_->[1]\n";
-        } elsif (@$_ == 5) {
-            # Section
-            my $start = " " x (4 + $flags->{indent}) . $_->[4];
-            $maxlength = length $start if length ($start) > $maxlength;
-            push @output, [$start, $_->[3]];
-        } elsif (@$_ == 0) {
-            # blank line
-            push @output, "\n";
-        } else {
-            my_die "Illegal length " . scalar @$_;
-        }
-    }
-    # want at least 2 spaces padding
-    $maxlength += 2;
-    $maxlength = ($maxlength + 3) & ~3;
-    # sprintf gives $1.....$2 where ... are spaces:
-    return unexpand (map {ref $_ ? sprintf "%-${maxlength}s%s\n", @$_ : $_}
-                     @output);
-}
-
 sub generate_manifest {
     # Annoyingly, unexpand doesn't consider it good form to replace a single
     # space before a tab with a tab
@@ -172,7 +140,7 @@ sub verify_contiguous {
 sub do_manifest {
     my ($name, $prev) = @_;
     my @manifest =
-        grep {! m!^pod/[^.]+\.pod.*!}
+        grep {! m!^pod/[^. \t]+\.pod.*!}
             grep {! m!^README\.(\S+)! || $state->{ignore}{$1}} split "\n", $prev;
     join "\n", (
                 # Dictionary order - fold and handle non-word chars as nothing
@@ -200,21 +168,6 @@ sub do_nmake {
 # shut up used only once warning
 *do_dmake = *do_dmake = \&do_nmake;
 
-sub do_perlpod {
-    my ($name, $pod) = @_;
-
-    unless ($pod =~ s{(For\ ease\ of\ access,\ .*\n)
-                      (?:\s+[a-z]{4,}.*\n   #   fooo
-                      |=head.*\n            # =head foo
-                      |\s*\n                # blank line
-                   )+
-                 }
-                     {$1 . join "", &generate_perlpod}mxe) {
-        my_die "Failed to insert amendments in do_perlpod";
-    }
-    $pod;
-}
-
 sub do_podmak {
     my ($name, $body) = @_;
     foreach my $variable (qw(pod man html tex)) {
diff --git a/Porting/release_managers_guide.pod b/Porting/release_managers_guide.pod
index 75b0bf3d90..f13f37d2fe 100644
--- a/Porting/release_managers_guide.pod
+++ b/Porting/release_managers_guide.pod
@@ -397,7 +397,7 @@ For example, for RC0 of 5.16.0:
     $ git rm perldelta515*.pod
 
 All mention to them should also be removed.  Currently the files that
-need to be edited for this task are F<MANIFEST>, F<pod.list>,
+need to be edited for this task are F<MANIFEST>,
 F<pod/perl.pod>, and F<win32/pod.mak> (including C<.man>, C<.html>, and
 C<.tex> entries for each removed pod).
 
@@ -996,7 +996,7 @@ example:
     $ cp -i ../5.10.x/pod/perldelta.pod pod/perl5101delta.pod    # for example
     $ git add pod/perl5101delta.pod
 
-Edit F<pod.lst> to add an entry for the file, e.g.:
+Edit F<pod/perl.pod> to add an entry for the file, e.g.:
 
     perl5101delta		Perl changes in version 5.10.1
 
diff --git a/README.cygwin b/README.cygwin
index abfd996efc..08881406cc 100644
--- a/README.cygwin
+++ b/README.cygwin
@@ -563,7 +563,7 @@ be kept as clean as possible.
   pod/perl561delta.pod pod/perl570delta.pod pod/perl572delta.pod
   pod/perl573delta.pod pod/perl58delta.pod pod/perl581delta.pod
   pod/perl590delta.pod pod/perlhist.pod pod/perlmodlib.pod
-  pod/perltoc.pod pod.lst Porting/Glossary pod/perlgit.pod
+  pod/perltoc.pod Porting/Glossary pod/perlgit.pod
   Porting/checkAUTHORS.pl
   dist/Cwd/Changes ext/Compress-Raw-Zlib/Changes
   ext/Compress-Raw-Zlib/README ext/Compress-Zlib/Changes
diff --git a/installman b/installman
index e986a78410..fb43e85bb4 100755
--- a/installman
+++ b/installman
@@ -74,7 +74,7 @@ my %do_not_install = map { ($_ => 1) } qw(
 # Install the main pod pages.
 pod2man({
          map {
-             $_ && @$_ > 2 && !$_->[0]{aux} ? ($_->[4], $_->[2]): ()
+             ($_->[0], $_->[1])
          } @{$state->{master}}
         }, $opts{man1dir}, $opts{man1ext});
 
diff --git a/lib/unicore/README.perl b/lib/unicore/README.perl
index 1a94d031bb..2518a604a5 100644
--- a/lib/unicore/README.perl
+++ b/lib/unicore/README.perl
@@ -105,7 +105,7 @@ current one is
 mktables has many checks to warn you if there are unexpected or novel things
 that it doesn't know how to handle.
 
-pod.lst should be changed so that it gives the new name (which includes the
+perl.pod should be changed so that it gives the new name (which includes the
 Unicode release number) for perluniprops.pod
 
 Module::CoreList should be changed to include the new release
diff --git a/pod.lst b/pod.lst
deleted file mode 100644
index 9e1a47e30f..0000000000
--- a/pod.lst
+++ /dev/null
@@ -1,240 +0,0 @@
-# h	- Header
-# o	- Omit from toc
-# r	- top level READMEs to be copied/symlinked
-# g	- other autogenerated pods
-# a	- for auxiliary documentation
-# number - indent by
-
-h Overview
-
-  perl			Perl overview (this section)
-  perlintro		Perl introduction for beginners
-go perltoc		Perl documentation table of contents
-
-h Tutorials
-
-  perlreftut		Perl references short introduction
-  perldsc		Perl data structures intro
-  perllol		Perl data structures: arrays of arrays
-
-  perlrequick		Perl regular expressions quick start
-  perlretut		Perl regular expressions tutorial
-
-  perlootut		Perl OO tutorial for beginners
-
-  perlperf		Perl Performance and Optimization Techniques
-
-  perlstyle		Perl style guide
-
-  perlcheat		Perl cheat sheet
-  perltrap		Perl traps for the unwary
-  perldebtut		Perl debugging tutorial
-
-  cpan/perlfaq/lib/perlfaq		Perl frequently asked questions
-2 cpan/perlfaq/lib/perlfaq1		General Questions About Perl
-2 cpan/perlfaq/lib/perlfaq2		Obtaining and Learning about Perl
-2 cpan/perlfaq/lib/perlfaq3		Programming Tools
-2 cpan/perlfaq/lib/perlfaq4		Data Manipulation
-2 cpan/perlfaq/lib/perlfaq5		Files and Formats
-2 cpan/perlfaq/lib/perlfaq6		Regexes
-2 cpan/perlfaq/lib/perlfaq7		Perl Language Issues
-2 cpan/perlfaq/lib/perlfaq8		System Interaction
-2 cpan/perlfaq/lib/perlfaq9		Networking
-
-h Reference Manual
-
-  perlsyn		Perl syntax
-  perldata		Perl data structures
-  perlop		Perl operators and precedence
-  perlsub		Perl subroutines
-  perlfunc		Perl built-in functions
-2 perlopentut		Perl open() tutorial
-2 perlpacktut		Perl pack() and unpack() tutorial
-  perlpod		Perl plain old documentation
-  perlpodspec		Perl plain old documentation format specification
-  perlpodstyle		Perl POD style guide
-  perlrun		Perl execution and options
-  perldiag		Perl diagnostic messages
-  perllexwarn		Perl warnings and their control
-  perldebug		Perl debugging
-  perlvar		Perl predefined variables
-  perlre		Perl regular expressions, the rest of the story
-  perlrebackslash	Perl regular expression backslash sequences
-  perlrecharclass	Perl regular expression character classes
-  perlreref		Perl regular expressions quick reference
-  perlref		Perl references, the rest of the story
-  perlform		Perl formats
-  perlobj		Perl objects
-  perltie		Perl objects hidden behind simple variables
-2 perldbmfilter		Perl DBM filters
-
-  perlipc		Perl interprocess communication
-  perlfork		Perl fork() information
-  perlnumber		Perl number semantics
-
-  perlthrtut		Perl threads tutorial
-
-  perlport		Perl portability guide
-  perllocale		Perl locale support
-  perluniintro		Perl Unicode introduction
-  perlunicode		Perl Unicode support
-  perlunifaq		Perl Unicode FAQ
-g perluniprops		Index of Unicode Version 6.0.0 properties in Perl
-  perlunitut		Perl Unicode tutorial
-  perlebcdic		Considerations for running Perl on EBCDIC platforms
-
-  perlsec		Perl security
-
-  perlmod		Perl modules: how they work
-g perlmodlib		Perl modules: how to write and use
-  perlmodstyle		Perl modules: how to write modules with style
-  perlmodinstall	Perl modules: how to install from CPAN
-  perlnewmod		Perl modules: preparing a new module for distribution
-  perlpragma		Perl modules: writing a user pragma
-
-  perlutil		utilities packaged with the Perl distribution
-
-  perlfilter		Perl source filters
-
-  perldtrace		Perl's support for DTrace
-
-  cpan/perlfaq/lib/perlglossary		Perl Glossary
-
-h Internals and C Language Interface
-
-  perlembed		Perl ways to embed perl in your C or C++ application
-  perldebguts		Perl debugging guts and tips
-  dist/ExtUtils-ParseXS/lib/perlxstut	Perl XS tutorial
-  dist/ExtUtils-ParseXS/lib/perlxs	Perl XS application programming interface
-  perlclib		Internal replacements for standard C library functions
-  perlguts		Perl internal functions for those doing extensions
-  perlcall		Perl calling conventions from C
-  perlmroapi		Perl method resolution plugin interface
-  perlreapi		Perl regular expression plugin interface
-  perlreguts		Perl regular expression engine internals
-
-g perlapi		Perl API listing (autogenerated)
-g perlintern		Perl internal functions (autogenerated)
-  perliol		C API for Perl's implementation of IO in Layers
-  perlapio		Perl internal IO abstraction interface
-
-  perlhack		Perl hackers guide
-  perlsource		Guide to the Perl source tree
-  perlinterp		Overview of the Perl interpreter source and how it works
-  perlhacktut		Walk through the creation of a simple C code patch
-  perlhacktips		Tips for Perl core C code hacking
-  perlpolicy		Perl development policies
-  perlgit		Using git with the Perl repository
-
-h Miscellaneous
-
-  perlbook		Perl book information
-  perlcommunity		Perl community information
-  perltodo		Perl things to do
-
-  dist/Pod-Perldoc/lib/perldoc	Look up Perl documentation in Pod format
-
-  perlhist		Perl history records
-  perldelta		Perl changes since previous version
-  perl5157delta		Perl changes in version 5.15.7
-  perl5156delta		Perl changes in version 5.15.6
-  perl5155delta		Perl changes in version 5.15.5
-  perl5154delta		Perl changes in version 5.15.4
-  perl5153delta		Perl changes in version 5.15.3
-  perl5152delta		Perl changes in version 5.15.2
-  perl5151delta		Perl changes in version 5.15.1
-  perl5150delta		Perl changes in version 5.15.0
-  perl5142delta		Perl changes in version 5.14.2
-  perl5141delta		Perl changes in version 5.14.1
-  perl5140delta		Perl changes in version 5.14.0
-  perl5124delta		Perl changes in version 5.12.4
-  perl5123delta		Perl changes in version 5.12.3
-  perl5122delta		Perl changes in version 5.12.2
-  perl5121delta		Perl changes in version 5.12.1
-  perl5120delta		Perl changes in version 5.12.0
-  perl5101delta		Perl changes in version 5.10.1
-  perl5100delta		Perl changes in version 5.10.0
-  perl589delta		Perl changes in version 5.8.9
-  perl588delta		Perl changes in version 5.8.8
-  perl587delta		Perl changes in version 5.8.7
-  perl586delta		Perl changes in version 5.8.6
-  perl585delta		Perl changes in version 5.8.5
-  perl584delta		Perl changes in version 5.8.4
-  perl583delta		Perl changes in version 5.8.3
-  perl582delta		Perl changes in version 5.8.2
-  perl581delta		Perl changes in version 5.8.1
-  perl58delta		Perl changes in version 5.8.0
-  perl561delta		Perl changes in version 5.6.1
-  perl56delta		Perl changes in version 5.6
-  perl5005delta		Perl changes in version 5.005
-  perl5004delta		Perl changes in version 5.004
-
-  perlexperiment	A listing of experimental features in Perl
-
-  perlartistic		Perl Artistic License
-  perlgpl		GNU General Public License
-
-ho Language-Specific
-
-ro perlcn		Perl for Simplified Chinese (in EUC-CN)
-ro perljp		Perl for Japanese (in EUC-JP)
-ro perlko		Perl for Korean (in EUC-KR)
-ro perltw		Perl for Traditional Chinese (in Big5)
-
-h Platform-Specific
-
-r perlaix		Perl notes for AIX
-r perlamiga		Perl notes for AmigaOS
-r perlbeos		Perl notes for BeOS
-r perlbs2000		Perl notes for POSIX-BC BS2000
-r perlce		Perl notes for WinCE
-r perlcygwin		Perl notes for Cygwin
-r perldgux		Perl notes for DG/UX
-r perldos		Perl notes for DOS
-r perlepoc		Perl notes for EPOC
-r perlfreebsd		Perl notes for FreeBSD
-r perlhaiku		Perl notes for Haiku
-r perlhpux		Perl notes for HP-UX
-r perlhurd		Perl notes for Hurd
-r perlirix		Perl notes for Irix
-r perllinux		Perl notes for Linux
-r perlmacos		Perl notes for Mac OS (Classic)
-r perlmacosx		Perl notes for Mac OS X
-r perlmpeix		Perl notes for MPE/iX
-r perlnetware		Perl notes for NetWare
-r perlopenbsd		Perl notes for OpenBSD
-r perlos2		Perl notes for OS/2
-r perlos390		Perl notes for OS/390
-r perlos400		Perl notes for OS/400
-r perlplan9		Perl notes for Plan 9
-r perlqnx		Perl notes for QNX
-r perlriscos		Perl notes for RISC OS
-r perlsolaris		Perl notes for Solaris
-r perlsymbian		Perl notes for Symbian
-r perltru64		Perl notes for Tru64
-r perluts		Perl notes for UTS
-r perlvmesa		Perl notes for VM/ESA
-  perlvms		Perl notes for VMS
-r perlvos		Perl notes for Stratus VOS
-r perlwin32		Perl notes for Windows
-
-oh Stubs for Deleted Documents
-
-  perlboot
-  perlbot
-  perltooc
-  perltoot
-
-aoh Auxiliary Documentation
-
-ao a2p
-ao c2ph
-ao h2ph
-ao h2xs
-ao perlbug
-ao pl2pm
-ao pod2html
-ao pod2man
-ao s2p
-ao splain
-ao xsubpp
diff --git a/pod/buildtoc b/pod/buildtoc
index a8a05ff414..cf17a9a877 100644
--- a/pod/buildtoc
+++ b/pod/buildtoc
@@ -76,9 +76,9 @@ my $roffitall;
 EOPOD2B
 
 # All the things in the master list that happen to be pod filenames
-foreach (grep {defined $_ && @$_ == 5 && !$_->[0]{toc_omit}} @{$state->{master}}) {
-    $roffitall .= "    \$mandir/$_->[4].1 \\\n";
-    podset($_->[4], $_->[2]);
+foreach (grep {!$_->[2]{toc_omit}} @{$state->{master}}) {
+    $roffitall .= "    \$mandir/$_->[0].1 \\\n";
+    podset($_->[0], $_->[1]);
 }
 
 foreach my $type (qw(PRAGMA MODULE)) {
@@ -109,7 +109,7 @@ $_= <<"EOPOD2B";
 
 EOPOD2B
 
-$_ .=  join "\n", map {"\t=item $_\n"} sort keys %{$state->{aux}};
+$_ .=  join "\n", map {"\t=item $_\n"} @{$state->{aux}};
 $_ .= <<"EOPOD2B" ;
 
 	=back
diff --git a/pod/perl.pod b/pod/perl.pod
index 0f136e8b0d..d199d6ee5b 100644
--- a/pod/perl.pod
+++ b/pod/perl.pod
@@ -28,6 +28,24 @@ perldoc> to learn more things you can do with F<perldoc>.
 
 For ease of access, the Perl manual has been split up into several sections.
 
+=begin buildtoc
+
+# This section is parsed by Porting/pod_lib.pl for use by pod/buildtoc etc
+
+flag =g  perluniprops perlmodlib perlapi perlintern
+flag =go perltoc
+flag =ro perlcn perljp perlko perltw
+flag =   perlvms
+
+path perlfaq.*          cpan/perlfaq/lib/
+path perlglossary       cpan/perlfaq/lib/
+path perlxs(?:tut)?     dist/ExtUtils-ParseXS/lib/
+path perldoc            dist/Pod-Perldoc/lib/
+
+aux a2p c2ph h2ph h2xs perlbug pl2pm pod2html pod2man s2p splain xsubpp
+
+=end buildtoc
+
 =head2 Overview
 
     perl		Perl overview (this section)
@@ -198,6 +216,8 @@ For ease of access, the Perl manual has been split up into several sections.
 
 =head2 Language-Specific
 
+=for buildtoc flag +r
+
     perlcn		Perl for Simplified Chinese (in EUC-CN)
     perljp		Perl for Japanese (in EUC-JP)
     perlko		Perl for Korean (in EUC-KR)
@@ -240,6 +260,8 @@ For ease of access, the Perl manual has been split up into several sections.
     perlvos		Perl notes for Stratus VOS
     perlwin32		Perl notes for Windows
 
+=for buildtoc flag -r
+
 =head2 Stubs for Deleted Documents
 
     perlboot		
@@ -247,6 +269,7 @@ For ease of access, the Perl manual has been split up into several sections.
     perltooc		
     perltoot		
 
+=for buildtoc __END__
 
 On a Unix-like system, these documentation files will usually also be
 available as manpages for use with the F<man> program.