Clarify use of SOURCE_DATE_EPOCH environment variable. (#421)

See #403.

Signed-off-by: Henry Cox <[email protected]>

Author: henry2cox

bin/genhtml

@@ -5471,12 +5471,19 @@ sub _computeAge
     if ($then > $now) {
         if (lcovutil::warn_once($lcovutil::ERROR_INCONSISTENT_DATA, $path)) {
             # issue annotation warning at most once per file
+	    # also attempt to clarify where the date comes from
             my $data =
                 exists($ENV{SOURCE_DATE_EPOCH}) ?
-                "'SOURCE_DATE_EPOCH=$ENV{SOURCE_DATE_EPOCH}'" :
+                (
+                lcovutil::warn_once($lcovutil::ERROR_INCONSISTENT_DATA,
+                                    'SOURCE_DATE_EPOCH') ?
+                    "computed from your 'SOURCE_DATE_EPOCH=$ENV{SOURCE_DATE_EPOCH}' environment variable - see 'man genhtml'"
+                :
+                    "'SOURCE_DATE_EPOCH=$ENV{SOURCE_DATE_EPOCH}'") :
                 "'now'";
+
             lcovutil::ignorable_error($lcovutil::ERROR_INCONSISTENT_DATA,
-                "File \"$path\": $data ($now) is older than annotate time '$when'"
+                "File \"$path\": '$now' ($data) is older than annotate time '$when'"
             );
         }
         return 0;

man/genhtml.1

@@ -1947,7 +1947,8 @@ The
 .B \-\-date\-bins
 option is used to specify age boundaries (cutpoints) for date\-binning classification.  Each
 .I age
-element is expected to be an integer number of days prior to today (or SOURCE_DATE_EPOCH, if specified).  If not specified, the default is to use 4 age ranges: less than 7 days, 7 to 30 days, 30 to 180 days, and more than 180 days.
+element is expected to be an integer number of days prior to today (or prior to your SOURCE_DATE_EPOCH environment variable, if set).  If
+.I \-\-date\-bins is not specified, the default is to use 4 age ranges: less than 7 days, 7 to 30 days, 30 to 180 days, and more than 180 days.
 This option is equivalent to the
 .I genhtml_date_bins
 config file option.  See man