Eliminate pod.lst. pod/perl.pod is now the master file for Pod metadata.
authorNicholas Clark <nick@ccl4.org>
Mon, 19 Dec 2011 13:45:17 +0000 (14:45 +0100)
committerNicholas Clark <nick@ccl4.org>
Wed, 21 Dec 2011 08:07:27 +0000 (09:07 +0100)
perl.pod already contained virtually all the information in pod.lst. Add
the remainder as =begin and =for Pod blocks.

As perl.pod no longer needs to be regenerated, remove the redundant code from
Porting/pod_rules.pl. Update (nearly) all references to pod.lst.

MANIFEST
Porting/bump-perl-version
Porting/new-perldelta.pl
Porting/pod_lib.pl
Porting/pod_rules.pl
Porting/release_managers_guide.pod
README.cygwin
lib/unicore/README.perl
pod.lst [deleted file]
pod/perl.pod

index 9f0b5d1..e535dcd 100644 (file)
--- 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
index a0b8311..b867414 100644 (file)
@@ -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(
index 4fa7fd1..d4fb593 100644 (file)
@@ -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";
 
index 95bea61..1c9b7bb 100644 (file)
@@ -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,70 @@ 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}{$_} = '' foreach @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};
 
             $state{generated}{"$podname.pod"}++ if $flags =~ tr/g//d;
 
@@ -124,23 +160,38 @@ 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;
+
+            if ($podname eq 'perldelta') {
+                local $" = '.';
+                my $delta_desc = "Perl changes in version @want";
+                push @{$state{master}},
+                    [{}, $state{delta_target}, "pod/$state{delta_target}",
+                     $delta_desc, $delta_leaf];
+                $state{pods}{$delta_leaf} = $delta_desc;
+            }
+
         } 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;
+
+    # This "structure" is identical to the array reference generated by the
+    # previous code from pod.lst. It's likely that it can be simplified.
+    push @{$state{master}},
+        [{aux => 1, toc_omit => 1}, $_, "pod/$_.pod", '', $_]
+            foreach sort keys %{$state{aux}}
 }
 
 sub get_pod_metadata {
@@ -161,7 +212,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);
 
@@ -206,18 +257,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 +273,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 +287,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;
 }
index 689219a..8386015 100644 (file)
@@ -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)) {
index 75b0bf3..f13f37d 100644 (file)
@@ -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
 
index abfd996..0888140 100644 (file)
@@ -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
index 1a94d03..2518a60 100644 (file)
@@ -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 (file)
index 9e1a47e..0000000
--- 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
index 0f136e8..d199d6e 100644 (file)
@@ -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.