Debian Bug report logs - #594219
manpages: tzfile.5 is very old, does not match current tzfile format on Debian

version graph

Package: manpages; Maintainer for manpages is Martin Schulze <joey@debian.org>; Source for manpages is src:manpages.

Reported by: Yitzchak Gale <gale@sefer.org>

Date: Tue, 24 Aug 2010 16:09:05 UTC

Severity: normal

Tags: fixed-upstream

Found in version manpages/3.05-1

Fixed in version 3.26-1

Done: Simon Paillard <spaillard@debian.org>

Bug is archived. No further changes may be made.

Toggle useless messages

View this report as an mbox folder, status mbox, maintainer mbox


Report forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>:
Bug#594219; Package manpages. (Tue, 24 Aug 2010 16:09:08 GMT) Full text and rfc822 format available.

Acknowledgement sent to Yitzchak Gale <gale@sefer.org>:
New Bug report received and forwarded. Copy sent to Martin Schulze <joey@debian.org>. (Tue, 24 Aug 2010 16:09:08 GMT) Full text and rfc822 format available.

Message #5 received at submit@bugs.debian.org (full text, mbox):

From: Yitzchak Gale <gale@sefer.org>
To: Debian Bug Tracking System <submit@bugs.debian.org>
Subject: manpages: tzfile.5 is very old, does not match current tzfile format on Debian
Date: Tue, 24 Aug 2010 19:06:13 +0300
Package: manpages
Version: 3.05-1
Severity: normal

The tzfile.5 man page is very old, from before the Version 2
format of zoneinfo files was defined. Since version 2010j
of the upstream zoneinfo files, which is the version now used
in the Debian tzdata package, the zoneinfo files are in Version 2
format. Therefore, the tzfile.5 man page is incorrect - it
does not reflect the format of the zoneinfo files on Debian
systems anymore.

Fix: please replace tzfile.5 with the version that is
included in the correct version of the tzcode tarball
from upstream. The latest upstream version is at:

ftp://elsie.nci.nih.gov/pub

But technically, we want the version that exactly corresponds
to the current version of tzcode that is used on Debian,
not the latest version from upstream.

The correct version of the tzcode tarball is probably
available in the Debian source packages somewhere,
perhaps glibc. If not, historical versions are available at:

ftp://munnari.oz.au/pub/oldtz

We currently want the one from tzcode2010j.tar.gz.

Wouldn't it make more sense for this man page to be
part of the tzdata package, so that the version of the
man page will track the file format used on Debian?

-- System Information:
Debian Release: 5.0.5
  APT prefers stable
  APT policy: (500, 'stable')
Architecture: i386 (i686)

Kernel: Linux 2.6.26-2-686 (SMP w/1 CPU core)
Locale: LANG=en_US.UTF-8, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8)
Shell: /bin/sh linked to /bin/bash

manpages depends on no packages.

manpages recommends no packages.

Versions of packages manpages suggests:
ii  konqueror [man-b 4:3.5.9.dfsg.1-6+lenny1 KDE's advanced file manager, web b
ii  man-db [man-brow 2.5.2-4                 on-line manual pager

-- no debconf information




Information forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>:
Bug#594219; Package manpages. (Sun, 29 Aug 2010 13:33:38 GMT) Full text and rfc822 format available.

Acknowledgement sent to mtk.manpages@gmail.com:
Extra info received and forwarded to list. Copy sent to Martin Schulze <joey@debian.org>. (Sun, 29 Aug 2010 13:33:38 GMT) Full text and rfc822 format available.

Message #10 received at 594219@bugs.debian.org (full text, mbox):

From: Michael Kerrisk <mtk.manpages@gmail.com>
To: Yitzchak Gale <gale@sefer.org>, 594219@bugs.debian.org
Cc: Andries Brouwer <andries.brouwer@cwi.nl>
Subject: Re: Bug#594219: manpages: tzfile.5 is very old, does not match current tzfile format on Debian
Date: Sun, 29 Aug 2010 15:26:27 +0200
Hello Yitzchak,

On Tue, Aug 24, 2010 at 6:06 PM, Yitzchak Gale <gale@sefer.org> wrote:
> Package: manpages
> Version: 3.05-1
> Severity: normal
>
> The tzfile.5 man page is very old, from before the Version 2
> format of zoneinfo files was defined. Since version 2010j
> of the upstream zoneinfo files, which is the version now used
> in the Debian tzdata package, the zoneinfo files are in Version 2
> format. Therefore, the tzfile.5 man page is incorrect - it
> does not reflect the format of the zoneinfo files on Debian
> systems anymore.
>
> Fix: please replace tzfile.5 with the version that is
> included in the correct version of the tzcode tarball
> from upstream. The latest upstream version is at:
>
> ftp://elsie.nci.nih.gov/pub
>
> But technically, we want the version that exactly corresponds
> to the current version of tzcode that is used on Debian,
> not the latest version from upstream.
>
> The correct version of the tzcode tarball is probably
> available in the Debian source packages somewhere,
> perhaps glibc. If not, historical versions are available at:
>
> ftp://munnari.oz.au/pub/oldtz
>
> We currently want the one from tzcode2010j.tar.gz.
>
> Wouldn't it make more sense for this man page to be
> part of the tzdata package, so that the version of the
> man page will track the file format used on Debian?

I'm the upstream man-pages maintainer, so can't speak about what
Debian does. It may be possible that Andries, who was maintainer back
then, remembers something. Here's what I piece together.

The upstream man-pages package contains tzfile.5 and tzselect.8 manual
pages, and I am guessing that these are shipped by Debian. These pages
were added to the man-pages set many years before my time as
maintainer, back in release 1.23 (i.e., in the 1990s). Back then, the
Announce file contained this text:

[[
section 5 and 8 man pages for the timezone utilities.

[The latter were taken from ftp://elsie.nci.nih.gov/pub/tzcode1998h.tar.gz.
Nowadays the timezone code, data and programs described in these manpages
come with glibc, but the manpages don't.  Stupid GNUheads.
GNU seems to strongly dislike man pages, and either ships no man page at all,
as e.g. for diff, or ships very ugly man pages, mechanically generated
from some other format, like a help text. In a few cases otherwise
good man pages have been spoilt by inserting the message that one
should rather read the info file, even in cases where in fact
the info file is less informative and less correct.
In the timezone case the man pages were thrown out, but no info file
was created: "better a user without docs than a user reading a man page".
As long as this situation lasts we also ship some Section 1 man pages here.]
]]

Checking ftp://elsie.nci.nih.gov/pub, I see that it contains tzfile.5
and tzselect.8 manual pages.

The tzfile.5 page at elsie contains new info that isn't in the
man-pages version of this page. On the other hand, there seems to be
no content difference in the tzselect.8 pages.

At this stage, I am not sure whether the correct course of action for
me upstream is

a) Remove tzfile.5 and tzselect.8 from the man-pages set and tell
downstream distributions to get the pages from the tzcode package.

b) Update the tzfile.5 page in man-pages, to add the new text in the
elsie version of the page. Obviously, this solution is redundant, and
prone to bit rot, but it is convenient for downstream folk, since they
don't need to take any action. On the other hand, it requires
verifying that the tzfile.5 changes correspond to current glibc
reality.

c) Do nothing.

I welcome thoughts on this.

Cheers,

Michael

> -- System Information:
> Debian Release: 5.0.5
>  APT prefers stable
>  APT policy: (500, 'stable')
> Architecture: i386 (i686)
>
> Kernel: Linux 2.6.26-2-686 (SMP w/1 CPU core)
> Locale: LANG=en_US.UTF-8, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8)
> Shell: /bin/sh linked to /bin/bash
>
> manpages depends on no packages.
>
> manpages recommends no packages.
>
> Versions of packages manpages suggests:
> ii  konqueror [man-b 4:3.5.9.dfsg.1-6+lenny1 KDE's advanced file manager, web b
> ii  man-db [man-brow 2.5.2-4                 on-line manual pager
>
> -- no debconf information
>
>
>
>



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface" http://blog.man7.org/




Information forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>:
Bug#594219; Package manpages. (Sun, 29 Aug 2010 14:24:03 GMT) Full text and rfc822 format available.

Acknowledgement sent to gale@sefer.org:
Extra info received and forwarded to list. Copy sent to Martin Schulze <joey@debian.org>. (Sun, 29 Aug 2010 14:24:03 GMT) Full text and rfc822 format available.

Message #15 received at 594219@bugs.debian.org (full text, mbox):

From: Yitzchak Gale <gale@sefer.org>
To: mtk.manpages@gmail.com
Cc: 594219@bugs.debian.org, Andries Brouwer <andries.brouwer@cwi.nl>
Subject: Re: Bug#594219: manpages: tzfile.5 is very old, does not match current tzfile format on Debian
Date: Sun, 29 Aug 2010 17:21:26 +0300
Hi Michael,


> The upstream man-pages package contains tzfile.5 and tzselect.8 manual
> pages, and I am guessing that these are shipped by Debian.

No, only tzfile.5. Debian ships its own version of tzselect.8.

> Checking ftp://elsie.nci.nih.gov/pub, I see that...
> the tzfile.5 page at elsie contains new info that isn't in the
> man-pages version of this page.
> At this stage, I am not sure whether the correct course of action for
> me upstream is
> a) Remove tzfile.5 and tzselect.8 from the man-pages
> b) Update the tzfile.5 page in man-pages...
> it requires verifying that the tzfile.5 changes correspond to current glibc
> reality.
> c) Do nothing.

Obviously it's up to you, but if you decide on (b),
I think you're OK with updating tzfile.5.
The newer version is completely backward
compatible - it describes both Version 1 format
and Version 2 format zoneinfo files. So even on
systems that don't support Version 2 yet, the man page
is correct and useful. And even the most stable systems
are likely to upgrade, because otherwise their timezone
information will be out of date; live zoneinfo files are
shipping in Version 2 format now. As for bitrot,
this man page seems to change about once every decade
or two, and even then the upstream authors are likely to
continue being zealous about backwards compatibility
due to the nature of this system.

For Debian, the right thing to do technically is to
move this man page to the tzdata or glibc package,
but in practice I doubt it's worth the effort. So it would
be kind of you to continue to support it upstream.

Thanks much,
Yitz




Information forwarded to debian-bugs-dist@lists.debian.org, Martin Schulze <joey@debian.org>:
Bug#594219; Package manpages. (Tue, 31 Aug 2010 07:42:14 GMT) Full text and rfc822 format available.

Acknowledgement sent to mtk.manpages@gmail.com:
Extra info received and forwarded to list. Copy sent to Martin Schulze <joey@debian.org>. (Tue, 31 Aug 2010 07:42:14 GMT) Full text and rfc822 format available.

Message #20 received at 594219@bugs.debian.org (full text, mbox):

From: Michael Kerrisk <mtk.manpages@gmail.com>
To: gale@sefer.org
Cc: 594219@bugs.debian.org, Andries Brouwer <andries.brouwer@cwi.nl>, control@bugs.debian.org
Subject: Re: Bug#594219: manpages: tzfile.5 is very old, does not match current tzfile format on Debian
Date: Tue, 31 Aug 2010 08:00:55 +0200
tags 594219 fixed-upstream
thanks

On Sun, Aug 29, 2010 at 4:21 PM, Yitzchak Gale <gale@sefer.org> wrote:
> Hi Michael,
>
>
>> The upstream man-pages package contains tzfile.5 and tzselect.8 manual
>> pages, and I am guessing that these are shipped by Debian.
>
> No, only tzfile.5. Debian ships its own version of tzselect.8.
>
>> Checking ftp://elsie.nci.nih.gov/pub, I see that...
>> the tzfile.5 page at elsie contains new info that isn't in the
>> man-pages version of this page.
>> At this stage, I am not sure whether the correct course of action for
>> me upstream is
>> a) Remove tzfile.5 and tzselect.8 from the man-pages
>> b) Update the tzfile.5 page in man-pages...
>> it requires verifying that the tzfile.5 changes correspond to current glibc
>> reality.
>> c) Do nothing.
>
> Obviously it's up to you, but if you decide on (b),
> I think you're OK with updating tzfile.5.
> The newer version is completely backward
> compatible - it describes both Version 1 format
> and Version 2 format zoneinfo files. So even on
> systems that don't support Version 2 yet, the man page
> is correct and useful. And even the most stable systems
> are likely to upgrade, because otherwise their timezone
> information will be out of date; live zoneinfo files are
> shipping in Version 2 format now. As for bitrot,
> this man page seems to change about once every decade
> or two, and even then the upstream authors are likely to
> continue being zealous about backwards compatibility
> due to the nature of this system.
>
> For Debian, the right thing to do technically is to
> move this man page to the tzdata or glibc package,
> but in practice I doubt it's worth the effort. So it would
> be kind of you to continue to support it upstream.

Thanks for the input Yitz. I decided on (b), and applied the following
patch, for man-pages-3.26.

Cheers,

Michael

--- a/man5/tzfile.5
+++ b/man5/tzfile.5
@@ -11,7 +11,9 @@ The timezone information files used by
 .BR tzset (3)
 begin with the magic characters "TZif" to identify then as
 timezone information files,
-followed by sixteen bytes reserved for future use,
+followed by a character identifying the version of the file's format
+(as of 2005, either an ASCII NUL ('\\0') or a '2')
+followed by fifteen bytes containing zeroes reserved for future use,
 followed by six four-byte values of type
 .IR long ,
 written in a "standard" byte order
@@ -57,7 +59,9 @@ each one tells which of the different types of
"local time" types
 described in the file is associated with the same-indexed transition time.
 These values serve as indices into an array of
 .I ttinfo
-structures that appears next in the file;
+structures (with
+.I tzh_typecnt
+entries) that appear next in the file;
 these structures are defined as follows:
 .in +4n
 .sp
@@ -121,7 +125,7 @@ were specified as UTC or local time,
 and are used when a timezone file is used in handling POSIX-style
 timezone environment variables.
 .PP
-.I Localtime
+.BR localtime (3)
 uses the first standard-time
 .I ttinfo
 structure in the file
@@ -132,3 +136,15 @@ if either
 .I tzh_timecnt
 is zero or the time argument is less than the first transition time recorded
 in the file.
+.PP
+For version-2-format timezone files,
+the above header and data is followed by a second header and data,
+identical in format except that
+eight bytes are used for each transition time or leap-second time.
+After the second header and data comes a newline-enclosed,
+POSIX-TZ-environment-variable-style string for use in handling instants
+after the last transition time stored in the file
+(with nothing between the newlines if there is no POSIX representation for
+such instants).
+.SH SEE ALSO
+.BR ctime (3)


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/




Added tag(s) fixed-upstream. Request was from Michael Kerrisk <mtk.manpages@gmail.com> to control@bugs.debian.org. (Tue, 31 Aug 2010 07:42:21 GMT) Full text and rfc822 format available.

Reply sent to Simon Paillard <spaillard@debian.org>:
You have taken responsibility. (Sat, 12 Feb 2011 18:30:11 GMT) Full text and rfc822 format available.

Notification sent to Yitzchak Gale <gale@sefer.org>:
Bug acknowledged by developer. (Sat, 12 Feb 2011 18:30:11 GMT) Full text and rfc822 format available.

Message #27 received at 594219-done@bugs.debian.org (full text, mbox):

From: Simon Paillard <spaillard@debian.org>
To: 594219-done@bugs.debian.org
Subject: Re: Bug#594219: manpages: tzfile.5 is very old, does not match current tzfile format on Debian
Date: Sat, 12 Feb 2011 19:27:00 +0100
Version: 3.26-1

On Tue, Aug 31, 2010 at 08:00:55AM +0200, Michael Kerrisk wrote:
> On Sun, Aug 29, 2010 at 4:21 PM, Yitzchak Gale <gale@sefer.org> wrote:
> >> The upstream man-pages package contains tzfile.5 and tzselect.8 manual
> >> pages, and I am guessing that these are shipped by Debian.
> >
> > No, only tzfile.5. Debian ships its own version of tzselect.8.
> >
> >> Checking ftp://elsie.nci.nih.gov/pub, I see that...
> >> the tzfile.5 page at elsie contains new info that isn't in the
> >> man-pages version of this page.
> >> At this stage, I am not sure whether the correct course of action for
> >> me upstream is
> >> a) Remove tzfile.5 and tzselect.8 from the man-pages
> >> b) Update the tzfile.5 page in man-pages...
> >> it requires verifying that the tzfile.5 changes correspond to current glibc
> >> reality.
> >> c) Do nothing.
[..] 
> Thanks for the input Yitz. I decided on (b), and applied the following
> patch, for man-pages-3.26.

Thanks Michael, the patch is present in Debian since 3.26-1. 

-- 
Simon Paillard




Bug archived. Request was from Debbugs Internal Request <owner@bugs.debian.org> to internal_control@bugs.debian.org. (Sun, 13 Mar 2011 07:32:19 GMT) Full text and rfc822 format available.

Send a report that this bug log contains spam.


Debian bug tracking system administrator <owner@bugs.debian.org>. Last modified: Mon Apr 21 15:53:52 2014; Machine Name: buxtehude.debian.org

Debian Bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.