From 9057adc106d6bbef53c9e706523cd94f1a7a08d4 Mon Sep 17 00:00:00 2001
From: Russ Allbery <rra@debian.org>
Date: Sat, 30 Aug 2014 15:10:41 -0700
Subject: Support POD_MAN_DATE in Pod::Man for the left-hand footer

Honor the environment variable POD_MAN_DATE and use its contents, if
set, as the value of the left-hand footer if the date option is not
set, overriding the timestamp of the input file.  This is primarily
useful to ensure reproducible builds of the same output file given the
same souce and Pod::Man version, even when file timestamps may not be
consistent.  Thanks, Niko Tyni.

Bug-Debian: http://bugs.debian.org/759405
Origin: upstream
Patch-Name: fixes/pod_man_reproducible_date.diff
---
 cpan/podlators/lib/Pod/Man.pm  | 69 +++++++++++++++++++++++++++++++-----------
 cpan/podlators/t/devise-date.t | 29 +++++++++++++-----
 2 files changed, 72 insertions(+), 26 deletions(-)

diff --git a/cpan/podlators/lib/Pod/Man.pm b/cpan/podlators/lib/Pod/Man.pm
index 72ca9ff..0536662 100644
--- a/cpan/podlators/lib/Pod/Man.pm
+++ b/cpan/podlators/lib/Pod/Man.pm
@@ -876,25 +876,42 @@ sub devise_title {
 }
 
 # Determine the modification date and return that, properly formatted in ISO
-# format.  If we can't get the modification date of the input, instead use the
-# current time.  Pod::Simple returns a completely unuseful stringified file
-# handle as the source_filename for input from a file handle, so we have to
-# deal with that as well.
+# format.
+#
+# If POD_MAN_DATE is set, that overrides anything else.  This can be used for
+# reproducible generation of the same file even if the input file timestamps
+# are unpredictable or the POD coms from standard input.
+#
+# Otherwise, use the modification date of the input if we can stat it.  Be
+# aware that Pod::Simple returns the stringification of the file handle as
+# source_filename for input from a file handle, so we'll stat some random ref
+# string in that case.  If that fails, instead use the current time.
+#
+# $self - Pod::Man object, used to get the source file
+#
+# Returns: YYYY-MM-DD date suitable for the left-hand footer
 sub devise_date {
     my ($self) = @_;
+
+    # If POD_MAN_DATE is set, always use it.
+    if ($ENV{POD_MAN_DATE}) {
+        return $ENV{POD_MAN_DATE};
+    }
+
+    # Otherwise, get the input filename and try to stat it.  If that fails,
+    # use the current time.
     my $input = $self->source_filename;
     my $time;
     if ($input) {
-        $time = (stat $input)[9] || time;
+        $time = (stat($input))[9] || time();
     } else {
-        $time = time;
+        $time = time();
     }
 
-    # Can't use POSIX::strftime(), which uses Fcntl, because MakeMaker
-    # uses this and it has to work in the core which can't load dynamic
-    # libraries.
-    my ($year, $month, $day) = (localtime $time)[5,4,3];
-    return sprintf ("%04d-%02d-%02d", $year + 1900, $month + 1, $day);
+    # Can't use POSIX::strftime(), which uses Fcntl, because MakeMaker uses
+    # this and it has to work in the core which can't load dynamic libraries.
+    my ($year, $month, $day) = (localtime($time))[5,4,3];
+    return sprintf("%04d-%02d-%02d", $year + 1900, $month + 1, $day);
 }
 
 # Print out the preamble and the title.  The meaning of the arguments to .TH
@@ -1632,6 +1649,15 @@ argument.
 Sets the centered page header to use instead of "User Contributed Perl
 Documentation".
 
+=item date
+
+Sets the left-hand footer.  If this option is not set, the contents of the
+environment variable POD_MAN_DATE, if set, will be used.  Failing that,
+the modification date of the input file will be used, or the current time
+if stat() can't find that file (which will be the case if the input is
+from C<STDIN>).  If obtained from the file modification date or the
+current time, he date will be formatted as C<YYYY-MM-DD>.
+
 =item errors
 
 How to report errors.  C<die> says to throw an exception on any POD
@@ -1642,13 +1668,6 @@ POD errors entirely, as much as possible.
 
 The default is C<pod>.
 
-=item date
-
-Sets the left-hand footer.  By default, the modification date of the input
-file will be used, or the current date if stat() can't find that file (the
-case if the input is from C<STDIN>), and the date will be formatted as
-C<YYYY-MM-DD>.
-
 =item fixed
 
 The fixed-width font to use for verbatim text and code.  Defaults to
@@ -1810,6 +1829,20 @@ option was set to C<die>.
 
 =back
 
+=head1 ENVIRONMENT
+
+=over 4
+
+=item POD_MAN_DATE
+
+If set, this will be used as the value of the left-hand footer unless the
+C<date> option is explicitly set, overriding the timestamp of the input
+file or the current time.  This is primarily useful to ensure reproducible
+builds of the same output file given the same souce and Pod::Man version,
+even when file timestamps may not be consistent.
+
+=back
+
 =head1 BUGS
 
 Encoding handling assumes that PerlIO is available and does not work
diff --git a/cpan/podlators/t/devise-date.t b/cpan/podlators/t/devise-date.t
index 3cce9f5..c610dd9 100644
--- a/cpan/podlators/t/devise-date.t
+++ b/cpan/podlators/t/devise-date.t
@@ -1,15 +1,28 @@
-#!/usr/bin/perl -w
-
-# In order for MakeMaker to build in the core, nothing can use
-# Fcntl which includes POSIX.  devise_date()'s use of strftime()
-# was replaced.  This tests that it's identical.
+#!/usr/bin/perl
+#
+# In order for MakeMaker to build in the core, nothing can use Fcntl which
+# includes POSIX.  devise_date()'s use of strftime() was replaced.  This tests
+# that it's identical.  It also tests special handling of the POD_MAN_DATE
+# environment variable.
 
+use 5.006;
 use strict;
-
-use Test::More tests => 1;
+use warnings;
 
 use Pod::Man;
 use POSIX qw(strftime);
 
+use Test::More tests => 2;
+
+# Check that the results of device_date matches strftime.  There is no input
+# file name, so this will use the current time.
 my $parser = Pod::Man->new;
-is $parser->devise_date, strftime("%Y-%m-%d", localtime);
+is(
+    $parser->devise_date,
+    strftime('%Y-%m-%d', localtime()),
+    'devise_date matches strftime'
+);
+
+# Set the override environment variable and ensure that it's honored.
+local $ENV{POD_MAN_DATE} = '2014-01-01';
+is($parser->devise_date, '2014-01-01', 'devise_date honors POD_MAN_DATE');