bug-gnulib
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[PATCH] parse-datetime: modernize doc


From: Paul Eggert
Subject: [PATCH] parse-datetime: modernize doc
Date: Fri, 24 Jul 2020 12:20:36 -0700

* doc/parse-datetime.texi: Use more-current examples.
Don’t lead with 32-bit time_t, as it’s on its way out.
Capitalize “Epoch” to be consistent with POSIX.
---
 ChangeLog               |  5 +++
 doc/parse-datetime.texi | 97 ++++++++++++++++++++---------------------
 2 files changed, 53 insertions(+), 49 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 1f46cca66..f56249b17 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,10 @@
 2020-07-24  Paul Eggert  <eggert@cs.ucla.edu>
 
+       parse-datetime: modernize doc
+       * doc/parse-datetime.texi: Use more-current examples.
+       Don’t lead with 32-bit time_t, as it’s on its way out.
+       Capitalize “Epoch” to be consistent with POSIX.
+
        timespec: remove dependence on ‘verify’
        * lib/timespec.h: Do not include verify.h; no longer needed.
        * modules/timespec (Depends-on): Remove ‘verify’.
diff --git a/doc/parse-datetime.texi b/doc/parse-datetime.texi
index c435ea4c2..f7e368514 100644
--- a/doc/parse-datetime.texi
+++ b/doc/parse-datetime.texi
@@ -46,17 +46,17 @@ arguments to the various programs.  The C interface (via the
 @code{parse_datetime} function) is not described here.
 
 @menu
-* General date syntax::            Common rules.
-* Calendar date items::            19 Dec 1994.
-* Time of day items::              9:20pm.
-* Time zone items::                EST, PDT, UTC, @dots{}
-* Combined date and time of day items:: 1972-09-24T20:02:00,000000-0500.
-* 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 parse_datetime::      Bellovin, Eggert, Salz, Berets, et al.
+* General date syntax::          Common rules
+* Calendar date items::          21 Jul 2020
+* Time of day items::            9:20pm
+* Time zone items::              UTC, -0700, +0900, @dots{}
+* Combined date and time of day items:: 2020-07-21T20:02:00,000000-0400
+* Day of week items::            Monday and others
+* Relative items in date strings:: next tuesday, 2 years ago
+* Pure numbers in date strings:: 20200721, 1440
+* Seconds since the Epoch::      @@1595289600
+* Specifying time zone rules::   TZ="America/New_York", TZ="UTC0"
+* Authors of parse_datetime::    Bellovin, Eggert, Salz, Berets, et al.
 @end menu
 
 
@@ -124,17 +124,17 @@ ways to do this:
 
 @example
 $ LC_ALL=C TZ=UTC0 date
-Mon Mar  1 00:21:42 UTC 2004
+Tue Jul 21 23:00:37 UTC 2020
 $ TZ=UTC0 date +'%Y-%m-%d %H:%M:%SZ'
-2004-03-01 00:21:42Z
+2020-07-21 23:00:37Z
 $ date --rfc-3339=ns  # --rfc-3339 is a GNU extension.
-2004-02-29 16:21:42.692722128-08:00
+2020-07-21 19:00:37.692722128-04:00
 $ date --rfc-2822  # a GNU extension
-Sun, 29 Feb 2004 16:21:42 -0800
+Tue, 21 Jul 2020 19:00:37 -0400
 $ date +'%Y-%m-%d %H:%M:%S %z'  # %z is a GNU extension.
-2004-02-29 16:21:42 -0800
+2020-07-21 19:00:37 -0400
 $ date +'@@%s.%N'  # %s and %N are GNU extensions.
-@@1078100502.692722128
+@@1595372437.692722128
 @end example
 
 @cindex case, ignored in dates
@@ -145,7 +145,7 @@ nested.  Hyphens not followed by a digit are currently 
ignored.  Leading
 zeros on numbers are ignored.
 
 @cindex leap seconds
-Invalid dates like @samp{2005-02-29} or times like @samp{24:00} are
+Invalid dates like @samp{2019-02-29} or times like @samp{24:00} are
 rejected.  In the typical case of a host that does not support leap
 seconds, a time like @samp{23:59:60} is rejected even if it
 corresponds to a valid leap second.
@@ -161,25 +161,23 @@ specified differently, depending on whether the month is 
specified
 numerically or literally.  All these strings specify the same calendar date:
 
 @example
-1972-09-24     # ISO 8601.
-72-9-24        # Assume 19xx for 69 through 99,
-               # 20xx for 00 through 68.
-72-09-24       # Leading zeros are ignored.
-9/24/72        # Common U.S. writing.
-24 September 1972
-24 Sept 72     # September has a special abbreviation.
-24 Sep 72      # Three-letter abbreviations always allowed.
-Sep 24, 1972
-24-sep-72
-24sep72
+2020-07-20     # ISO 8601.
+20-7-20        # Assume 19xx for 69 through 99,
+               # 20xx for 00 through 68 (not recommended).
+7/20/2020      # Common U.S. writing.
+20 July 2020
+20 Jul 2020    # Three-letter abbreviations always allowed.
+Jul 20, 2020
+20-jul-2020
+20jul2020
 @end example
 
 The year can also be omitted.  In this case, the last specified year is
 used, or the current year if none.  For example:
 
 @example
-9/24
-sep 24
+7/20
+jul 20
 @end example
 
 Here are the rules.
@@ -432,14 +430,14 @@ 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
+example, @samp{2020-07-31 -1 month} might evaluate to 2020-07-01,
+because 2020-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:
 
 @example
 $ date -R
-Thu, 31 Jul 2003 13:02:39 -0700
+Thu, 31 Jul 2020 13:02:39 -0400
 $ date --date='-1 month' +'Last month was %B?'
 Last month was July?
 $ date --date="$(date +%Y-%m-15) -1 month" +'Last month was %B!'
@@ -487,28 +485,29 @@ infinity.  Such a number cannot be combined with any 
other date
 item, as it specifies a complete timestamp.
 
 @cindex beginning of time, for POSIX
-@cindex epoch, for POSIX
+@cindex Epoch, for POSIX
 Internally, computer times are represented as a count of seconds since
-an epoch---a well-defined point of time.  On GNU and
-POSIX systems, the epoch is 1970-01-01 00:00:00 UTC, so
+an Epoch---a well-defined point of time.  On GNU and
+POSIX systems, the Epoch is 1970-01-01 00:00:00 UTC, so
 @samp{@@0} represents this time, @samp{@@1} represents 1970-01-01
 00:00:01 UTC, and so forth.  GNU and most other
 POSIX-compliant systems support such times as an extension
 to POSIX, using negative counts, so that @samp{@@-1}
 represents 1969-12-31 23:59:59 UTC.
 
-Traditional Unix systems count seconds with 32-bit two's-complement
+Most modern systems count seconds with 64-bit two's-complement integers
+of seconds with nanosecond subcounts, which is a range that includes
+the known lifetime of the universe with nanosecond resolution.
+Some obsolescent 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 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.
+2038-01-19 03:14:07 UTC@.  A few systems sport other time ranges.
 
 @cindex leap seconds
 On most hosts, these counts ignore the presence of leap seconds.
-For example, on most hosts @samp{@@915148799} represents 1998-12-31
-23:59:59 UTC, @samp{@@915148800} represents 1999-01-01 00:00:00
+For example, on most hosts @samp{@@1483228799} represents 2016-12-31
+23:59:59 UTC, @samp{@@1483228800} represents 2017-01-01 00:00:00
 UTC, and there is no way to represent the intervening leap second
-1998-12-31 23:59:60 UTC.
+2016-12-31 23:59:60 UTC.
 
 @node Specifying time zone rules
 @section Specifying time zone rules
@@ -525,22 +524,22 @@ backslash.
 
 For example, with the GNU @command{date} command you can
 answer the question ``What time is it in New York when a Paris clock
-shows 6:30am on October 31, 2004?'' by using a date beginning with
+shows 6:30am on October 31, 2019?'' by using a date beginning with
 @samp{TZ="Europe/Paris"} as shown in the following shell transcript:
 
 @example
 $ export TZ="America/New_York"
-$ date --date='TZ="Europe/Paris" 2004-10-31 06:30'
-Sun Oct 31 01:30:00 EDT 2004
+$ date --date='TZ="Europe/Paris" 2019-10-31 06:30'
+Sun Oct 31 01:30:00 EDT 2019
 @end example
 
 In this example, the @option{--date} operand begins with its own
 @env{TZ} setting, so the rest of that operand is processed according
-to @samp{Europe/Paris} rules, treating the string @samp{2004-10-31
+to @samp{Europe/Paris} rules, treating the string @samp{2019-10-31
 06:30} as if it were in Paris.  However, since the output of the
 @command{date} command is processed according to the overall time zone
 rules, it uses New York time.  (Paris was normally six hours ahead of
-New York in 2004, but this example refers to a brief Halloween period
+New York in 2019, but this example refers to a brief Halloween period
 when the gap was five hours.)
 
 A @env{TZ} value is a rule that typically names a location in the
-- 
2.17.1




reply via email to

[Prev in Thread] Current Thread [Next in Thread]