coreutils doc fix to cover TZ better

[Paul Eggert]

The coreutils manual doesn't cover TZ in some places that it should,
e.g., "ls", "who".  Also, I'm about to merge gnulib getdate into
coreutils, so some cross references need updating.  I installed this
patch.

Maybe the coreutils manual should get reorganized a bit so that TZ and
similarly-global environment variables (e.g., LC_ALL) are all
documented together?  Just a thought.

2004-10-29  Paul Eggert  <address@hidden>

        * coreutils.texi: Document TZ better, and adjust to new getdate.texi.
        (Top): Update menu.
        (pr invocation, Formatting file timestamps, touch invocation,
        stat invocation, who invocation, date invocation, Options for date):
        Mention TZ.

--- coreutils.texi.~1.223.~     2004-10-28 00:43:52 -0700
+++ coreutils.texi      2004-10-29 16:18:45 -0700
@@ -432,15 +432,16 @@ File permissions
 
 Date input formats
 
-* General date syntax:           General date syntax
-* Calendar date items:           Calendar date items
-* Time of day items:             Time of day items
-* Time zone items:               Time zone items
-* Day of week items:             Day of week items
-* Relative items in date strings:  Relative items in date strings
-* Pure numbers in date strings:  Pure numbers in date strings
-* Seconds since the Epoch:       Seconds since the Epoch
-* Authors of get_date:           Authors of get_date
+* General date syntax::          Common rules.
+* Calendar date items::          19 Dec 1994.
+* Time of day items::            9:20pm.
+* Time zone items::              @sc{est}, @sc{pdt}, @sc{gmt}.
+* Day of week items::            Monday and others.
+* Relative items in date strings:: next tuesday, 2 years ago.
+* Pure numbers in date strings:: 19931219, 1440.
+* Seconds since the Epoch::      @@1078100502.
+* Specifying time zone rules::   TZ="America/New_York", TZ="UTC0".
+* Authors of get_date::          Bellovin, Eggert, Salz, Berets, et al.
 
 Opening the software toolbox
 
@@ -2047,6 +2048,12 @@ and the @env{LC_TIME} locale category sp
 locale, the default is @samp{%b %e %H:%M %Y} (for example,
 @samp{Dec@ @ 4 23:59 2001}.
 
address@hidden TZ
+Time stamps are listed according to the time zone rules specified by
+the @env{TZ} environment variable, or by the system default rules if
address@hidden is not set.  @xref{TZ Variable,, Specifying the Time Zone
+with @env{TZ}, libc, The GNU C Library}.
+
 @item address@hidden@var{in-tabwidth}]]
 @itemx address@hidden@var{in-tabwidth}]]
 @opindex -e
@@ -5938,6 +5945,12 @@ today is not listed in recent form, the 
 which means you probably have clock skew problems which may break
 programs like @command{make} that rely on file timestamps.
 
address@hidden TZ
+Time stamps are listed according to the time zone rules specified by
+the @env{TZ} environment variable, or by the system default rules if
address@hidden is not set.  @xref{TZ Variable,, Specifying the Time Zone
+with @env{TZ}, libc, The GNU C Library}.
+
 The following option changes how file timestamps are printed.
 
 @table @samp
@@ -8460,6 +8473,13 @@ Another operation that modifies a file's
 the others is renaming.  In any case, it is not possible, in normal
 operations, for a user to change the ctime field to a user-specified value.
 
address@hidden TZ
+Time stamps assume the time zone rules specified by the @env{TZ}
+environment variable, or by the system default rules if @env{TZ} is
+not set.  @xref{TZ Variable,, Specifying the Time Zone with @env{TZ},
+libc, The GNU C Library}.  You can avoid avoid ambiguities during
+daylight saving transitions by using @sc{utc} time stamps.
+
 The program accepts the following options.  Also see @ref{Common options}.
 
 @table @samp
@@ -9011,6 +9031,7 @@ Print the information in terse form, sui
 Use @var{format} rather than the default format.
 
 Interpreted sequences for file stat are:
+
 @itemize @bullet
 @item %a - Access rights in octal
 @item %A - Access rights in human readable form
@@ -9041,6 +9062,7 @@ Interpreted sequences for file stat are:
 @end itemize
 
 Interpreted sequences for file system stat are:
+
 @itemize @bullet
 @item %n - File name
 @item %i - File System id in hex
@@ -9053,6 +9075,12 @@ Interpreted sequences for file system st
 @item %s - Optimal transfer block size
 @item %c - Total file nodes in file system
 @end itemize
+
address@hidden TZ
+Time stamps are listed according to the time zone rules specified by
+the @env{TZ} environment variable, or by the system default rules if
address@hidden is not set.  @xref{TZ Variable,, Specifying the Time Zone
+with @env{TZ}, libc, The GNU C Library}.
 @end table
 
 @exitstatus
@@ -11185,6 +11213,12 @@ for the user running it (determined from
 by the hostname.  Traditionally, the two arguments given are @samp{am
 i}, as in @samp{who am i}.
 
address@hidden TZ
+Time stamps are listed according to the time zone rules specified by
+the @env{TZ} environment variable, or by the system default rules if
address@hidden is not set.  @xref{TZ Variable,, Specifying the Time Zone
+with @env{TZ}, libc, The GNU C Library}.
+
 The program accepts the following options.  Also see @ref{Common options}.
 
 @table @samp
@@ -11329,6 +11363,12 @@ it with a default format that depends on
 In the default C locale, this format is @samp{'+%a %b %e %H:%M:%S %Z %Y'},
 so the output looks like @samp{Fri Feb 27 13:47:51 PST 2004}.
 
address@hidden TZ
+Normally, @command{date} uses the time zone rules indicated by the
address@hidden environment variable, or the system default rules if @env{TZ}
+is not set.  @xref{TZ Variable,, Specifying the Time Zone with
address@hidden, libc, The GNU C Library}.
+
 @findex strftime @r{and @command{date}}
 @cindex time formats
 @cindex formatting times
@@ -11688,10 +11728,10 @@ Set the time and date to @var{datestr}. 
 @cindex UTC
 @cindex Greenwich Mean Time
 @cindex GMT
address@hidden TZ
 Use Coordinated Universal Time (@acronym{UTC}) by operating as if the
 @env{TZ} environment variable were set to the string @samp{UTC0}.
-Normally, @command{date} operates in the time zone indicated by
address@hidden, or the system default if @env{TZ} is not set.  Coordinated
+Coordinated
 Universal Time is often called ``Greenwich Mean Time'' (@sc{gmt}) for
 historical reasons.
 @end table