[tz] zdump man page misleading?

[Martin Burnicki]

Brian Inglis via tz wrote:
> 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.

Cool, I just started playing around with zdump and wasn't aware of these 
details.

Paul, thanks for applying the patch!

Martin
-- 
Martin Burnicki

Senior Software Engineer

MEINBERG Funkuhren GmbH & Co. KG
Email: martin.burnicki at meinberg.de
Phone: +49 5281 9309-414
Linkedin: https://www.linkedin.com/in/martinburnicki/

Lange Wand 9, 31812 Bad Pyrmont, Germany
Amtsgericht Hannover 17HRA 100322
Geschäftsführer/Managing Directors: Günter Meinberg, Werner Meinberg, 
Andre Hartmann, Heiko Gerstung
Websites: https://www.meinberg.de  https://www.meinbergglobal.com
Training: https://www.meinberg.academy
-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 6034 bytes
Desc: not available
URL: <http://mm.icann.org/pipermail/tz/attachments/20210226/a67ed3cc/attachment.bin>