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=<output_tz> date -d 'TZ="<input_tz>" <datestr>'

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.