[tz] zdump man page misleading?

[Brian Inglis]

On 2021-02-25 02:06, Martin Burnicki via tz wrote:
> the zdump.8.txt file generated from the current github code says:
> 
> -c [loyear,]hiyear
> ...
> Cutoffs are at the start of each year, where the lower-bound timestamp is 
> *exclusive* and the upper is *inclusive*; for example, -c 1970,2070 selects 
> transitions after 1970-01-01 00:00:00 UTC and on or before 2070-01-01 00:00:00 
> UTC.  The default cutoff is -500,2500.
> 
> and
> 
> $ ./zdump -V -c 2021,2022 Europe/Berlin
> Europe/Berlin  Sun Mar 28 00:59:59 2021 UT = Sun Mar 28 01:59:59 ..
> Europe/Berlin  Sun Mar 28 01:00:00 2021 UT = Sun Mar 28 03:00:00 ..
> Europe/Berlin  Sun Oct 31 00:59:59 2021 UT = Sun Oct 31 02:59:59 ..
> Europe/Berlin  Sun Oct 31 01:00:00 2021 UT = Sun Oct 31 02:00:00 ..
> 
> (lines shorted to avoid line-wrapping)
> 
> So the lower year is *inclusive* and the upper year is *exclusive*, and from my 
> understanding these words should be swapped in the text of the man page. Or am I 
> missing something?
> 
> If I'm correct, should I provide a patch or pull request for the git repo?

You're right, it appears misleading and is unintuitive, but has been the same 
since it was partially clarified in 2014h/i.

The -c year range is inclusive of the first optional year, excluding the first 
second of that year in UT excluding leap seconds (presumably POSIX time), but 
exclusive of the required second year, but inclusive of the first second of that 
year in UT excluding leap seconds (presumably POSIX time).

For -t timestamps, the first optional timestamp is excluded and the second is 
excluded I believe.

It would be better if both years/timestamps were *inclusive*, as that is what 
most users expect in ranges e.g. 1970 thru 2021, as exemplified in many 
languages which include ranges, as opposed to C loops which are choosey about 
their friends.

When you have to keep clarifying documentation because of misunderstandings or 
misinterpretations, or having to implement work arounds, then the design, 
implementation, or interface may be based on poor or inadequate assumptions, and 
the interface, implementation, or design should be corrected to match normal 
assumptions, allowing the documentation to be simplified to match normal 
assumptions, and the work arounds to be simplified or eliminated, in my opinion.

So both -c years should be inclusive from start to end and so should -t timestamps.

As zdump produces no default output for $TZ or /etc/localtime, my interactive 
zdump interface for my usual use case is now:

$ which zdump
zdump ()
{
     local z=${1:-${TZ:-/etc/localtime}} y=$(date +%Y);
     local e=$(($y+1)) b p l t;
     for b in $y 1970 1900 1752;
     do
         p=$(command /usr/bin/zdump -Vc$b,$e $z);
         [ -n "$p" ] && break;
     done;
     l=${p##*$'\n'};
     t=${l##*[012][0-9]:[0-5][0-9]:[0-6][0-9] };
     b=${t:0:4};
     [ $b -lt $y ] && p=$(command /usr/bin/zdump -Vc$b,$e $z);
     echo "$p"
}

which produces a dump for transitions enclosing the current year:

$ zdump
America/Edmonton  Sun Mar 14 08:59:59 2021 UT = Sun Mar 14 01:59:59 2021 MST 
isdst=0 gmtoff=-25200
America/Edmonton  Sun Mar 14 09:00:00 2021 UT = Sun Mar 14 03:00:00 2021 MDT 
isdst=1 gmtoff=-21600
America/Edmonton  Sun Nov  7 07:59:59 2021 UT = Sun Nov  7 01:59:59 2021 MDT 
isdst=1 gmtoff=-21600
America/Edmonton  Sun Nov  7 08:00:00 2021 UT = Sun Nov  7 01:00:00 2021 MST 
isdst=0 gmtoff=-25200

I may add options if I see more need, but for now use the command prefix or 
explicit /usr/bin/zdump path for other use cases:

$ command zdump
$ command zdump $TZ
America/Edmonton  Thu Feb 25 14:13:39 2021 MST
$ command zdump /etc/localtime
/etc/localtime  Thu Feb 25 14:13:42 2021 MST

although the output appears to ignore all locale settings:

$ date; date +%c
2021 Feb 25 Thu 14:13:48 MST
2021 Feb 25 Thu 14:13:48-0700

which to me should only be done if using ISO style formats e.g. %F\ %T%z.

Same results regardless of system and zdump build:

$ command zdump --version
zdump (Debian GLIBC 2.28-10) 2.28
$ command zdump --version
zdump (tzcode) 2021a

although other distros are more selective about incorporating tzcode changes.

-- 
Take care. Thanks, Brian Inglis, Calgary, Alberta, Canada

This email may be disturbing to some readers as it contains
too much technical detail. Reader discretion is advised.
[Data in binary units and prefixes, physical quantities in SI.]