[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: mandoc(1) warning in tzfile(5) regarding //
From: |
Paul Eggert |
Subject: |
Re: mandoc(1) warning in tzfile(5) regarding // |
Date: |
Wed, 8 Mar 2023 13:54:45 -0800 |
User-agent: |
Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101 Thunderbird/102.8.0 |
On 3/8/23 11:44, Alejandro Colomar wrote:
Would you mind sending your patches inline, if it's not much
cumbersome to you?
Sure, today I resent that other patch inline.
I still see the warning.
Oh well. Looks like a mandoc bug; maybe it can't tell that we're in a
macro so '\\' is OK, indeed expected.
I guess you referred to the TH line in the tzselect.8 page, which
doesn't show a date, has the project and (unreleased) version in
the 4th field, and has no 5th field.
Yes.
-.TH tzfile 5 2022-09-09 Linux "Linux Programmer's Manual"
+.TH tzfile 5 2023-03-07 Linux "Linux Programmer's Manual"
I don't like this TH line
That's the Linux man page's .TH line not the tzdb .TH line. I merely
used the format that was already there. The tzdb .TH line is merely ".TH
TZFILE 5". So you can edit the man-pages .TZ line any way you like.
Come to think of it, the tzdb man pages aren't systematic about .TH line
capitalization. Some use uppercase (the style in 7th Edition Unix), some
lowercase (more common in recent decades). Let's go with lowercase.
Proposed tzdb patch attached, and installed in the development
repository. If mandoc complains about this, that's mandoc's problem not
ours.
Would you mind specifying your own project and version upstream
so I could keep them untouched?
I can see problems with that. First, it's tzdb commit
12b48faf10c265ee3ea1aad8cdb5c8239eea65a0 and I doubt whether man page
readers want to see that. We do have a mechanism for converting that
commit ID to the quasi version number "2022g-64-g12b48fa" but this quasi
version number depends on development history not merely on current
state, so it has its own issues.
Second, non-Linux installations of man pages could see bad output with a
.TH line like this:
.TH tzfile 5 "tzdb commit 12b48faf10c265ee3ea1aad8cdb5c8239eea65a0"
"Time Zone Database"
On Solaris 10, "nroff -man tzfile.5" generates the following footer line
for that:
Last change: tzdb commit 12b48faf10c265ee3ea1aad8cdb5c8239eea65a1
This ends in "a1" not the correct "a0", and the "Time Zone Database" has
vanished. On Fedora 37 and macOS the footer line isn't much better:
Time Zone Dattzdbecommit 12b48faf10c265ee3ea1aad8cdb5c8239eea65a0
tzfile(5)
Nor does it look good on AIX 7.1:
Time Zone Database (tzdb commit 12b48faf10c265ee3ea1aad8cdb5tzfile(5)
Third, Git doesn't automatically put version numbers into working files,
like SCCS does. So it'll be a pain to generate those numbers
automatically, with our current approach of committing the man page
files directly into the repository. As you suggest, we'd have to rename
the man page files to something else in the repository, and have 'make'
(or some script) generate the version number.
Although some (perhaps all) of this is doable, it'd take some time to
implement and it'd probably affect downstream users who currently fetch
the man pages directly from the repository, so it wouldn't be as simple
as the attached patch.
I'd also like if you specified the last-modified date when you
make a release,
Also doable, but as we don't do that now even for programs like 'zdump'
it'd be an even bigger lift.
.TH tzselect 8 (date) "Linux man-pages (unreleased)"
And don't really like this one either, since it looks like
the Linux man-pages is the upstream of the page, and it's not.
I probably changed this also by accident in some scripted patch.
I realized and avoided it for tzfile.5, but forgot about this
one :/.
That's the man-pages .TZ line, not the upstream one, so please feel free
to modify it any way you like.
Another way the files differ is in the lack of
"%%%LICENSE_START(PUBLIC_DOMAIN)" and "%%%LICENSE_END" boilerplate
upstream. I've been reluctant to do that upstream since I expect each
downstream user has its own format for comments regarding licensing,
SBOM, SSDF, SCA, and so forth (and if you don't know what those acronyms
mean then I envy you :-).
0001-Use-lowercase-.TH-titles.patch
Description: Text Data