parse-datetime: Update documentation regarding non-Gregorian calendars.

* doc/parse-datetime.texi (General date syntax): Mention that date
syntax should use the Gregorian calendar. Change examples that use %Y
to use LC_ALL=C, so that they work even for users in Thailand, Iran, or
Ethiopia.

diff --git a/ChangeLog b/ChangeLog
index b342c34550c6899cda70dffedb7eaeae6a48f3f5..ecb8923da49ed81c86fe64e1a0136e8194bf8c7f 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+2025-07-17  Bruno Haible  <bruno@clisp.org>
+
+       parse-datetime: Update documentation regarding non-Gregorian calendars.
+       * doc/parse-datetime.texi (General date syntax): Mention that date
+       syntax should use the Gregorian calendar. Change examples that use %Y
+       to use LC_ALL=C, so that they work even for users in Thailand, Iran, or
+       Ethiopia.
+
 2025-07-17  Bruno Haible  <bruno@clisp.org>
 
        Fix sb_dupfree(), sbr_dupfree() on an empty buffer.

diff --git a/doc/parse-datetime.texi b/doc/parse-datetime.texi
index 3b0935b087d5214143faf7b70e802a0838add364..51c6f741486dba3e00ea01ea0bf6af0f445cd661 100644 (file)
--- a/doc/parse-datetime.texi
+++ b/doc/parse-datetime.texi
@@ -111,27 +111,34 @@ In the current implementation, only English is supported for words and
 abbreviations like @samp{AM}, @samp{DST}, @samp{EST}, @samp{first},
 @samp{January}, @samp{Sunday}, @samp{tomorrow}, and @samp{year}.
 
+@cindex calendar, in dates
+In the current implementation, only the Gregorian calendar is supported,
+regardless of the locale.
+
 @cindex language, in dates
+@cindex calendar, in dates
 @cindex time zone item
 The output of the @command{date} command
 is not always acceptable as a date string,
-not only because of the language problem, but also because there is no
+not only because of the language problem and of the calendar problem,
+but also because there is no
 standard meaning for time zone items like @samp{IST}@.  When using
 @command{date} to generate a date string intended to be parsed later,
-specify a date format that is independent of language and that does not
-use time zone items other than @samp{UTC} and @samp{Z}@.  Here are some
-ways to do this:
+specify a date format that is independent of language,
+that uses the Gregorian calendar,
+and that does not use time zone items other than @samp{UTC} and @samp{Z}@.
+Here are some ways to do this:
 
 @example
 $ LC_ALL=C TZ=UTC0 date
 Tue Nov 15 02:02:42 UTC 2022
-$ TZ=UTC0 date +'%Y-%m-%d %H:%M:%SZ'
+$ LC_ALL=C TZ=UTC0 date +'%Y-%m-%d %H:%M:%SZ'
 2022-11-15 02:02:42Z
 $ date --rfc-3339=ns  # --rfc-3339 is a GNU extension.
 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.
+$ LC_ALL=C date +'%Y-%m-%d %H:%M:%S %z'  # %z is a GNU extension.
 2022-11-14 21:02:42 -0500
 $ date +'@@%s.%N'  # %s and %N are GNU extensions.
 @@1668477762.692722128