Add t/porting/perlfunc.t so that porting tests catch problems with perlfunc

Pod::Functions is now generated from pod/perlfunc.pod by
ext/Pod-Functions/Functions_pm.PL

If it can't parse pod/perlfunc.pod, it will abort, which will cause the
build to break. It's really not possible for it to carry on, hence aborting
is the only option. However, innocent-seeming changes to documentation
shouldn't break the build, and we expect everyone to run (at least)
the porting tests, hence this test, to catch such problems before it's too
late. To avoid duplicating the parsing logic, we make Functions_pm.PL take
a --tap option, to test that all is well.

4 files changed, 47 insertions, 2 deletions

diff --git a/MANIFEST b/MANIFEST
index 659f067a74..1853b5057f 100644
--- a/MANIFEST
+++ b/MANIFEST
@@ -5375,6 +5375,7 @@ t/porting/globvar.t		Check that globvar.sym is sane
 t/porting/known_pod_issues.dat	Data file for porting/podcheck.t
 t/porting/maintainers.t		Test that Porting/Maintainers.pl is up to date
 t/porting/manifest.t		Test that this MANIFEST file is well formed
+t/porting/perlfunc.t		Test that Functions_pm.PL can parse perlfunc.pod
 t/porting/podcheck.t		Test the POD of shipped modules is well formed
 t/porting/pod_rules.t		Check that various pod lists are consistent
 t/porting/regen.t		Check that regen.pl doesn't need running
diff --git a/ext/Pod-Functions/Functions_pm.PL b/ext/Pod-Functions/Functions_pm.PL
index e77a40c7ae..12c788f8d3 100644
--- a/ext/Pod-Functions/Functions_pm.PL
+++ b/ext/Pod-Functions/Functions_pm.PL
@@ -2,6 +2,10 @@
 use strict;
 use Pod::Simple::SimpleTree;
 
+my ($tap, $test);
+
+@ARGV = grep { not($_ eq '--tap' and $tap = 1) } @ARGV;
+
 my (%Kinds, %Flavor, @Types);
 my %Omit;
 
@@ -86,12 +90,22 @@ sub sort_funcs {
                 @_;
 }
 
+if ($tap) {
+    foreach my $func (sort_funcs(keys %Flavor)) {
+	++$test;
+	my $ok = $Type{$func} ? 'ok' : 'not ok';
+	print "$ok $test - $func is mentioned in at least one category group\n";
+    }
+    print "1..$test\n";
+    exit;
+}
+
 # blead will run this with miniperl, hence we can't use autodie
 my $real = 'Functions.pm';
 my $temp = "Functions.$$";
 
 END {
-    return if !-e $temp;
+    return if !defined $temp || !-e $temp;
     unlink $temp or warn "Can't unlink '$temp': $!";
 }
 
diff --git a/pod/perldelta.pod b/pod/perldelta.pod
index 6423d09b03..562bb9abf3 100644
--- a/pod/perldelta.pod
+++ b/pod/perldelta.pod
@@ -427,7 +427,8 @@ L<Version::Requirements> has been upgraded from version 0.101021 to version 0.10
 
 =item *
 
-XXX
+F<t/porting/perlfunc.t> has been added, to test that changes to
+F<pod/perlfunc.pod> do not inadvertently break the build of L<Pod::Functions>.
 
 =back
 
diff --git a/t/porting/perlfunc.t b/t/porting/perlfunc.t
new file mode 100644
index 0000000000..b32e88acdd
--- /dev/null
+++ b/t/porting/perlfunc.t
@@ -0,0 +1,29 @@
+#!./perl -w
+
+# What does this test?
+# This checks that changes to pod/perlfunc.pod don't accidentally break the
+# build by causing ext/Pod-Functions/Functions_pm.PL to abort.
+#
+# Why do we test this?
+# Pod::Functions is generated from pod/perlfunc.pod by
+# ext/Pod-Functions/Functions_pm.PL
+# If it can't parse pod/perlfunc.pod, it will abort, which will cause the
+# build to break. It's really not possible for it to carry on, hence aborting
+# is the only option. However, innocent-seeming changes to documentation
+# shouldn't break the build, and we expect everyone to run (at least)
+# the porting tests, hence this test, to catch such problems before it's too
+# late. To avoid duplicating the parsing logic, we make Functions_pm.PL take
+# a --tap option, to test that all is well.
+#
+# It's broken - how do I fix it?
+# Likely it's because you changed something in pod/perlfunc.pod
+# If you added a new function, it needs to be added to one or more groups in
+# "Perl Functions by Category".
+
+BEGIN {
+    @INC = '..' if -f '../TestInit.pm';
+}
+
+use TestInit qw(T A); # T is chdir to the top level, A makes paths absolute
+
+system "$^X ext/Pod-Functions/Functions_pm.PL --tap pod/perlfunc.pod";