* doc/parse-datetime.texi: Use @samp and @code in menus
for consistenty with how the Coreutils manual will do
this sort of thing. Update examples to this year.
---
ChangeLog | 7 ++++
doc/parse-datetime.texi | 78 ++++++++++++++++++++---------------------
2 files changed, 46 insertions(+), 39 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index d51a62a023..4ae5aefa54 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2022-11-14 Paul Eggert <egg...@cs.ucla.edu>
+
+ parse-datetime: improve doc formatting, timeliness
+ * doc/parse-datetime.texi: Use @samp and @code in menus
+ for consistenty with how the Coreutils manual will do
+ this sort of thing. Update examples to this year.
+
2022-11-13 Simon Josefsson <si...@josefsson.org>
vc-list-files-tests: Avoid OpenPGP private key operations.
diff --git a/doc/parse-datetime.texi b/doc/parse-datetime.texi
index e1ce97220a..0c91013a6c 100644
--- a/doc/parse-datetime.texi
+++ b/doc/parse-datetime.texi
@@ -47,15 +47,15 @@ arguments to the various programs. The C interface (via the
@menu
* 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"
+* Calendar date items:: @samp{14 Nov 2022}
+* Time of day items:: @samp{9:02pm}
+* Time zone items:: @samp{UTC}, @samp{-0700}, @samp{+0900},
@dots{}
+* Combined date and time of day items:: @samp{2022-11-14T21:02:42,000000-0500}
+* Day of week items:: @samp{Monday} and others
+* Relative items in date strings:: @samp{next tuesday, 2 years ago}
+* Pure numbers in date strings:: @samp{20221114}, @samp{2102}
+* Seconds since the Epoch:: @samp{@@1668477762}
+* Specifying time zone rules:: @samp{TZ="America/New_York"}, @samp{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
-Tue Jul 21 23:00:37 UTC 2020
+Tue Nov 15 02:02:42 UTC 2022
$ TZ=UTC0 date +'%Y-%m-%d %H:%M:%SZ'
-2020-07-21 23:00:37Z
+2022-11-15 02:02:42Z
$ date --rfc-3339=ns # --rfc-3339 is a GNU extension.
-2020-07-21 19:00:37.692722128-04:00
-$ date --rfc-2822 # a GNU extension
-Tue, 21 Jul 2020 19:00:37 -0400
+2022-11-14 21:02:42.000000000-05:00
+$ date --rfc-email # a GNU extension
+Mon, 14 Nov 2022 21:02:42 -0500
$ date +'%Y-%m-%d %H:%M:%S %z' # %z is a GNU extension.
-2020-07-21 19:00:37 -0400
+2022-11-14 21:02:42 -0500
$ date +'@@%s.%N' # %s and %N are GNU extensions.
-@@1595372437.692722128
+@@1668477762.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{2019-02-29} or times like @samp{24:00} are
+Invalid dates like @samp{2022-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,23 +161,23 @@ specified differently, depending on whether the month is
specified
numerically or literally. All these strings specify the same calendar date:
@example
-2020-07-20 # ISO 8601.
-20-7-20 # Assume 19xx for 69 through 99,
+2022-11-14 # ISO 8601.
+22-11-14 # 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
+11/14/2022 # Common U.S. writing.
+14 November 2022
+14 Nov 2022 # Three-letter abbreviations always allowed.
+November 14, 2022
+14-nov-2022
+14nov2022
@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
-7/20
-jul 20
+11/14
+nov 14
@end example
Here are the rules.
@@ -335,8 +335,8 @@ excess precision is silently discarded.
Here are some examples:
@example
-2012-09-24T20:02:00.052-05:00
-2012-12-31T23:59:59,999999999+11:00
+2022-09-24T20:02:00.052-05:00
+2022-12-31T23:59:59,999999999+11:00
1970-01-01 00:00Z
@end example
@@ -430,18 +430,18 @@ 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{2020-07-31 -1 month} might evaluate to 2020-07-01,
-because 2020-06-31 is an invalid date. To determine the previous
+example, @samp{2022-12-31 -1 month} might evaluate to 2022-12-01,
+because 2022-11-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 2020 13:02:39 -0400
+Thu, 31 Dec 2022 13:02:39 -0400
$ date --date='-1 month' +'Last month was %B?'
-Last month was July?
+Last month was December?
$ date --date="$(date +%Y-%m-15) -1 month" +'Last month was %B!'
-Last month was June!
+Last month was November!
@end example
Also, take care when manipulating dates around clock changes such as
@@ -524,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, 2019?'' by using a date beginning with
+shows 6:30am on October 31, 2022?'' 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" 2019-10-31 06:30'
-Sun Oct 31 01:30:00 EDT 2019
+$ date --date='TZ="Europe/Paris" 2022-10-31 06:30'
+Mon Oct 31 01:30:00 EDT 2022
@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{2019-10-31
+to @samp{Europe/Paris} rules, treating the string @samp{2022-11-14
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 2019, but this example refers to a brief Halloween period
+New York in 2022, 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.38.1
