Patrick Williams | c124f4f | 2015-09-15 14:41:29 -0500 | [diff] [blame] | 1 | From 9057adc106d6bbef53c9e706523cd94f1a7a08d4 Mon Sep 17 00:00:00 2001 |
| 2 | From: Russ Allbery <rra@debian.org> |
| 3 | Date: Sat, 30 Aug 2014 15:10:41 -0700 |
| 4 | Subject: Support POD_MAN_DATE in Pod::Man for the left-hand footer |
| 5 | |
| 6 | Honor the environment variable POD_MAN_DATE and use its contents, if |
| 7 | set, as the value of the left-hand footer if the date option is not |
| 8 | set, overriding the timestamp of the input file. This is primarily |
| 9 | useful to ensure reproducible builds of the same output file given the |
| 10 | same souce and Pod::Man version, even when file timestamps may not be |
| 11 | consistent. Thanks, Niko Tyni. |
| 12 | |
| 13 | Bug-Debian: http://bugs.debian.org/759405 |
| 14 | Origin: upstream |
| 15 | Patch-Name: fixes/pod_man_reproducible_date.diff |
| 16 | --- |
| 17 | cpan/podlators/lib/Pod/Man.pm | 69 +++++++++++++++++++++++++++++++----------- |
| 18 | cpan/podlators/t/devise-date.t | 29 +++++++++++++----- |
| 19 | 2 files changed, 72 insertions(+), 26 deletions(-) |
| 20 | |
| 21 | diff --git a/cpan/podlators/lib/Pod/Man.pm b/cpan/podlators/lib/Pod/Man.pm |
| 22 | index 72ca9ff..0536662 100644 |
| 23 | --- a/cpan/podlators/lib/Pod/Man.pm |
| 24 | +++ b/cpan/podlators/lib/Pod/Man.pm |
| 25 | @@ -876,25 +876,42 @@ sub devise_title { |
| 26 | } |
| 27 | |
| 28 | # Determine the modification date and return that, properly formatted in ISO |
| 29 | -# format. If we can't get the modification date of the input, instead use the |
| 30 | -# current time. Pod::Simple returns a completely unuseful stringified file |
| 31 | -# handle as the source_filename for input from a file handle, so we have to |
| 32 | -# deal with that as well. |
| 33 | +# format. |
| 34 | +# |
| 35 | +# If POD_MAN_DATE is set, that overrides anything else. This can be used for |
| 36 | +# reproducible generation of the same file even if the input file timestamps |
| 37 | +# are unpredictable or the POD coms from standard input. |
| 38 | +# |
| 39 | +# Otherwise, use the modification date of the input if we can stat it. Be |
| 40 | +# aware that Pod::Simple returns the stringification of the file handle as |
| 41 | +# source_filename for input from a file handle, so we'll stat some random ref |
| 42 | +# string in that case. If that fails, instead use the current time. |
| 43 | +# |
| 44 | +# $self - Pod::Man object, used to get the source file |
| 45 | +# |
| 46 | +# Returns: YYYY-MM-DD date suitable for the left-hand footer |
| 47 | sub devise_date { |
| 48 | my ($self) = @_; |
| 49 | + |
| 50 | + # If POD_MAN_DATE is set, always use it. |
| 51 | + if ($ENV{POD_MAN_DATE}) { |
| 52 | + return $ENV{POD_MAN_DATE}; |
| 53 | + } |
| 54 | + |
| 55 | + # Otherwise, get the input filename and try to stat it. If that fails, |
| 56 | + # use the current time. |
| 57 | my $input = $self->source_filename; |
| 58 | my $time; |
| 59 | if ($input) { |
| 60 | - $time = (stat $input)[9] || time; |
| 61 | + $time = (stat($input))[9] || time(); |
| 62 | } else { |
| 63 | - $time = time; |
| 64 | + $time = time(); |
| 65 | } |
| 66 | |
| 67 | - # Can't use POSIX::strftime(), which uses Fcntl, because MakeMaker |
| 68 | - # uses this and it has to work in the core which can't load dynamic |
| 69 | - # libraries. |
| 70 | - my ($year, $month, $day) = (localtime $time)[5,4,3]; |
| 71 | - return sprintf ("%04d-%02d-%02d", $year + 1900, $month + 1, $day); |
| 72 | + # Can't use POSIX::strftime(), which uses Fcntl, because MakeMaker uses |
| 73 | + # this and it has to work in the core which can't load dynamic libraries. |
| 74 | + my ($year, $month, $day) = (localtime($time))[5,4,3]; |
| 75 | + return sprintf("%04d-%02d-%02d", $year + 1900, $month + 1, $day); |
| 76 | } |
| 77 | |
| 78 | # Print out the preamble and the title. The meaning of the arguments to .TH |
| 79 | @@ -1632,6 +1649,15 @@ argument. |
| 80 | Sets the centered page header to use instead of "User Contributed Perl |
| 81 | Documentation". |
| 82 | |
| 83 | +=item date |
| 84 | + |
| 85 | +Sets the left-hand footer. If this option is not set, the contents of the |
| 86 | +environment variable POD_MAN_DATE, if set, will be used. Failing that, |
| 87 | +the modification date of the input file will be used, or the current time |
| 88 | +if stat() can't find that file (which will be the case if the input is |
| 89 | +from C<STDIN>). If obtained from the file modification date or the |
| 90 | +current time, he date will be formatted as C<YYYY-MM-DD>. |
| 91 | + |
| 92 | =item errors |
| 93 | |
| 94 | How to report errors. C<die> says to throw an exception on any POD |
| 95 | @@ -1642,13 +1668,6 @@ POD errors entirely, as much as possible. |
| 96 | |
| 97 | The default is C<pod>. |
| 98 | |
| 99 | -=item date |
| 100 | - |
| 101 | -Sets the left-hand footer. By default, the modification date of the input |
| 102 | -file will be used, or the current date if stat() can't find that file (the |
| 103 | -case if the input is from C<STDIN>), and the date will be formatted as |
| 104 | -C<YYYY-MM-DD>. |
| 105 | - |
| 106 | =item fixed |
| 107 | |
| 108 | The fixed-width font to use for verbatim text and code. Defaults to |
| 109 | @@ -1810,6 +1829,20 @@ option was set to C<die>. |
| 110 | |
| 111 | =back |
| 112 | |
| 113 | +=head1 ENVIRONMENT |
| 114 | + |
| 115 | +=over 4 |
| 116 | + |
| 117 | +=item POD_MAN_DATE |
| 118 | + |
| 119 | +If set, this will be used as the value of the left-hand footer unless the |
| 120 | +C<date> option is explicitly set, overriding the timestamp of the input |
| 121 | +file or the current time. This is primarily useful to ensure reproducible |
| 122 | +builds of the same output file given the same souce and Pod::Man version, |
| 123 | +even when file timestamps may not be consistent. |
| 124 | + |
| 125 | +=back |
| 126 | + |
| 127 | =head1 BUGS |
| 128 | |
| 129 | Encoding handling assumes that PerlIO is available and does not work |
| 130 | diff --git a/cpan/podlators/t/devise-date.t b/cpan/podlators/t/devise-date.t |
| 131 | index 3cce9f5..c610dd9 100644 |
| 132 | --- a/cpan/podlators/t/devise-date.t |
| 133 | +++ b/cpan/podlators/t/devise-date.t |
| 134 | @@ -1,15 +1,28 @@ |
| 135 | -#!/usr/bin/perl -w |
| 136 | - |
| 137 | -# In order for MakeMaker to build in the core, nothing can use |
| 138 | -# Fcntl which includes POSIX. devise_date()'s use of strftime() |
| 139 | -# was replaced. This tests that it's identical. |
| 140 | +#!/usr/bin/perl |
| 141 | +# |
| 142 | +# In order for MakeMaker to build in the core, nothing can use Fcntl which |
| 143 | +# includes POSIX. devise_date()'s use of strftime() was replaced. This tests |
| 144 | +# that it's identical. It also tests special handling of the POD_MAN_DATE |
| 145 | +# environment variable. |
| 146 | |
| 147 | +use 5.006; |
| 148 | use strict; |
| 149 | - |
| 150 | -use Test::More tests => 1; |
| 151 | +use warnings; |
| 152 | |
| 153 | use Pod::Man; |
| 154 | use POSIX qw(strftime); |
| 155 | |
| 156 | +use Test::More tests => 2; |
| 157 | + |
| 158 | +# Check that the results of device_date matches strftime. There is no input |
| 159 | +# file name, so this will use the current time. |
| 160 | my $parser = Pod::Man->new; |
| 161 | -is $parser->devise_date, strftime("%Y-%m-%d", localtime); |
| 162 | +is( |
| 163 | + $parser->devise_date, |
| 164 | + strftime('%Y-%m-%d', localtime()), |
| 165 | + 'devise_date matches strftime' |
| 166 | +); |
| 167 | + |
| 168 | +# Set the override environment variable and ensure that it's honored. |
| 169 | +local $ENV{POD_MAN_DATE} = '2014-01-01'; |
| 170 | +is($parser->devise_date, '2014-01-01', 'devise_date honors POD_MAN_DATE'); |