manual pages in tzdb

manual pages in tzdb

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 2182 bytes --]

Hi Paul,

I had in mind something: I would like to cherry-pick all tzdb's commits
that affect manual pages into the Linux man-pages git repository,
instead of just pasting here snapshots of your manual pages.

For that to work, we'd need to agree on a path inside the repository (or
I could manually --or with a script-- edit each commit, which would be
combersome, and I'd rather avoid).

What do you think of moving the pages in the tzdb repository into
man/man*/ directories?  I see your repository is perfectly flat, so I
don't know if there are strong reasons for that, or if it's just
innertia.

To be explicit, this is what I'd do in tzdb.git:

	diff --git a/date.1 b/man/man1/date.1
	similarity index 100%
	rename from date.1
	rename to man/man1/date.1
	diff --git a/newctime.3 b/man/man3/newctime.3
	similarity index 100%
	rename from newctime.3
	rename to man/man3/newctime.3
	diff --git a/newstrftime.3 b/man/man3/newstrftime.3
	similarity index 100%
	rename from newstrftime.3
	rename to man/man3/newstrftime.3
	diff --git a/newtzset.3 b/man/man3/newtzset.3
	similarity index 100%
	rename from newtzset.3
	rename to man/man3/newtzset.3
	diff --git a/time2posix.3 b/man/man3/time2posix.3
	similarity index 100%
	rename from time2posix.3
	rename to man/man3/time2posix.3
	diff --git a/tzfile.5 b/man/man5/tzfile.5
	similarity index 100%
	rename from tzfile.5
	rename to man/man5/tzfile.5
	diff --git a/tzselect.8 b/man/man8/tzselect.8
	similarity index 100%
	rename from tzselect.8
	rename to man/man8/tzselect.8
	diff --git a/zdump.8 b/man/man8/zdump.8
	similarity index 100%
	rename from zdump.8
	rename to man/man8/zdump.8
	diff --git a/zic.8 b/man/man8/zic.8
	similarity index 100%
	rename from zic.8
	rename to man/man8/zic.8

If we do that, then my idea would be to do

	$ git remote add tzdb git@github.com:eggert/tz.git

in my Linux man-pages local repo, and cherry-pick commits '-- man/' from
time to time.

Does that sound good to you?

Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es/>
A client is hiring kernel driver, mm, and/or crypto developers;
contact me if interested.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: manual pages in tzdb

[Paul Eggert]

On 2024-05-08 09:24, Alejandro Colomar wrote:
> What do you think of moving the pages in the tzdb repository into
> man/man*/ directories?  I see your repository is perfectly flat, so I
> don't know if there are strong reasons for that, or if it's just
> innertia.

To be fair, inertia itself is a strong reason....

I wouldn't mind renaming the man pages, though I'd get rid of the "new" 
prefixes while we're at it. However, I worry that other downstream users 
would be adversely affected. Perhaps others could chime in.

Re: [tz] manual pages in tzdb

[Philip Paeps]

On 2024-05-09 00:57:38 (+0800), Paul Eggert via tz wrote:
> On 2024-05-08 09:24, Alejandro Colomar wrote:
>> What do you think of moving the pages in the tzdb repository into
>> man/man*/ directories?  I see your repository is perfectly flat, so I
>> don't know if there are strong reasons for that, or if it's just
>> innertia.
>
> To be fair, inertia itself is a strong reason....
>
> I wouldn't mind renaming the man pages, though I'd get rid of the 
> "new" prefixes while we're at it. However, I worry that other 
> downstream users would be adversely affected. Perhaps others could 
> chime in.

I don't mind the idea, but we (FreeBSD) would have to rework some of our 
tooling.  I suspect other non-Linux distributions are similarly 
affected.

Thinking out loud: would it make sense to rename the files in the Git 
repository, but keep the tarballs flat?  I suspect most downstreams 
consume the tarballs rather than the Git repository.

Philip

Re: [tz] manual pages in tzdb

[Paul Eggert]

On 2024-05-08 20:36, Philip Paeps wrote:
> Thinking out loud: would it make sense to rename the files in the Git 
> repository, but keep the tarballs flat?  I suspect most downstreams 
> consume the tarballs rather than the Git repository.

You may be right. My impression is that some people do it either way. 
There would be some pain in the long run if the two methods put files in 
different places.

We could arrange for the tarballs to contain two hard links or copies of 
the renamed files, one with the old name and one with the new.

All in all, though, I'm inclined to think that if we're going to rename 
the files, we should just do it. The backward compatibility concerns are 
less with documentation location than with data or code.

Re: [tz] manual pages in tzdb

[Philip Paeps]

On 2024-05-09 11:41:40 (+0800), Paul Eggert wrote:
> On 2024-05-08 20:36, Philip Paeps wrote:
>> Thinking out loud: would it make sense to rename the files in the Git 
>> repository, but keep the tarballs flat?  I suspect most downstreams 
>> consume the tarballs rather than the Git repository.
>
> You may be right. My impression is that some people do it either way. 
> There would be some pain in the long run if the two methods put files 
> in different places.
>
> We could arrange for the tarballs to contain two hard links or copies 
> of the renamed files, one with the old name and one with the new.

That would likely cause more confusion.

> All in all, though, I'm inclined to think that if we're going to 
> rename the files, we should just do it. The backward compatibility 
> concerns are less with documentation location than with data or code.

I agree with this.  If something is done, it should be done once.

But "doing nothing" also works.  So far, the only request for change has 
been from a consumer of documentation, not code or data.

Re: [tz] manual pages in tzdb

[Dag-Erling Smørgrav]

Philip Paeps via tz <tz@iana.org> writes:
> Paul Eggert via tz <tz@iana.org> writes:
> > I wouldn't mind renaming the man pages, though I'd get rid of the
> > "new" prefixes while we're at it. However, I worry that other
> > downstream users would be adversely affected. Perhaps others could
> > chime in.
> I don't mind the idea, but we (FreeBSD) would have to rework some of
> our tooling.

Speaking as the FreeBSD developer who would actually be affected by the
change: it's not an issue.

DES
-- 
Dag-Erling Smørgrav - des@des.no

Re: [tz] manual pages in tzdb

[brian.inglis]

On 2024-05-08 10:57, Paul Eggert via tz wrote:
> On 2024-05-08 09:24, Alejandro Colomar wrote:
>> What do you think of moving the pages in the tzdb repository into
>> man/man*/ directories?  I see your repository is perfectly flat, so I
>> don't know if there are strong reasons for that, or if it's just
>> innertia.
> 
> To be fair, inertia itself is a strong reason....
> 
> I wouldn't mind renaming the man pages, though I'd get rid of the "new" prefixes 
> while we're at it. However, I worry that other downstream users would be 
> adversely affected. Perhaps others could chime in.

Not seeing any obvious man[1358] references in Linux distro RPM specs/builds: 
presumably rely on man-pages.

Gentoo reported https://bugs.gentoo.org/920035 sys-libs/timezone-data: installs 
man3 manpages without corresponding libraries.

Some BSDs seem to customize utilities and man pages (or use old releases) based 
on online man pages.

What about updating glibc/manual/time.texi, and are any (non-info) docs or man 
pages generated from that in any distro or downstream?

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

La perfection est atteinte                   Perfection is achieved
non pas lorsqu'il n'y a plus rien à ajouter  not when there is no more to add
mais lorsqu'il n'y a plus rien à retirer     but when there is no more to cut
                                 -- Antoine de Saint-Exupéry