[PATCH] parse-datetime: improve doc formatting, timeliness

[Paul Eggert]

* 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  <eggert@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  <simon@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