[groff] 04/05: Document use of SOURCE_DATE_EPOCH and TZ.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 7cf56b8eea7d66d36f3a8c910e13e3be74e48324
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sun Jan 3 17:28:01 2021 +1100

    Document use of SOURCE_DATE_EPOCH and TZ.
    
    The semantics of SOURCE_DATE_EPOCH to groff were not established with
    respect to time zone selection, prompting divergent interpretations;
    Debian and distributions derived from it have for several years patched
    groff to implicitly use UTC as the time zone when interpreting the
    current time (or SOURCE_DATE_EPOCH) as a local time.  While a convenient
    and defensible choice for reproducible build efforts[1], it runs against
    the grain of user expectations.  Systems programmers like monotonically
    increasing clocks; the broader user base usually prefers a clock that
    follows an applicable civil calendar.  To the latter audience, a
    difference between
      $ date "+%Y-%M-%d %H:%m:%S"
    and
      $ groff <<EOF
      .af year 0000
      .af mo 00
      .af dy 00
      .af hours 00
      .af minutes 00
      .af seconds 00
      .tm \n[year]-\n[mo]-\n[dy] \n[hours]:\n[minutes]:\n[seconds]
      EOF
    is difficult to explain.
    
    * doc/groff.texi (Environment):
    * src/devices/grohtml/grohtml.1.man (Environment):
    * src/devices/gropdf/gropdf.1.man (Environment):
    * src/devices/grops/grops.1.man (Environment):
    * src/roff/groff/groff.1.man (Environment):
    * src/roff/troff/troff.1.man (Environment): Expand description of use of
      SOURCE_DATE_EPOCH to note that it converts the time (as seconds since
      the Epoch) to local time, which motivates documentation of the TZ
      environment variable.  Explain what the time stamps are used for:
      troff merely stores the human-readable time components in registers;
      the grohtml, gropdf, and grops output drivers write the information to
      the output in comments.
    
    Fixes <https://savannah.gnu.org/bugs/?57218>.
    
    [1] https://reproducible-builds.org/docs/source-date-epoch/
---
 ChangeLog                         | 45 +++++++++++++++++++++++++++++++++++++++
 NEWS                              | 12 +++++++++++
 doc/groff.texi                    | 14 +++++++++---
 src/devices/grohtml/grohtml.1.man | 14 ++++++++++++
 src/devices/gropdf/gropdf.1.man   | 21 ++++++++++++++++--
 src/devices/grops/grops.1.man     | 19 +++++++++++++++--
 src/roff/groff/groff.1.man        | 22 +++++++++++++++++++
 src/roff/troff/troff.1.man        | 22 +++++++++++++++++++
 8 files changed, 162 insertions(+), 7 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 31240ad..e75f920 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,48 @@
+2021-01-04  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       Document use of SOURCE_DATE_EPOCH and TZ.
+
+       The semantics of SOURCE_DATE_EPOCH to groff were not established
+       with respect to time zone selection, prompting divergent
+       interpretations; Debian and distributions derived from it have
+       for several years patched groff to implicitly use UTC as the
+       time zone when interpreting the current time (or
+       SOURCE_DATE_EPOCH) as a local time.  While a convenient and
+       defensible choice for reproducible build efforts[1], it runs
+       against the grain of user expectations.  Systems programmers
+       like monotonically increasing clocks; the broader user base
+       usually prefers a clock that follows an applicable civil
+       calendar.  To the latter audience, a difference between
+         $ date "+%Y-%M-%d %H:%m:%S"
+       and
+         $ groff <<EOF
+         .af year 0000
+         .af mo 00
+         .af dy 00
+         .af hours 00
+         .af minutes 00
+         .af seconds 00
+         .tm \n[year]-\n[mo]-\n[dy] \n[hours]:\n[minutes]:\n[seconds]
+         EOF
+       is difficult to explain.
+
+       * doc/groff.texi (Environment):
+       * src/devices/grohtml/grohtml.1.man (Environment):
+       * src/devices/gropdf/gropdf.1.man (Environment):
+       * src/devices/grops/grops.1.man (Environment):
+       * src/roff/groff/groff.1.man (Environment):
+       * src/roff/troff/troff.1.man (Environment): Expand description
+       of use of SOURCE_DATE_EPOCH to note that it converts the time
+       {as seconds since the Epoch} to local time, which motivates
+       documentation of the TZ environment variable.  Explain what the
+       time stamps are used for: troff merely stores the human-readable
+       time components in registers; the grohtml, gropdf, and grops
+       output drivers write the information to the output in comments.
+
+       Fixes <https://savannah.gnu.org/bugs/?57218>.
+
+       [1] https://reproducible-builds.org/docs/source-date-epoch/
+
 2021-01-03  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        * src/roff/troff/input.cpp (init_registers): Delete comment from
diff --git a/NEWS b/NEWS
index f616d92..00355b3 100644
--- a/NEWS
+++ b/NEWS
@@ -148,6 +148,18 @@ o On the Latin-1 output device ("groff -T latin1") the 
output glyph
 Miscellaneous
 -------------
 
+o The semantics of the environment variable SOURCE_DATE_EPOCH (support
+  for which was added in 1.22.4) to groff were not established with
+  respect to time zone selection, prompting divergent interpretations;
+  Debian and distributions derived from it have for several years
+  patched groff to implicitly use UTC as the time zone when interpreting
+  the current time (or SOURCE_DATE_EPOCH) as a local time.  While a
+  convenient and defensible choice for reproducible build efforts, it
+  runs against the grain of user expectations.  Systems programmers like
+  monotonically increasing clocks; the broader user base usually prefers
+  a clock that follows an applicable civil calendar.  Users of
+  SOURCE_DATE_EPOCH may also wish to set the TZ environment variable.
+
 o groffer has been deleted from the distribution.
 
 
diff --git a/doc/groff.texi b/doc/groff.texi
index 35dd7f6..fab68a5 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -1453,9 +1453,17 @@ The default output device.
 
 @item SOURCE_DATE_EPOCH
 @tindex SOURCE_DATE_EPOCH@r{, environment variable}
-A timestamp (expressed as seconds since the Unix epoch) to use in place
-of the current time when initializing time-based built-in registers such
-as @code{\n[seconds]}.
+A timestamp (expressed as seconds since the Unix epoch) to use as the
+creation timestamp in place of the current time.  The time is converted
+to human-readable form using @cite{ctime@r{(3)}} when the formatter
+starts up and stored in registers usable by documents and macro
+packages (@pxref{Built-in Registers}).
+
+@item TZ
+@tindex TZ@r{, environment variable}
+The time zone to use when converting the current time (or value of
+@env{SOURCE_DATE_EPOCH}) to human-readable form; see
+@cite{tzset@r{(3)}}.
 @end table
 
 MS-DOS and MS-Windows ports of @code{groff} use semicolons, rather than
diff --git a/src/devices/grohtml/grohtml.1.man 
b/src/devices/grohtml/grohtml.1.man
index c7e4996..2980663 100644
--- a/src/devices/grohtml/grohtml.1.man
+++ b/src/devices/grohtml/grohtml.1.man
@@ -481,6 +481,20 @@ A timestamp
 (expressed as seconds since the Unix epoch)
 to use as the creation timestamp in place of the current time.
 .
+The time is converted to human-readable form using
+.IR ctime (3)
+and recorded in an HTML comment.
+.
+.
+.TP
+.I TZ
+The time zone to use when converting the current time
+(or value of
+.IR SOURCE_DATE_EPOCH )
+to human-readable form;
+see
+.IR tzset (3).
+.
 .
 .\" ====================================================================
 .SH Bugs
diff --git a/src/devices/gropdf/gropdf.1.man b/src/devices/gropdf/gropdf.1.man
index 56c82ef..6466a35 100644
--- a/src/devices/gropdf/gropdf.1.man
+++ b/src/devices/gropdf/gropdf.1.man
@@ -1334,10 +1334,27 @@ If this is set true,
 .B gropdf
 will ignore all commands which produce a presentation pdf,
 and produce a normal pdf instead.
+.
+.
 .TP
 .I SOURCE_DATE_EPOCH
-A timestamp (expressed as seconds since the Unix epoch) to use as the
-creation timestamp in place of the current time.
+A timestamp
+(expressed as seconds since the Unix epoch)
+to use as the creation timestamp in place of the current time.
+.
+The time is converted to human-readable form using Perl's
+.I localtime()
+function and recorded in a PDF comment.
+.
+.
+.TP
+.I TZ
+The time zone to use when converting the current time
+(or value of
+.IR SOURCE_DATE_EPOCH )
+to human-readable form;
+see
+.IR tzset (3).
 .
 .
 .\" ====================================================================
diff --git a/src/devices/grops/grops.1.man b/src/devices/grops/grops.1.man
index 5c6861e..59f8403 100644
--- a/src/devices/grops/grops.1.man
+++ b/src/devices/grops/grops.1.man
@@ -1486,8 +1486,23 @@ for more details.
 .
 .TP
 .I SOURCE_DATE_EPOCH
-A timestamp (expressed as seconds since the Unix epoch) to use as the
-creation timestamp in place of the current time.
+A timestamp
+(expressed as seconds since the Unix epoch)
+to use as the creation timestamp in place of the current time.
+.
+The time is converted to human-readable form using
+.IR ctime (3)
+and recorded in a PostScript comment.
+.
+.
+.TP
+.I TZ
+The time zone to use when converting the current time
+(or value of
+.IR SOURCE_DATE_EPOCH )
+to human-readable form;
+see
+.IR tzset (3).
 .
 .
 .\" ====================================================================
diff --git a/src/roff/groff/groff.1.man b/src/roff/groff/groff.1.man
index 3758141..127c2eb 100644
--- a/src/roff/groff/groff.1.man
+++ b/src/roff/groff/groff.1.man
@@ -1585,6 +1585,28 @@ This device name is overwritten by the option
 .BR \-T .
 .
 .
+.TP
+.I SOURCE_DATE_EPOCH
+A timestamp
+(expressed as seconds since the Unix epoch)
+to use as the creation timestamp in place of the current time.
+.
+The time is converted to human-readable form using
+.IR ctime (3)
+when the formatter starts up and stored in registers usable by documents
+and macro packages.
+.
+.
+.TP
+.I TZ
+The time zone to use when converting the current time
+(or value of
+.IR SOURCE_DATE_EPOCH )
+to human-readable form;
+see
+.IR tzset (3).
+.
+.
 .\" ====================================================================
 .SH Examples
 .\" ====================================================================
diff --git a/src/roff/troff/troff.1.man b/src/roff/troff/troff.1.man
index eb3b92a..0fde2e6 100644
--- a/src/roff/troff/troff.1.man
+++ b/src/roff/troff/troff.1.man
@@ -662,6 +662,28 @@ option before these, and in standard directories
 after these.
 .
 .
+.TP
+.I SOURCE_DATE_EPOCH
+A timestamp
+(expressed as seconds since the Unix epoch)
+to use as the creation timestamp in place of the current time.
+.
+The time is converted to human-readable form using
+.IR ctime (3)
+when the formatter starts up and stored in registers usable by documents
+and macro packages.
+.
+.
+.TP
+.I TZ
+The timezone to use when converting the current time
+(or value of
+.IR SOURCE_DATE_EPOCH )
+to human-readable form;
+see
+.IR tzset (3).
+.
+.
 .\" ====================================================================
 .SH Files
 .\" ====================================================================