1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
|
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
Upstream-Status: Pending
---
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');
|
