[Bug-tar] getdate documentation update for GNU tar

[Paul Eggert]

I installed this patch to update the getdate documentation to match
the new gnulib code.

2004-04-04  Paul Eggert  <address@hidden>

        Merge getdate documentation changes from coreutils.

        * doc/getdate.texi: Update from coreutils CVS.
        * doc/tar.texi: Fix getdate menu to match getdate.texi's.

Index: doc/tar.texi
===================================================================
RCS file: /cvsroot/tar/tar/doc/tar.texi,v
retrieving revision 1.47
diff -p -u -r1.47 tar.texi
--- doc/tar.texi        26 Feb 2004 18:02:50 -0000      1.47
+++ doc/tar.texi        5 Apr 2004 05:43:35 -0000
@@ -503,7 +503,7 @@ This manual is for @acronym{GNU} @comman
 from archives.
 
 Copyright @copyright{} 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001,
-2003 Free Software Foundation, Inc.
+2003, 2004 Free Software Foundation, Inc.
 
 @quotation
 Permission is granted to copy, distribute and/or modify this document
@@ -757,7 +757,8 @@ Date input formats
 * Day of week items::              Monday and others.
 * Relative items in date strings:: next tuesday, 2 years ago.
 * Pure numbers in date strings::   19931219, 1440.
-* Authors of getdate::             Bellovin, Eggert, Salz, Berets, et al.
+* Seconds since the Epoch::        @@1078100502.
+* Authors of get_date::            Bellovin, Eggert, Salz, Berets, et al.
 
 Controlling the Archive Format
 
Index: doc/getdate.texi
===================================================================
RCS file: /cvsroot/tar/tar/doc/getdate.texi,v
retrieving revision 1.8
diff -p -u -r1.8 getdate.texi
--- doc/getdate.texi    4 Jul 2003 18:06:51 -0000       1.8
+++ doc/getdate.texi    5 Apr 2004 05:43:28 -0000
@@ -1,19 +1,20 @@
address@hidden Date input formats
address@hidden Date input formats
address@hidden GNU date syntax documentation
 
address@hidden Copyright (C) 1994, 1995, 1996, 1997, 1999, 2000, 2001, 2003 
Free Software
address@hidden Foundation, Inc.
address@hidden Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 
2002,
address@hidden 2003, 2004 Free Software Foundation, Inc.
 
 @c Permission is granted to copy, distribute and/or modify this document
address@hidden under the terms of the GNU Free Documentation License, Version 
1.1
address@hidden or any later version published by the Free Software Foundation;
address@hidden with no Invariant Sections, with no
address@hidden Front-Cover Texts, and with no Back-Cover Texts.
address@hidden A copy of the license is included in the section entitled ``GNU
address@hidden Free Documentation License''.
address@hidden under the terms of the GNU Free Documentation License, Version 
1.1 or
address@hidden any later version published by the Free Software Foundation; 
with no
address@hidden Invariant Sections, with no Front-Cover Texts, and with no 
Back-Cover
address@hidden Texts.  A copy of the license is included in the ``GNU Free
address@hidden Documentation License'' file as part of this distribution.
+
address@hidden Date input formats
address@hidden Date input formats
 
 @cindex date input formats
address@hidden getdate
address@hidden get_date
 
 First, a quote:
 
@@ -44,19 +45,7 @@ or a week from Sunday, with feelings of 
 This section describes the textual date representations that @sc{gnu}
 programs accept.  These are the strings you, as a user, can supply as
 arguments to the various programs.  The C interface (via the
address@hidden function) is not described here.
-
address@hidden beginning of time, for @acronym{POSIX}
address@hidden epoch, for @acronym{POSIX}
-Although the date syntax here can represent any possible time since the
-year zero, computer integers often cannot represent such a wide range of
-time.  On @acronym{POSIX} systems, the clock starts at 1970-01-01 00:00:00
address@hidden: @acronym{POSIX} does not require support for times before the
address@hidden Epoch and times far in the future.  Traditional Unix systems
-have 32-bit signed @code{time_t} and can represent times from 1901-12-13
-20:45:52 through 2038-01-19 03:14:07 @sc{utc}.  Systems with 64-bit
-signed @code{time_t} can represent all the times in the known
-lifetime of the universe.
address@hidden function) is not described here.
 
 @menu
 * General date syntax::            Common rules.
@@ -66,7 +55,8 @@ lifetime of the universe.
 * Day of week items::              Monday and others.
 * Relative items in date strings:: next tuesday, 2 years ago.
 * Pure numbers in date strings::   19931219, 1440.
-* Authors of getdate::             Bellovin, Eggert, Salz, Berets, et al.
+* Seconds since the Epoch::        @@1078100502.
+* Authors of get_date::            Bellovin, Eggert, Salz, Berets, et al.
 @end menu
 
 
@@ -128,15 +118,17 @@ ways to do this:
 
 @example
 $ LC_ALL=C TZ=UTC0 date
-Fri Dec 15 19:48:05 UTC 2000
-$ TZ=UTC0 date +"%Y-%m-%d %H:%M:%SZ"
-2000-12-15 19:48:05Z
-$ date --iso-8601=seconds  # a GNU extension
-2000-12-15T11:48:05-0800
-$ date --rfc-822  # a GNU extension
-Fri, 15 Dec 2000 11:48:05 -0800
-$ date +"%Y-%m-%d %H:%M:%S %z"  # %z is a GNU extension.
-2000-12-15 11:48:05 -0800
+Mon Mar  1 00:21:42 UTC 2004
+$ TZ=UTC0 date +'%Y-%m-%d %H:%M:%SZ'
+2004-03-01 00:21:42Z
+$ date --iso-8601=ns  # a GNU extension
+2004-02-29T16:21:42,692722128-0800
+$ date --rfc-2822  # a GNU extension
+Sun, 29 Feb 2004 16:21:42 -0800
+$ date +'%Y-%m-%d %H:%M:%S %z'  # %z is a GNU extension.
+2004-02-29 16:21:42 -0800
+$ date +'@@%s.%N'  # %s and %N are GNU extensions.
+@@1078100502.692722128
 @end example
 
 @cindex case, ignored in dates
@@ -227,7 +219,7 @@ A @dfn{time of day item} in date strings
 day.  Here are some examples, all of which represent the same time:
 
 @example
-20:02:0
+20:02:00.000000
 20:02
 8:02pm
 20:02-0500      # In @sc{est} (U.S. Eastern Standard Time).
@@ -236,7 +228,9 @@ day.  Here are some examples, all of whi
 More generally, the time of the day may be given as
 @address@hidden:@var{minute}:@var{second}}, where @var{hour} is
 a number between 0 and 23, @var{minute} is a number between 0 and
-59, and @var{second} is a number between 0 and 59.  Alternatively,
+59, and @var{second} is a number between 0 and 59 possibly followed by
address@hidden or @samp{,} and a fraction containing one or more digits.
+Alternatively,
 @samp{:@var{second}} can be omitted, in which case it is taken to
 be zero.
 
@@ -381,6 +375,26 @@ When a relative item causes the resultin
 where the clocks were adjusted, typically for daylight-saving time,
 the resulting date and time are adjusted accordingly.
 
+The fuzz in units can cause problems with relative items.  For
+example, @samp{2003-07-31 -1 month} might evaluate to 2003-07-01,
+because 2003-06-31 is an invalid date.  To determine the previous
+month more reliably, you can ask for the month before the 15th of the
+current month.  For example:
+
address@hidden
+$ date -R
+Thu, 31 Jul 2003 13:02:39 -0700
+$ date --date='-1 month' +'Last month was %B?'
+Last month was July?
+$ date --date="$(date +%Y-%m-15) -1 month" +'Last month was %B!'
+Last month was June!
address@hidden example
+
+Also, take care when manipulating dates around clock changes such as
+daylight saving leaps.  In a few cases these have added or subtracted
+as much as 24 hours from the clock, so it is often wise to adopt
+universal time by setting the @env{TZ} environment variable to
address@hidden before embarking on calendrical calculations.
 
 @node Pure numbers in date strings
 @section Pure numbers in date strings
@@ -406,10 +420,42 @@ in the date string, but no relative item
 year.
 
 
address@hidden Authors of getdate
address@hidden Authors of @code{getdate}
address@hidden Seconds since the Epoch
address@hidden Seconds since the Epoch
+
+If you precede a number with @samp{@@}, it represents an internal time
+stamp as a count of seconds.  The number can contain an internal
+decimal point (either @samp{.} or @samp{,}); any excess precision not
+supported by the internal representation is truncated toward minus
+infinity.
+
address@hidden beginning of time, for @acronym{POSIX}
address@hidden epoch, for @acronym{POSIX}
+Internally, computer times are represented as a count of seconds since
+an epoch---a well-defined point of time.  On @acronym{GNU} and
address@hidden systems, the epoch is 1970-01-01 00:00:00 @sc{utc}, so
address@hidden@@0} represents this time, @samp{@@1} represents 1970-01-01
+00:00:01 @sc{utc}, and so forth.  @acronym{GNU} and most other
address@hidden systems support such times as an extension
+to @acronym{POSIX}, using negative counts, so that @samp{@@-1}
+represents 1969-12-31 23:59:59 @sc{utc}.
+
+Traditional Unix systems count seconds with 32-bit two's-complement
+integers and can represent times from 1901-12-13 20:45:52 through
+2038-01-19 03:14:07 @sc{utc}.  More modern systems use 64-bit counts
+of seconds with nanosecond subcounts, and can represent all the times
+in the known lifetime of the universe to a resolution of 1 nanosecond.
+
+On most systems, these counts ignore the presence of leap seconds.
+For example, on most systems @samp{@@915148799} represents 1998-12-31
+23:59:59 @sc{utc}, @samp{@@915148800} represents 1999-01-01 00:00:00
address@hidden, and there is no way to represent the intervening leap second
+1998-12-31 23:59:60 @sc{utc}.
+
address@hidden Authors of get_date
address@hidden Authors of @code{get_date}
 
address@hidden authors of @code{getdate}
address@hidden authors of @code{get_date}
 
 @cindex Bellovin, Steven M.
 @cindex Salz, Rich
@@ -417,7 +463,7 @@ year.
 @cindex MacKenzie, David
 @cindex Meyering, Jim
 @cindex Eggert, Paul
address@hidden was originally implemented by Steven M. Bellovin
address@hidden was originally implemented by Steven M. Bellovin
 (@email{smb@@research.att.com}) while at the University of North Carolina
 at Chapel Hill.  The code was later tweaked by a couple of people on
 Usenet, then completely overhauled by Rich $alz (@email{rsalz@@bbn.com})