[Top][All Lists]

[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.


-.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 :-).

Attachment: 0001-Use-lowercase-.TH-titles.patch
Description: Text Data

reply via email to

[Prev in Thread] Current Thread [Next in Thread]