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 :-).From 393ad035dc20c14e43ff33435552290b0db5b5e8 Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@xxxxxxxxxxx>
Date: Wed, 8 Mar 2023 13:14:57 -0800
Subject: [PROPOSED] Use lowercase .TH titles
---
newctime.3 | 2 +-
newstrftime.3 | 2 +-
newtzset.3 | 2 +-
tzfile.5 | 2 +-
tzselect.8 | 2 +-
5 files changed, 5 insertions(+), 5 deletions(-)
diff --git a/newctime.3 b/newctime.3
index 0860151..70d8e54 100644
--- a/newctime.3
+++ b/newctime.3
@@ -1,6 +1,6 @@
.\" This file is in the public domain, so clarified as of
.\" 2009-05-17 by Arthur David Olson.
-.TH NEWCTIME 3
+.TH newctime 3
.SH NAME
asctime, ctime, difftime, gmtime, localtime, mktime \- convert date and time
.SH SYNOPSIS
diff --git a/newstrftime.3 b/newstrftime.3
index d5d8ee1..75d88c8 100644
--- a/newstrftime.3
+++ b/newstrftime.3
@@ -35,7 +35,7 @@
.\" from: @(#)strftime.3 5.12 (Berkeley) 6/29/91
.\" $Id: strftime.3,v 1.4 1993/12/15 20:33:00 jtc Exp $
.\"
-.TH NEWSTRFTIME 3
+.TH newstrftime 3
.SH NAME
strftime \- format date and time
.SH SYNOPSIS
diff --git a/newtzset.3 b/newtzset.3
index 086152a..e16ae6b 100644
--- a/newtzset.3
+++ b/newtzset.3
@@ -1,6 +1,6 @@
.\" This file is in the public domain, so clarified as of
.\" 2009-05-17 by Arthur David Olson.
-.TH NEWTZSET 3
+.TH newtzset 3
.SH NAME
tzset \- initialize time conversion information
.SH SYNOPSIS
diff --git a/tzfile.5 b/tzfile.5
index 1bd561a..eb5d4e8 100644
--- a/tzfile.5
+++ b/tzfile.5
@@ -1,6 +1,6 @@
.\" This file is in the public domain, so clarified as of
.\" 1996-06-05 by Arthur David Olson.
-.TH TZFILE 5
+.TH tzfile 5
.SH NAME
tzfile \- timezone information
.SH DESCRIPTION
diff --git a/tzselect.8 b/tzselect.8
index 846b867..9828848 100644
--- a/tzselect.8
+++ b/tzselect.8
@@ -1,6 +1,6 @@
.\" This file is in the public domain, so clarified as of
.\" 2009-05-17 by Arthur David Olson.
-.TH TZSELECT 8
+.TH tzselect 8
.SH NAME
tzselect \- select a timezone
.SH SYNOPSIS
--
2.39.2
