From ae9a340dc2f2bac96bfaad47c28d5af57fa6dc82 Mon Sep 17 00:00:00 2001
From: Dennis Kaarsemaker <dennis@kaarsemaker.net>
Date: Mon, 11 Mar 2013 00:31:44 +0100
Subject: [PATCH] t/porting/readme.t: Check Porting/README.pod consistency

All files in Porting/ should be mentioned in its README.pod and vice
versa.
---
 t/porting/readme.t | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)
 create mode 100644 t/porting/readme.t

diff --git a/t/porting/readme.t b/t/porting/readme.t
new file mode 100644
index 0000000..8949f67
--- /dev/null
+++ b/t/porting/readme.t
@@ -0,0 +1,35 @@
+#!./perl -w
+#
+# Check whether all files mentioned in Porting/README.pod exist in Porting and
+# vice versa.
+
+BEGIN {
+    chdir 't' if -d 't';
+    @INC = qw(. ../lib);
+    require 'test.pl';
+}
+
+use strict;
+use Data::Dumper;
+plan('no_plan');
+
+my %files_in_pod;
+
+open(my $fh, '<', '../Porting/README.pod') or die("Can't open Porting/README.pod: $!");
+
+while(<$fh>) {
+    next unless $_ =~ /^=head/;
+    my @matches = $_ =~ m/F<([^>]+)>/g;
+    for my $file (@matches) {
+        $files_in_pod{$file} = 1;
+    }
+}
+for my $file (glob("../Porting/*")) {
+    $file =~ s!^../Porting/!!;
+    next if $file =~ /^(perl[0-9]+delta|README)\.pod$/;
+    ok(exists($files_in_pod{$file}), "$file is mentioned in Porting/README.pod");
+    delete $files_in_pod{$file};
+}
+for my $file (keys %files_in_pod) {
+    ok(0, "$file exists in Porting/");
+}
-- 
1.8.1.5.4.g84d0fe6

From 3834d52b9860b869ee05d6a6676b35117c439afe Mon Sep 17 00:00:00 2001
From: Brian Gottreu <gottreu@gmail.com>
Date: Wed, 26 Jun 2013 19:39:25 -0500
Subject: [PATCH 1/2] t/porting/readme.t: Check Porting/README.pod consistency
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="------------1.7.10.4"

This is a multi-part message in MIME format.
--------------1.7.10.4
Content-Type: text/plain; charset=UTF-8; format=fixed
Content-Transfer-Encoding: 8bit


This is a slightly expanded (or bloated) version of the patch
Dennis Kaarsemaker <dennis@kaarsemaker.net> submitted.
---
 t/porting/readme.t |   75 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 75 insertions(+)
 create mode 100644 t/porting/readme.t


--------------1.7.10.4
Content-Type: text/x-patch; name="0001-t-porting-readme.t-Check-Porting-README.pod-consiste.patch"
Content-Transfer-Encoding: 8bit
Content-Disposition: attachment; filename="0001-t-porting-readme.t-Check-Porting-README.pod-consiste.patch"

diff --git a/t/porting/readme.t b/t/porting/readme.t
new file mode 100644
index 0000000..505e1e3
--- /dev/null
+++ b/t/porting/readme.t
@@ -0,0 +1,75 @@
+#!./perl -w
+#
+# Check whether all files mentioned in Porting/README.pod exist in Porting and
+# vice versa.
+
+BEGIN {
+    @INC = '..' if -f '../TestInit.pm';
+}
+
+use TestInit qw(T); # T is chdir to the top level
+use strict;
+use warnings;
+require 't/test.pl';
+
+open(my $fh, '<', 'Porting/README.pod') or die("Can't open Porting/README.pod: $!");
+
+my @porting_files = glob("Porting/*");
+# It seems that dying here is nicer than having several dozen failing tests
+# later.  But that assumes one will see the message from die.
+die "Can't get contents of Porting/ directory.\n" unless @porting_files > 1;
+
+my (@current_order, @sorted_order, %files_in_pod);
+while(<$fh>) {
+    next unless $_ =~ /^=head/;
+    my @matches = $_ =~ m/F<([^>]+)>/g;
+    for my $file (@matches) {
+        $files_in_pod{$file} = 1;
+        push @current_order, $file;
+    }
+}
+
+for my $file (@porting_files) {
+    $file =~ s!^Porting/!!;
+    next if $file =~ /^perl[0-9]+delta\.pod$/;
+    ok(exists($files_in_pod{$file}), "$file is mentioned in Porting/README.pod");
+    delete $files_in_pod{$file};
+}
+for my $file (keys %files_in_pod) {
+    fail("$file exists in Porting/");
+}
+
+# Check if the entries in the README are in some sort of order.
+eval {
+    require Unicode::Collate;
+    my $Collator = Unicode::Collate->new();
+    @sorted_order = $Collator->sort(@current_order);
+};
+
+if(@sorted_order) {
+    ok(eq_array(\@current_order, \@sorted_order), "Files are referenced in order") or
+        print_right_order();
+}
+else {
+    note('Unicode collation did not work.  Not checking order of entries.');
+}
+
+# Frankly this is a bit much for a porting test, but it exists now.
+sub print_right_order {
+    my $max = 0;
+    for(@current_order) {
+        my $l = length $_;
+        $max = $l if $l > $max;
+    }
+    $max = 36 if $max > 36;
+    note(sprintf " N   %-${max}s %-${max}s\n", "Correct", "Current");
+    for(0..$#current_order) {
+        my $wrong = $sorted_order[$_] eq $current_order[$_] ? '' : 'X';
+        my $line = sprintf "%2d %1s %-${max}s %-${max}s\n",
+            $_, $wrong, $sorted_order[$_], $current_order[$_];
+        $line =~ s{ ((?:  ){2,})}{" " . ". " x (length($1)/2)}e if $_&1;
+        note($line);
+    }
+}
+
+done_testing();

--------------1.7.10.4--

From 15bb1964c909ac25a19cda7c7f39b22f96da81d1 Mon Sep 17 00:00:00 2001
From: Brian Gottreu <gottreu@gmail.com>
Date: Wed, 26 Jun 2013 19:44:34 -0500
Subject: [PATCH 2/2] Fix Porting/README.pod so it passes its new test.
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="------------1.7.10.4"

This is a multi-part message in MIME format.
--------------1.7.10.4
Content-Type: text/plain; charset=UTF-8; format=fixed
Content-Transfer-Encoding: 8bit


Added entries for sync-with-cpan and README.pod itself.  Rearranged
entries to be sorted consistently.
---
 Porting/README.pod |   89 ++++++++++++++++++++++++++++------------------------
 1 file changed, 48 insertions(+), 41 deletions(-)


--------------1.7.10.4
Content-Type: text/x-patch; name="0002-Fix-Porting-README.pod-so-it-passes-its-new-test.patch"
Content-Transfer-Encoding: 8bit
Content-Disposition: attachment; filename="0002-Fix-Porting-README.pod-so-it-passes-its-new-test.patch"

diff --git a/Porting/README.pod b/Porting/README.pod
index 695e7ed..e77c80d 100644
--- a/Porting/README.pod
+++ b/Porting/README.pod
@@ -16,7 +16,7 @@ text.
 Program to prepare dual-life distributions for insertion into the Perl 5
 F<lib/> and F<t/> directories.  Now thought to be largely superseded.
 
-=head2 F<bisect-example.sh>, F<bisect-runner.pl> and F<bisect.pl>
+=head2 F<bisect-example.sh>, F<bisect.pl> and F<bisect-runner.pl>
 
 Use C<git bisect> to pinpoint changes.
 
@@ -30,23 +30,14 @@ number in various files within the perl source.
 Performs pathname portability checks, including whether there are naming
 conflicts when names are truncated to the DOSish, case-ignoring 8.3 format.
 
-=head2 F<checkAUTHORS.pl>
-
-Used by F<t/porting/authors.t> to ensure the F<AUTHORS> list is up to date.
-
-=head2 F<checkURL.pl>
-
-Checks that all the URLs in the Perl source are valid.
-
-=head2 F<checkVERSION.pl>
-
-Used by F<t/porting/cmp_version.t> to ensure changed modules have had their
-versions updated.
-
 =head2 F<checkansi.pl>
 
 Check source code for ANSI-C violations.
 
+=head2 F<checkAUTHORS.pl>
+
+Used by F<t/porting/authors.t> to ensure the F<AUTHORS> list is up to date.
+
 =head2 F<checkcfgvar.pl>
 
 Check that the various F<config.sh>-clones have (at least) all the same
@@ -69,6 +60,15 @@ F<MANIFEST>).
 Check if POD files contain non-ASCII without specifying
 encoding. Run it as: C<perl Porting/checkpodencoding.pl>.
 
+=head2 F<checkURL.pl>
+
+Checks that all the URLs in the Perl source are valid.
+
+=head2 F<checkVERSION.pl>
+
+Used by F<t/porting/cmp_version.t> to ensure changed modules have had their
+versions updated.
+
 =head2 F<cherrymaint>
 
 Command line tool to update cherrymaint; a tool for selecting commits from 
@@ -114,16 +114,16 @@ same version than the corresponding module on CPAN.
 Prints a table of differences between two Perl versions with respect to
 modules included in the distribution.
 
-=head2 F<corelist.pl>
-
-Generates info for Module::CoreList from this perl tree.
-
 =head2 F<corelist-perldelta.pl>
 
 Generates a list of the module changes for the Perl you are currently
 building.  Also generates a diff between the corelist sections of two
 F<perldelta*> files.
 
+=head2 F<corelist.pl>
+
+Generates info for Module::CoreList from this perl tree.
+
 =head2 F<epigraphs.pod>
 
 List of Perl release epigraphs.
@@ -146,13 +146,6 @@ Expand C macros using the C preprocessor.
 This script finds reentrant variants of functions used in an executable and
 shared objects.
 
-=head2 F<GitUtils.pm>
-
-This script contains the subroutine to generate a F<.patch file> for a
-committish (the SHA1 checksum of a commit, a number made of 40 hexadecimal
-digits which acts the internal unique identifier for this commit
-(lilypond.org).  Related file: F<make_dot_patch.pl>
-
 =head2 F<git-deltatool>
 
 This script, a rough draft, aids in generating a perldelta file
@@ -167,6 +160,13 @@ id.
 
 This script creates a tag for every p4raw-id.
 
+=head2 F<GitUtils.pm>
+
+This script contains the subroutine to generate a F<.patch file> for a
+committish (the SHA1 checksum of a commit, a number made of 40 hexadecimal
+digits which acts the internal unique identifier for this commit
+(lilypond.org).  Related file: F<make_dot_patch.pl>
+
 =head2 F<Glossary>
 
 This file is built by F<metaconfig>. This file contains a description of all
@@ -201,31 +201,31 @@ F<Maintainers>, F<Maintainers.pm>
 A package to search and show information about which core files/modules are
 associated with maintainers.  Related files: F<Maintainers>, F<Maintainers.pl>
 
-=head2 F<make-rmg-checklist>
-
-This script creates a release checklist as a simple HTML document.
-
 =head2 F<make_dot_patch.pl>
 
 Generate a F<.patch> file to STDOUT for a commit ID specified on the
 command-line.
 
+=head2 F<makemeta>
+
+This script creates F<META.yml> and F<META.json> files.
+
 =head2 F<make_modlib_cpan.pl>
 
 This script generates the list of registered CPAN sites in F<perlmodlib.PL>.
 
-=head2 F<make_snapshot.pl>
+=head2 F<makerel>
 
-This script is a quick and dirty snapshot generator for the perl5.git.perl.org
-web page to use to generate the snapshot files. 
+This script builds a Perl release tarball.
 
-=head2 F<makemeta>
+=head2 F<make-rmg-checklist>
 
-This script creates F<META.yml> and F<META.json> files.
+This script creates a release checklist as a simple HTML document.
 
-=head2 F<makerel>
+=head2 F<make_snapshot.pl>
 
-This script builds a Perl release tarball.
+This script is a quick and dirty snapshot generator for the perl5.git.perl.org
+web page to use to generate the snapshot files. 
 
 =head2 F<manicheck>
 
@@ -279,6 +279,13 @@ Pumpkin - Notes on handling the Perl Patch Pumpkin And Porting Perl.
 Many of these are out of date or superseded by other documents in 
 this directory.
 
+=head2 F<README.pod>
+
+This file.  An exhaustive list of the contents of the F<Porting/>
+directory along with a description of each file.
+The test F<t/porting/readme.t> ensures that this lists every file
+and that every file is listed.
+
 =head2 F<README.y2038>
 
 The y2038 implementation for perl. This is an implementation of POSIX time.h
@@ -312,6 +319,10 @@ This is a script for sorting the warning and error messages in
 F<perldiag.pod>.  POD formatting, printf-style escapes, non-letter characters,
 and case are ignored, as explained in L<perldiag>.
 
+=head2 F<sync-with-cpan>
+
+Script to help out with syncing cpan distros.
+
 =head2 F<testall.atom>
 
 Test suite profiling on Tru 64.
@@ -321,10 +332,6 @@ Test suite profiling on Tru 64.
 Script for cleaning out the "known noise" from Third Degree reports: either
 noise caused by F<libc> itself, or F<Perl_yyparse> leaks.
 
-=head2 F<time>
-
-A helper tool for perl's 2038 support. See F<Porting/README.y2038> for details.
-
 =head2 F<timecheck2.c>
 
 A little program to test the limits of your system's time functions. See
@@ -340,7 +347,7 @@ This is a list of wishes for Perl. The most up-to-date version of this file is
 at L<http://perl5.git.perl.org/perl.git/blob_plain/HEAD:/Porting/todo.pod>.
 The tasks we think are smaller or easier are listed first.  Anyone is welcome
 to work on any of these, but it's a good idea to first contact
-F<perl5-porters@perl.org> to avoid duplication of effort, and to learn from
+I<perl5-porters@perl.org> to avoid duplication of effort, and to learn from
 any previous attempts.
 
 =head2 F<valgrindpp.pl>

--------------1.7.10.4--

From 8504db9a91fbfa54c6a03fc4bdccc2b4ace9fa32 Mon Sep 17 00:00:00 2001
From: Brian Gottreu <gottreu@gmail.com>
Date: Wed, 26 Jun 2013 22:11:17 -0500
Subject: [PATCH] MANIFEST: add t/porting/readme.t

---
 MANIFEST |    1 +
 1 file changed, 1 insertion(+)

diff --git a/MANIFEST b/MANIFEST
index c4ff4f1..63274db 100644
--- a/MANIFEST
+++ b/MANIFEST
@@ -5279,6 +5279,7 @@ t/porting/pending-author.t	Check if any pending commit would break tests
 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/readme.t		Check that all files in Porting/ are mentioned in Porting/README.pod
 t/porting/regen.t		Check that regen.pl doesn't need running
 t/porting/test_bootstrap.t	Test that the instructions for test bootstrapping aren't accidentally overlooked.
 t/porting/utils.t		Check that utility scripts still compile
-- 
1.7.10.4