P/manifest_lib.pl - tweak MANIFEST sort order, better description indent

This patch ensures that all files in a common sub-directory or
preferably sub-directory pair will have their descriptions "indented"
to the same level. Eg, all files in cpan/Foo should have the
description line up.

I did some analysis and something like 95% of our files are less than
40 characters.  So short files mostly have their descriptions start
on column 40, with the caveat that if they are in a subdirectory

This also changes the sort order so files at the top level of the
repo, which are mostly C files, are sorted together, and not with
things in cpan/ dist/ or ext/, which are grouped separately.

It has been pointed out that the format for MANIFEST differs from
that used by ExtUtils::Manifest, and that maybe we should migrate.
That would allow us to use normal spaces as separators instead of tabs,
and be more fine grained about how we line up the files. IMO this
is a good idea, but out of scope for this patch.

This patch includes an application of the new logic to MANIFEST.

1 files changed, 62 insertions, 4 deletions

diff --git a/Porting/manifest_lib.pl b/Porting/manifest_lib.pl
index 95d49be9cd..555804836e 100644
--- a/Porting/manifest_lib.pl
+++ b/Porting/manifest_lib.pl
@@ -1,6 +1,8 @@
 #!/usr/bin/perl
 
 use strict;
+use warnings;
+use Text::Tabs qw(expand unexpand);
 
 =head1 NAME
 
@@ -27,16 +29,70 @@ listed sorted appropriately.
 # and so that lib/Foo/Bar.pm sorts before lib/Foo/Bar/Alpha.pm
 # and so that configure and Configure sort together.
 sub sort_manifest {
-    return
+    my @lines = @_;
+
+    # first we ensure that the descriptions for the files
+    # are lined up reasonably.
+    my %pfx_len;
+    my @line_tuples;
+    foreach my $idx (0 .. $#lines) {
+        my $line = $lines[$idx];
+        $line =~ s/\t +/\t/;
+        $line =~ /^(\S+)(?:\t+([^\t]*))?\z/
+            or do {
+                $line =~ s/\t/\\t/g;
+                die "Malformed content in MANIFEST at line $idx: '$line'\n",
+                    "Note: tabs have been encoded as \\t in this message.\n";
+            };
+        my ($file, $descr) = ($1, $2);
+        my $pfx;
+        if ($file =~ m!^((?:[^/]+/){1,2})!) {
+            $pfx = $1;
+        } else {
+            $pfx = "";
+        }
+        #print "'$pfx': $file\n";
+        push @line_tuples, [$pfx, $file, $descr];
+        $pfx_len{$pfx} //= 40;
+
+        # ensure we have at least one "space" (really tab)
+        my $flen = 1 + length $file;
+        $pfx_len{$pfx} = $flen
+            if $pfx_len{$pfx} < $flen;
+    }
+
+    # round up to the next tab stop
+    $_ % 8 and $_ += (8 - ($_ % 8)) for values %pfx_len;
+
+    my @pretty_lines;
+    foreach my $tuple (@line_tuples) {
+        my ($pfx, $file, $descr) = @$tuple;
+        my $str = sprintf "%*s", -$pfx_len{$pfx}, $file;
+        ($str) = unexpand($str);
+        # I do not understand why this is necessary. Bug in unexpand()?
+        # See https://github.com/ap/Text-Tabs/issues/5
+        $str =~ s/[ ]+/\t/;
+        if ($descr) {
+            $str =~ s/\t?\z/\t/;
+            $str .= $descr;
+        }
+        $str =~ s/\s+\z//;
+        push @pretty_lines, $str;
+    }
+
+    @pretty_lines =
     # case insensitive sorting of directory components independently.
     map { $_->[0] } # extract the full line
     sort {
+        $a->[2] cmp $b->[2] || # sort by the first directory
         $a->[1] cmp $b->[1] || # sort in order of munged filename
         $a->[0] cmp $b->[0]    # then by the exact text in full line
     }
     map {
         # split out the filename and the description
         my ($f) = split /\s+/, $_, 2;
+        # extract out the first directory
+        my $d = $f=~m!^(\w+/)! ? lc $1 : "";
         # lc the filename so Configure and configure sort together in the list
         my $m= lc $f; # $m for munged
         # replace slashes by nulls, this makes short directory names sort before
@@ -46,9 +102,11 @@ sub sort_manifest {
         # this puts any foo/blah.ext before any files in foo/blah/
         $m =~ s{(?<!\A)(\.[^.]+\z)}{\0\0$1};
 
-        # return the original string, and the munged filename
-        [ $_, $m ];
-    } @_;
+        # return the original string, and the munged filename, and root dir
+        [ $_, $m, $d ];
+    } @pretty_lines;
+
+    return @pretty_lines;
 }
 
 1;