Re: mandoc(1) warning in tzfile(5) regarding //

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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


[Index of Archives]     [Kernel Documentation]     [Netdev]     [Linux Ethernet Bridging]     [Linux Wireless]     [Kernel Newbies]     [Security]     [Linux for Hams]     [Netfilter]     [Bugtraq]     [Yosemite News]     [MIPS Linux]     [ARM Linux]     [Linux RAID]     [Linux Admin]     [Samba]

  Powered by Linux