bug#56524: doc: timezone offset conversion/info

[Paul Eggert]

On 7/13/22 14:31, Karl Berry wrote:

 +Simple POSIX rules like this can also specify nonzero Greenwich offsets.

Nothing about this seems "simple" to me :).


I meant "simple" in comparison to the rules like 
TZ="<-05>+5<-04>,M3.2.0/2,M11.1.0/2".


Fixed by installing the attached further patch, which also omits that 
hyphen - though it keeps another similar hyphen that you didn't mention. 
"Most style guides do advise against linking 'more' to an adjective with 
a hyphen, but most also recognize that sometimes a hyphen may be 
necessary for clarity." 
From 5336cb27ab42f27b8b8ac31982e8215fe5af6f34 Mon Sep 17 00:00:00 2001
From: Paul Eggert 
Date: Wed, 13 Jul 2022 18:54:56 -0700
Subject: [PATCH] * doc/parse-datetime.texi: Tweak wording again.

---
 doc/parse-datetime.texi | 17 ++---
 1 file changed, 10 insertions(+), 7 deletions(-)

diff --git a/doc/parse-datetime.texi b/doc/parse-datetime.texi
index 7939273691..e1ce97220a 100644
--- a/doc/parse-datetime.texi
+++ b/doc/parse-datetime.texi
@@ -551,31 +551,34 @@ location name in a @env{TZ} setting, e.g.,
 @samp{TZ=":America/New_York"}.
 
 The @samp{tz} database includes a wide variety of locations ranging
-from @samp{Arctic/Longyearbyen} to @samp{Antarctica/South_Pole}, but
+from @samp{Africa/Abidjan} to @samp{Pacific/Tongatapu}, but
 if you are at sea and have your own private time zone, or if you are
 using a non-GNU host that does not support the @samp{tz}
 database, you may need to use a POSIX rule instead.
 The previously-mentioned POSIX rule @samp{UTC0} says that the time zone
 abbreviation is @samp{UTC}, the zone is zero hours away from
 Greenwich, and there is no daylight saving time.
-Simple POSIX rules like this can also specify nonzero Greenwich offsets.
+POSIX rules can also specify nonzero Greenwich offsets.
 For example, the following shell transcript answers the question
 ``What time is it five and a half hours east of Greenwich when a clock
 seven hours west of Greenwich shows 9:50pm on July 12, 2022?''
 
 @example
-$ TZ="<+0530>-5:30" date --date='TZ="<-07>7" 2022-07-12 21:50'
+$ TZ="<+0530>-5:30" date --date='TZ="<-07>+7" 2022-07-12 21:50'
 Wed Jul 13 10:20:00 +0530 2022
 @end example
 
 @noindent
-This example uses the somewhat-confusing POSIX convention for TZ strings.
-@samp{TZ="<-07>7"} says that the time zone abbreviation is @samp{-07}
+This example uses the somewhat-confusing POSIX convention for rules.
+@samp{TZ="<-07>+7"} says that the time zone abbreviation is @samp{-07}
 and the time zone is 7 hours west of Greenwich, and
 @samp{TZ="<+0530>-5:30"} says that the time zone abbreviation is @samp{+0530}
 and the time zone is 5 hours 30 minutes east of Greenwich.
-More-complex POSIX TZ strings can specify simple daylight saving
-regimes.  @xref{TZ Variable,, Specifying the Time Zone with @code{TZ},
+Although trickier POSIX @env{TZ} settings like
+@samp{TZ="<-05>+5<-04>,M3.2.0/2,M11.1.0/2"} can specify some daylight
+saving regimes, location-based settings like
+@samp{TZ="America/New_York"} are typically simpler and more accurate
+historically.  @xref{TZ Variable,, Specifying the Time Zone with @code{TZ},
 libc, The GNU C Library}.
 
 @node Authors of parse_datetime
-- 
2.34.1

bug#56524: doc: timezone offset conversion/info

[Karl Berry]

I installed the attached patch to Gnulib 

Thanks. 

+Simple POSIX rules like this can also specify nonzero Greenwich offsets.

Nothing about this seems "simple" to me :). Anyway.

+More-complex POSIX TZ strings can specify simple daylight saving

There shouldn't be a hyphen after "More". --thanks again, karl.

bug#56524: doc: timezone offset conversion/info

[Paul Eggert]

On 7/12/22 15:57, Karl Berry wrote:


$ TZ=UTC-4 date -d 'TZ="UTC" 2022-07-24 15:00'


This doesn't mean what you want, because TZ=UTC-4 means "My time zone is 
abbreviated 'UTC', and it's four hours east of Greenwich" which is not a 
useful setting.


You're not the first person to run afoul of POSIX TZ strings, which are 
poorly designed. I installed the attached patch to Gnulib to give 
another example, which I hope clarifies things a bit. I'll cc this email 
to bug-gnulib since the problem is in Gnulib not Coreutils proper.



If the offset syntax is documented anywhere, I couldn't find it. Sorry.


It's documented in the glibc manual, and this part of the Coreutils 
manual (actually, taken from Gnulib) has a cross-reference to that.



BTW, in neither case did --debug clarify anything for me. In fact, it
confused me more, because the output seemingly did not include anything
about the offset at all, just reporting "UTC".


It'd be nice if --debug could diagnose invalid TZ settings. However, 
this would likely require glibc support along the lines of what's in 
tzcode and NetBSD (the tzalloc function).From f65d00ebacc891e57cca729041d028d07d1883bb Mon Sep 17 00:00:00 2001
From: Paul Eggert 
Date: Tue, 12 Jul 2022 17:11:26 -0700
Subject: [PATCH] parse-datetime: improve doc for TZ="<-07>7" etc.

* doc/parse-datetime.texi (Specifying time zone rules):
Give examples of POSIX TZ strings that specify UTC offsets (Bug#56524).
---
 ChangeLog   |  6 ++
 doc/parse-datetime.texi | 24 +---
 2 files changed, 27 insertions(+), 3 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index cd01e0208e..f245082aa6 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2022-07-12  Paul Eggert  
+
+	parse-datetime: improve doc for TZ="<-07>7" etc.
+	* doc/parse-datetime.texi (Specifying time zone rules):
+	Give examples of POSIX TZ strings that specify UTC offsets (Bug#56524).
+
 2022-07-10  Bruno Haible  
 
 	sigsegv: Optimize stackvma implementation for AIX 7.
diff --git a/doc/parse-datetime.texi b/doc/parse-datetime.texi
index 44305d136c..7939273691 100644
--- a/doc/parse-datetime.texi
+++ b/doc/parse-datetime.texi
@@ -554,9 +554,27 @@ The @samp{tz} database includes a wide variety of locations ranging
 from @samp{Arctic/Longyearbyen} to @samp{Antarctica/South_Pole}, but
 if you are at sea and have your own private time zone, or if you are
 using a non-GNU host that does not support the @samp{tz}
-database, you may need to use a POSIX rule instead.  Simple
-POSIX rules like @samp{UTC0} specify a time zone without
-daylight saving time; other rules can specify simple daylight saving
+database, you may need to use a POSIX rule instead.
+The previously-mentioned POSIX rule @samp{UTC0} says that the time zone
+abbreviation is @samp{UTC}, the zone is zero hours away from
+Greenwich, and there is no daylight saving time.
+Simple POSIX rules like this can also specify nonzero Greenwich offsets.
+For example, the following shell transcript answers the question
+``What time is it five and a half hours east of Greenwich when a clock
+seven hours west of Greenwich shows 9:50pm on July 12, 2022?''
+
+@example
+$ TZ="<+0530>-5:30" date --date='TZ="<-07>7" 2022-07-12 21:50'
+Wed Jul 13 10:20:00 +0530 2022
+@end example
+
+@noindent
+This example uses the somewhat-confusing POSIX convention for TZ strings.
+@samp{TZ="<-07>7"} says that the time zone abbreviation is @samp{-07}
+and the time zone is 7 hours west of Greenwich, and
+@samp{TZ="<+0530>-5:30"} says that the time zone abbreviation is @samp{+0530}
+and the time zone is 5 hours 30 minutes east of Greenwich.
+More-complex POSIX TZ strings can specify simple daylight saving
 regimes.  @xref{TZ Variable,, Specifying the Time Zone with @code{TZ},
 libc, The GNU C Library}.
 
-- 
2.34.1

bug#56524: doc: timezone offset conversion/info

[Karl Berry]

Suppose I have a date in UTC, and I want to "convert" it to a given UTC
offset, say UTC-4. Based on the date --help msg and examples, etc., I
was under the impression that the idiom is 
  TZ= date -d 'TZ="" '

Thus, in my case:
$ TZ=UTC-4 date -d 'TZ="UTC" 2022-07-24 15:00'

The output is:
Sun Jul 24 19:00:00 UTC 2022

It adds 4 hours instead of subtracting. Why? I'm probably missing
something completely obvious, but maybe the doc could explain this.


If I use a tz name that is currently UTC-4, it subtracts as expected:
$ TZ=America/New_York date -d 'TZ="UTC" 2022-07-24 15:00'
Sun Jul 24 11:00:00 EDT 2022

Also, if I interchange the input/output tz settings, it subtracts as
expected:
$ TZ=UTC date -d 'TZ="UTC-4" 2022-07-24 15:00'
Sun Jul 24 11:00:00 UTC 2022


Overall, I suggest another example in the "Examples of date" node.
I know UTC offsets are often not the best thing to be using, but
sometimes that's the data we're given and we have to work with it.


Related: I also suggest explicitly saying how to specify UTC offsets,
because it is not clear. For one, apparently UTC+0430 is invalid since
it doesn't affect the output (no error message, which I guess is
standard):

$ TZ=UTC+0430 date -d 'TZ="UTC" 2022-07-24 15:00'
Sat Jul 23 15:00:00 UTC 2022

whereas with a colon it works as expected (well, given the above, that
it subtracts with a positive offset):
$ TZ=UTC+04:30 date -d 'TZ="UTC" 2022-07-24 15:00'
Sun Jul 24 10:30:00 UTC 2022

If the offset syntax is documented anywhere, I couldn't find it. Sorry.

BTW, in neither case did --debug clarify anything for me. In fact, it
confused me more, because the output seemingly did not include anything
about the offset at all, just reporting "UTC".

This is with coreutils 8.30 (from Alma Linux 8) on x86_64, though I
doubted that it was version-dependent, so confess I didn't try the
latest release. --thanks, karl.