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

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

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 1603 bytes --]

Hi Paul, Branden,

I don't remember if we covered this bit in the discussions we had
a few months ago.  I'm seeing a couple of warnings from mandoc(1)
in tzfile(5):


$ make lint-man-mandoc V=1
LINT (mandoc)	tmp/lint/man5/tzfile.5.lint-man.mandoc.touch
! (mandoc -man -Tlint  man5/tzfile.5 2>&1 \
   | grep -v 'STYLE: lower case character in document title:' \
   | grep -v 'UNSUPP: ignoring macro in table:' \
   | grep -v 'WARNING: cannot parse date, using it verbatim: TH (date)' \
   | grep -v 'WARNING: empty block: UR' \
   ||:; \
) \
| grep '.' >&2
mandoc: man5/tzfile.5:15:19: WARNING: undefined escape, printing literally: \\
mandoc: man5/tzfile.5:15:10: WARNING: undefined escape, printing literally: \\
make: *** [lib/lint-man.mk:88: tmp/lint/man5/tzfile.5.lint-man.mandoc.touch] Error 1


The source is:

$ head man5/tzfile.5 -n20
.\" %%%LICENSE_START(PUBLIC_DOMAIN)
.\" This file is in the public domain, so clarified as of
.\" 1996-06-05 by Arthur David Olson <arthur_david_olson@nih.gov>.
.\" %%%LICENSE_END
.\"
.TH tzfile 5 2022-09-09 Linux "Linux Programmer's Manual"
.SH NAME
tzfile \- timezone information
.SH DESCRIPTION
.ie '\[lq]'' .ds lq \&"\"
.el .ds lq \[lq]\"
.ie '\[rq]'' .ds rq \&"\"
.el .ds rq \[rq]\"
.de q
\\$3\*(lq\\$1\*(rq\\$2
..
.ie \n(.g .ds - \f(CW-\fP
.el ds - \-
The timezone information files used by
.BR tzset (3)


Is this a limitation in mandoc(1)?  Should we change the source code?

Cheers,

Alex



-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

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

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

[Paul Eggert]

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

On 2023-03-07 15:54, Alejandro Colomar wrote:
> mandoc: man5/tzfile.5:15:19: WARNING: undefined escape, printing literally: \\
> mandoc: man5/tzfile.5:15:10: WARNING: undefined escape, printing literally: \\

My guess is that this is fallout from last month's changes to use \[lq] 
instead of \(lq and so forth. I suggest reverting all those changes to 
tzfile.5, since the upstream tzfile.5 continues to use \(lq etc. for 
compatibility with traditional troff, which is still a thing upstream.

Come to think of it, we should resync tzfile.5 and tzselect.8 from 
upstream for other reasons. Proposed patch to manpages attached. If this 
generates more mandoc warnings, I suppose we can adjust the calls to mandoc.

[-- Attachment #2: 0001-tzfile.5-tzselect.8-sync-from-tzdb-upstream.patch --]
[-- Type: text/x-patch, Size: 19958 bytes --]

From f68d7d2ac270f366bc97b6e8dc2b0f2af201c8aa Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@cs.ucla.edu>
Date: Tue, 7 Mar 2023 21:11:38 -0800
Subject: [PATCH] tzfile.5, tzselect.8: sync from tzdb upstream

This makes tzfile.5 and tzselect.8 a copy of the tzdb develoment
version (commit 12b48faf10c265ee3ea1aad8cdb5c8239eea65a0), except that
man-pages boilerplate surrounds the copyright notice, and the .TH line
uses man-pages format.
---
 man5/tzfile.5   | 194 +++++++++++++++++++++++++++++++++---------------
 man8/tzselect.8 | 133 +++++++++++++++++++++++++--------
 2 files changed, 237 insertions(+), 90 deletions(-)

diff --git a/man5/tzfile.5 b/man5/tzfile.5
index aa2170479..e94aaaad6 100644
--- a/man5/tzfile.5
+++ b/man5/tzfile.5
@@ -1,21 +1,21 @@
 .\" %%%LICENSE_START(PUBLIC_DOMAIN)
 .\" This file is in the public domain, so clarified as of
-.\" 1996-06-05 by Arthur David Olson <arthur_david_olson@nih.gov>.
+.\" 1996-06-05 by Arthur David Olson.
 .\" %%%LICENSE_END
 .\"
-.TH tzfile 5 2022-09-09 Linux "Linux Programmer's Manual"
+.TH tzfile 5 2023-03-07 Linux "Linux Programmer's Manual"
 .SH NAME
 tzfile \- timezone information
 .SH DESCRIPTION
-.ie '\[lq]'' .ds lq \&"\"
-.el .ds lq \[lq]\"
-.ie '\[rq]'' .ds rq \&"\"
-.el .ds rq \[rq]\"
+.ie '\(lq'' .ds lq \&"\"
+.el .ds lq \(lq\"
+.ie '\(rq'' .ds rq \&"\"
+.el .ds rq \(rq\"
 .de q
 \\$3\*(lq\\$1\*(rq\\$2
 ..
-.ie \n(.g .ds - \f(CW-\fP
-.el ds - \-
+.ie \n(.g .ds - \f(CR-\fP
+.el .ds - \-
 The timezone information files used by
 .BR tzset (3)
 are typically found under a directory with a name like
@@ -35,35 +35,36 @@ The magic four-byte ASCII sequence
 identifies the file as a timezone information file.
 .IP *
 A byte identifying the version of the file's format
-(as of 2017, either an ASCII NUL, or
+(as of 2021, either an ASCII NUL,
 .q "2",
+.q "3",
 or
-.q "3" ).
+.q "4" ).
 .IP *
 Fifteen bytes containing zeros reserved for future use.
 .IP *
 Six four-byte integer values, in the following order:
 .RS
 .TP
-.I tzh_ttisutcnt
+.B tzh_ttisutcnt
 The number of UT/local indicators stored in the file.
 (UT is Universal Time.)
 .TP
-.I tzh_ttisstdcnt
+.B tzh_ttisstdcnt
 The number of standard/wall indicators stored in the file.
 .TP
-.I tzh_leapcnt
+.B tzh_leapcnt
 The number of leap seconds for which data entries are stored in the file.
 .TP
-.I tzh_timecnt
+.B tzh_timecnt
 The number of transition times for which data entries are stored
 in the file.
 .TP
-.I tzh_typecnt
+.B tzh_typecnt
 The number of local time types for which data entries are stored
 in the file (must not be zero).
 .TP
-.I tzh_charcnt
+.B tzh_charcnt
 The number of bytes of time zone abbreviation strings
 stored in the file.
 .RE
@@ -71,14 +72,14 @@ stored in the file.
 The above header is followed by the following fields, whose lengths
 depend on the contents of the header:
 .IP * 2
-.I tzh_timecnt
+.B tzh_timecnt
 four-byte signed integer values sorted in ascending order.
 These values are written in network byte order.
 Each is used as a transition time (as returned by
 .BR time (2))
 at which the rules for computing local time change.
 .IP *
-.I tzh_timecnt
+.B tzh_timecnt
 one-byte unsigned integer values;
 each one but the last tells which of the different types of local time types
 described in the file is associated with the time period
@@ -88,8 +89,8 @@ and continuing up to but not including the next transition time.
 POSIX-style TZ string described below.)
 These values serve as indices into the next field.
 .IP *
-.I tzh_typecnt
-.I ttinfo
+.B tzh_typecnt
+.B ttinfo
 entries, each defined as follows:
 .in +.5i
 .sp
@@ -104,55 +105,78 @@ struct ttinfo {
 .fi
 .sp
 Each structure is written as a four-byte signed integer value for
-.IR tt_utoff ,
+.BR tt_utoff ,
 in network byte order, followed by a one-byte boolean for
-.I tt_isdst
+.B tt_isdst
 and a one-byte value for
-.IR tt_desigidx .
+.BR tt_desigidx .
 In each structure,
-.I tt_utoff
+.B tt_utoff
 gives the number of seconds to be added to UT,
-.I tt_isdst
+.B tt_isdst
 tells whether
-.I tm_isdst
+.B tm_isdst
 should be set by
 .BR localtime (3)
 and
-.I tt_desigidx
+.B tt_desigidx
 serves as an index into the array of time zone abbreviation bytes
 that follow the
-.I ttinfo
-structure(s) in the file.
+.B ttinfo
+entries in the file; if the designated string is "\*-00", the
+.B ttinfo
+entry is a placeholder indicating that local time is unspecified.
 The
-.I tt_utoff
+.B tt_utoff
 value is never equal to \-2**31, to let 32-bit clients negate it without
 overflow.
 Also, in realistic applications
-.I tt_utoff
+.B tt_utoff
 is in the range [\-89999, 93599] (i.e., more than \-25 hours and less
 than 26 hours); this allows easy support by implementations that
 already support the POSIX-required range [\-24:59:59, 25:59:59].
 .IP *
-.I tzh_leapcnt
+.B tzh_charcnt
+bytes that represent time zone designations,
+which are null-terminated byte strings, each indexed by the
+.B tt_desigidx
+values mentioned above.
+The byte strings can overlap if one is a suffix of the other.
+The encoding of these strings is not specified.
+.IP *
+.B tzh_leapcnt
 pairs of four-byte values, written in network byte order;
 the first value of each pair gives the nonnegative time
 (as returned by
 .BR time (2))
-at which a leap second occurs;
-the second is a signed integer specifying the
+at which a leap second occurs or at which the leap second table expires;
+the second is a signed integer specifying the correction, which is the
 .I total
 number of leap seconds to be applied during the time period
 starting at the given time.
-The pairs of values are sorted in ascending order by time.
-Each transition is for one leap second, either positive or negative;
-transitions always separated by at least 28 days minus 1 second.
+The pairs of values are sorted in strictly ascending order by time.
+Each pair denotes one leap second, either positive or negative,
+except that if the last pair has the same correction as the previous one,
+the last pair denotes the leap second table's expiration time.
+Each leap second is at the end of a UTC calendar month.
+The first leap second has a nonnegative occurrence time,
+and is a positive leap second if and only if its correction is positive;
+the correction for each leap second after the first differs
+from the previous leap second by either 1 for a positive leap second,
+or \-1 for a negative leap second.
+If the leap second table is empty, the leap-second correction is zero
+for all timestamps;
+otherwise, for timestamps before the first occurrence time,
+the leap-second correction is zero if the first pair's correction is 1 or \-1,
+and is unspecified otherwise (which can happen only in files
+truncated at the start).
 .IP *
-.I tzh_ttisstdcnt
+.B tzh_ttisstdcnt
 standard/wall indicators, each stored as a one-byte boolean;
 they tell whether the transition times associated with local time types
 were specified as standard time or local (wall clock) time.
 .IP *
-.I tzh_ttisutcnt
+.B tzh_ttisutcnt
 UT/local indicators, each stored as a one-byte boolean;
 they tell whether the transition times associated with local time types
 were specified as UT or local time.
@@ -178,10 +202,10 @@ The
 .BR localtime (3)
 function
 normally uses the first
-.I ttinfo
+.B ttinfo
 structure in the file
 if either
-.I tzh_timecnt
+.B tzh_timecnt
 is zero or the time argument is less than the first transition time recorded
 in the file.
 .SS Version 2 format
@@ -195,11 +219,11 @@ POSIX-TZ-environment-variable-style string for use in handling instants
 after the last transition time stored in the file
 or for all instants if the file has no transitions.
 The POSIX-style TZ string is empty (i.e., nothing between the newlines)
-if there is no POSIX representation for such instants.
+if there is no POSIX-style representation for such instants.
 If nonempty, the POSIX-style TZ string must agree with the local time
 type after the last transition time if present in the eight-byte data;
 for example, given the string
-.q "WET0WEST,M3.5.0,M10.5.0/3"
+.q "WET0WEST,M3.5.0/1,M10.5.0"
 then if a last transition time is in July, the transition's local time
 type must specify a daylight-saving time abbreviated
 .q "WEST"
@@ -217,33 +241,52 @@ from 0 through 24.
 Second, DST is in effect all year if it starts
 January 1 at 00:00 and ends December 31 at 24:00 plus the difference
 between daylight saving and standard time.
+.SS Version 4 format
+For version-4-format TZif files,
+the first leap second record can have a correction that is neither
++1 nor \-1, to represent truncation of the TZif file at the start.
+Also, if two or more leap second transitions are present and the last
+entry's correction equals the previous one, the last entry
+denotes the expiration of the leap second table instead of a leap second;
+timestamps after this expiration are unreliable in that future
+releases will likely add leap second entries after the expiration, and
+the added leap seconds will change how post-expiration timestamps are treated.
 .SS Interoperability considerations
 Future changes to the format may append more data.
 .PP
 Version 1 files are considered a legacy format and
-should be avoided, as they do not support transition
+should not be generated, as they do not support transition
 times after the year 2038.
-Readers that only understand Version 1 must ignore
+Readers that understand only Version 1 must ignore
 any data that extends beyond the calculated end of the version
 1 data block.
 .PP
-Writers should generate a version 3 file if
+Other than version 1, writers should generate
+the lowest version number needed by a file's data.
+For example, a writer should generate a version 4 file
+only if its leap second table either expires or is truncated at the start.
+Likewise, a writer not generating a version 4 file
+should generate a version 3 file only if
 TZ string extensions are necessary to accurately
 model transition times.
-Otherwise, version 2 files should be generated.
 .PP
 The sequence of time changes defined by the version 1
-header and data block should be a contiguous subsequence
+header and data block should be a contiguous sub-sequence
 of the time changes defined by the version 2+ header and data
 block, and by the footer.
 This guideline helps obsolescent version 1 readers
 agree with current readers about timestamps within the
-contiguous subsequence.  It also lets writers not
+contiguous sub-sequence.  It also lets writers not
 supporting obsolescent readers use a
-.I tzh_timecnt
+.B tzh_timecnt
 of zero
 in the version 1 data block to save space.
 .PP
+When a TZif file contains a leap second table expiration
+time, TZif readers should either refuse to process
+post-expiration timestamps, or process them as if the expiration
+time did not exist (possibly with an error indication).
+.PP
 Time zone designations should consist of at least three (3)
 and no more than six (6) ASCII characters from the set of
 alphanumerics,
@@ -253,13 +296,20 @@ and
 This is for compatibility with POSIX requirements for
 time zone abbreviations.
 .PP
-When reading a version 2 or 3 file, readers
+When reading a version 2 or higher file, readers
 should ignore the version 1 header and data block except for
 the purpose of skipping over them.
 .PP
 Readers should calculate the total lengths of the
 headers and data blocks and check that they all fit within
 the actual file size, as part of a validity check for the file.
+.PP
+When a positive leap second occurs, readers should append an extra
+second to the local minute containing the second just before the leap
+second.  If this occurs when the UTC offset is not a multiple of 60
+seconds, the leap second occurs earlier than the last second of the
+local minute and the minute's remaining local seconds are numbered
+through 60 instead of the usual 59; the UTC offset is unaffected.
 .SS Common interoperability issues
 This section documents common problems in reading or writing TZif files.
 Most of these are problems in generating TZif files for use by
@@ -280,7 +330,7 @@ design goal has been that a reader can successfully use a TZif
 file even if the file is of a later TZif version than what the
 reader was designed for.
 When complete compatibility was not achieved, an attempt was
-made to limit glitches to rarely used timestamps, and to allow
+made to limit glitches to rarely used timestamps and allow
 simple partial workarounds in writers designed to generate
 new-version data useful even for older-version readers.
 This section attempts to document these compatibility issues and
@@ -297,20 +347,33 @@ version 2+ data even if the reader's native timestamps have only
 32 bits.
 .IP *
 Some readers designed for version 2 might mishandle
-timestamps after a version 3 file's last transition, because
+timestamps after a version 3 or higher file's last transition, because
 they cannot parse extensions to POSIX in the TZ-like string.
 As a partial workaround, a writer can output more transitions
 than necessary, so that only far-future timestamps are
 mishandled by version 2 readers.
 .IP *
 Some readers designed for version 2 do not support
-permanent daylight saving time, e.g., a TZ string
+permanent daylight saving time with transitions after 24:00
+\(en e.g., a TZ string
 .q "EST5EDT,0/0,J365/25"
-denoting permanent Eastern Daylight Time (\-04).
-As a partial workaround, a writer can substitute standard time
-for the next time zone east, e.g.,
+denoting permanent Eastern Daylight Time
+(\-04).
+As a workaround, a writer can substitute standard time
+for two time zones east, e.g.,
+.q "XXX3EDT4,0/0,J365/23"
+for a time zone with a never-used standard time (XXX, \-03)
+and negative daylight saving time (EDT, \-04) all year.
+Alternatively,
+as a partial workaround a writer can substitute standard time
+for the next time zone east \(en e.g.,
 .q "AST4"
-for permanent Atlantic Standard Time (\-04).
+for permanent
+Atlantic Standard Time (\-04).
+.IP *
+Some readers designed for version 2 or 3, and that require strict
+conformance to RFC 8536, reject version 4 files whose leap second
+tables are truncated at the start or that end in expiration times.
 .IP *
 Some readers ignore the footer, and instead predict future
 timestamps from the time type of the last transition.
@@ -375,6 +438,17 @@ thus swapping standard and daylight saving time.
 Although this workaround misidentifies which part of the year
 uses daylight saving time, it records UT offsets and time zone
 abbreviations correctly.
+.IP *
+Some readers generate ambiguous timestamps for positive leap seconds
+that occur when the UTC offset is not a multiple of 60 seconds.
+For example, in a timezone with UTC offset +01:23:45 and with
+a positive leap second 78796801 (1972-06-30 23:59:60 UTC), some readers will
+map both 78796800 and 78796801 to 01:23:45 local time the next day
+instead of mapping the latter to 01:23:46, and they will map 78796815 to
+01:23:59 instead of to 01:23:60.
+This has not yet been a practical problem, since no civil authority
+has observed such UTC offsets since leap seconds were
+introduced in 1972.
 .PP
 Some interoperability problems are reader bugs that
 are listed here mostly as warnings to developers of readers.
@@ -417,11 +491,9 @@ of one hour, or of 15 minutes, or of 1 minute.
 .PP
 Olson A, Eggert P, Murchison K. The Time Zone Information Format (TZif).
 2019 Feb.
-.UR https://\:www.rfc-editor.org/\:info/\:rfc8536
+.UR https://\:datatracker.ietf.org/\:doc/\:html/\:rfc8536
 Internet RFC 8536
 .UE
 .UR https://\:doi.org/\:10.17487/\:RFC8536
 doi:10.17487/RFC8536
 .UE .
-.\" This file is in the public domain, so clarified as of
-.\" 1996-06-05 by Arthur David Olson.
diff --git a/man8/tzselect.8 b/man8/tzselect.8
index 2319c6158..3b69587f3 100644
--- a/man8/tzselect.8
+++ b/man8/tzselect.8
@@ -1,53 +1,128 @@
 .\" %%%LICENSE_START(PUBLIC_DOMAIN)
-.\" This page is in the public domain
+.\" This file is in the public domain, so clarified as of
+.\" 2009-05-17 by Arthur David Olson.
 .\" %%%LICENSE_END
 .\"
 .TH tzselect 8 (date) "Linux man-pages (unreleased)"
 .SH NAME
 tzselect \- select a timezone
 .SH SYNOPSIS
-.nf
+.ie \n(.g .ds - \f(CR-\fP
+.el .ds - \-
+.ds d " degrees
+.ds m " minutes
+.ds s " seconds
+.ds _ " \&
+.if t \{\
+. if \n(.g .if c \(de .if c \(fm .if c \(sd \{\
+.  ds d \(de
+.  ds m \(fm
+.  ds s \(sd
+.  ds _ \|
+. \}
+.\}
 .B tzselect
-.fi
+[
+.B \*-c
+.I coord
+] [
+.B \*-n
+.I limit
+] [
+.B \*-\*-help
+] [
+.B \*-\*-version
+]
 .SH DESCRIPTION
 The
 .B tzselect
 program asks the user for information about the current location,
-and outputs the resulting timezone description to standard output.
-The output is suitable as a value for the
-.B TZ
-environment variable.
+and outputs the resulting timezone to standard output.
+The output is suitable as a value for the TZ environment variable.
 .PP
 All interaction with the user is done via standard input and standard error.
-.SH EXIT STATUS
-The exit status is zero if a timezone was successfully obtained
-from the user, and is nonzero otherwise.
-.SH ENVIRONMENT
-.TP
-.B AWK
-Name of a POSIX-compliant
-.I awk
+.SH OPTIONS
+.TP
+.BI "\*-c " coord
+Instead of asking for continent and then country and then city,
+ask for selection from time zones whose largest cities
+are closest to the location with geographical coordinates
+.I coord.
+Use ISO 6709 notation for
+.I coord,
+that is, a latitude immediately followed by a longitude.  The latitude
+and longitude should be signed integers followed by an optional
+decimal point and fraction: positive numbers represent north and east,
+negative south and west.  Latitudes with two and longitudes with three
+integer digits are treated as degrees; latitudes with four or six and
+longitudes with five or seven integer digits are treated as
+.I "DDMM, DDDMM, DDMMSS,"
+or
+.I DDDMMSS
+representing
+.I DD
+or
+.I DDD
+degrees,
+.I MM
+minutes,
+and zero or
+.I SS
+seconds, with any trailing fractions represent fractional minutes or
+(if
+.I SS
+is present) seconds.  The decimal point is that of the current locale.
+For example, in the (default) C locale,
+.B "\*-c\ +40.689\*-074.045"
+specifies 40.689\*d\*_N, 74.045\*d\*_W,
+.B "\*-c\ +4041.4\*-07402.7"
+specifies 40\*d\*_41.4\*m\*_N, 74\*d\*_2.7\*m\*_W, and
+.B "\*-c\ +404121\*-0740240"
+specifies 40\*d\*_41\*m\*_21\*s\*_N, 74\*d\*_2\*m\*_40\*s\*_W.
+If
+.I coord
+is not one of the documented forms, the resulting behavior is unspecified.
+.TP
+.BI "\*-n " limit
+When
+.B \*-c
+is used, display the closest
+.I limit
+locations (default 10).
+.TP
+.B "\*-\*-help"
+Output help information and exit.
+.TP
+.B "\*-\*-version"
+Output version information and exit.
+.SH "ENVIRONMENT VARIABLES"
+.TP
+\f3AWK\fP
+Name of a Posix-compliant
+.B awk
 program (default:
 .BR awk ).
 .TP
-.B TZDIR
+\f3TZDIR\fP
 Name of the directory containing timezone data files (default:
-.IR /usr/share/zoneinfo ).
-.\" or perhaps /usr/local/etc/zoneinfo in some older systems.
+.BR /usr/share/zoneinfo ).
 .SH FILES
 .TP
-\fBTZDIR\fP\fI/iso3166.tab\fP
+\f2TZDIR\fP\f3/iso3166.tab\fP
 Table of ISO 3166 2-letter country codes and country names.
 .TP
-\fBTZDIR\fP\fI/zone.tab\fP
-Table of country codes, latitude and longitude, TZ values, and
+\f2TZDIR\fP\f3/zone1970.tab\fP
+Table of country codes, latitude and longitude, timezones, and
 descriptive comments.
 .TP
-\fBTZDIR\fP\fI/\fP\fITZ\fP
-Timezone data file for timezone
-.IR TZ .
-.SH SEE ALSO
-.BR tzfile (5),
-.BR zdump (8),
-.BR zic (8)
-.\" @(#)tzselect.8	1.3
+\f2TZDIR\fP\f3/\fP\f2TZ\fP
+Timezone data file for timezone \f2TZ\fP.
+.SH "EXIT STATUS"
+The exit status is zero if a timezone was successfully obtained from the user,
+nonzero otherwise.
+.SH "SEE ALSO"
+newctime(3), tzfile(5), zdump(8), zic(8)
+.SH NOTES
+Applications should not assume that
+.BR tzselect 's
+output matches the user's political preferences.
-- 
2.39.2

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

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 6299 bytes --]

Hi Paul!

[reordered quotes for my reply]

On 3/8/23 06:19, Paul Eggert wrote:

> 
> Come to think of it, we should resync tzfile.5 and tzselect.8 from 
> upstream for other reasons. Proposed patch to manpages attached. If this 
> generates more mandoc warnings, I suppose we can adjust the calls to mandoc.

Yes, I like having them as synced as possible (ideally, we would just
hold a simple copy in the Linux man-pages).  I've applied your patch.

BTW, I have some comments to make about the patch, and it would be
easier to make them if the patch was not attached, but rather inline
in the mail.  (IIRC, I also have a few comments about your other patch
submitted recently, and I haven't answered so far because I find it
cumbersome to copy from the attachment into the email to do a proper
reply; but I'm not ignoring it; just finding some time for it ;)
Would you mind sending your patches inline, if it's not much
cumbersome to you?  But I guess you may have your customs though,
so if you prefer sending them attached, that's fine; it'll just
take me a bit more time to reply, but I appreciate your contributions
anyway :-)

> I suggest reverting all those changes to 
> tzfile.5, since the upstream tzfile.5 continues to use \(lq etc. for 
> compatibility with traditional troff, which is still a thing upstream.

Yup, no problem with that.  I applied the patch to tz* pages by
accident.  It wasn't my intention to deviate from upstream.  I
just applied the scripted changes to all pages blindly, and forgot
to keep the external pages out of the patches.

> On 2023-03-07 15:54, Alejandro Colomar wrote:
>> mandoc: man5/tzfile.5:15:19: WARNING: undefined escape, printing literally: \\
>> mandoc: man5/tzfile.5:15:10: WARNING: undefined escape, printing literally: \\
> 
> My guess is that this is fallout from last month's changes to use \[lq] 
> instead of \(lq and so forth.

It seems not.  I still see the warning.

alx@debian:~/src/linux/man-pages/man-pages/main$ grep -n '\\\\' man5/tzfile.5 
15:\\$3\*(lq\\$1\*(rq\\$2
alx@debian:~/src/linux/man-pages/man-pages/main$ make lint-man-mandoc V=1
LINT (mandoc)	tmp/lint/man5/tzfile.5.lint-man.mandoc.touch
! (mandoc -man -Tlint  man5/tzfile.5 2>&1 \
   | grep -v 'STYLE: lower case character in document title:' \
   | grep -v 'UNSUPP: ignoring macro in table:' \
   | grep -v 'WARNING: cannot parse date, using it verbatim: TH (date)' \
   | grep -v 'WARNING: empty block: UR' \
   ||:; \
) \
| grep '.' >&2
mandoc: man5/tzfile.5:15:18: WARNING: undefined escape, printing literally: \\
mandoc: man5/tzfile.5:15:9: WARNING: undefined escape, printing literally: \\
make: *** [lib/lint-man.mk:88: tmp/lint/man5/tzfile.5.lint-man.mandoc.touch] Error 1


I don't run these tests often, so I'm not saying this is a new warning.
It has been there probably since forever.  It's just that previously
there were many other pages that gave warnings, but now I've cleaned
most of those, and your pages are the only ones --together with
bpf-helpers(7)-- that trigger warnings from `make lint-man-mandoc`.


And now some question about the patch itself (I've applied it, but
there's something itching me):

> commit bab8324d213362bbb59434748797a0cddcbefecd (HEAD -> master, korg/master)
> Author: Paul Eggert <eggert@cs.ucla.edu>
> Date:   Tue Mar 7 21:11:38 2023 -0800
> 
>     tzfile.5, tzselect.8: sync from tzdb upstream
>     
>     This makes tzfile.5 and tzselect.8 a copy of the tzdb develoment
>     version (commit 12b48faf10c265ee3ea1aad8cdb5c8239eea65a0), except that
>     man-pages boilerplate surrounds the copyright notice, and the .TH line
>     uses man-pages format.

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.

>     
>     Signed-off-by: Alejandro Colomar <alx@kernel.org>
> 
> diff --git a/man5/tzfile.5 b/man5/tzfile.5
> index aa2170479..e94aaaad6 100644
> --- a/man5/tzfile.5
> +++ b/man5/tzfile.5
> @@ -1,21 +1,21 @@
>  .\" %%%LICENSE_START(PUBLIC_DOMAIN)
>  .\" This file is in the public domain, so clarified as of
> -.\" 1996-06-05 by Arthur David Olson <arthur_david_olson@nih.gov>.
> +.\" 1996-06-05 by Arthur David Olson.
>  .\" %%%LICENSE_END
>  .\"
> -.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, because:

-  The 4th argument is supposed to specify the project and version
   of the upstream manual page.  That should be your project and
   version (similar to how the Linux man-pages pages have in the
   latest release "Linux man-pages 6.03").  For example, another
   page that is synced from upstream is bpf-helpers.7.  It has the
   following:

       $ grep '\.TH' man7/bpf-helpers.7 
       .TH "BPF-HELPERS" 7 "2022-09-26" "Linux v6.1"

   Would you mind specifying your own project and version upstream
   so I could keep them untouched?

I'd also like if you specified the last-modified date when you
make a release, but if we sync the page from git HEAD that's less
important.  You could do something similar to the placeholder
'(date)' that we use, and somehow update it at release time.


>  .SH NAME
>  tzfile \- timezone information
>  .SH DESCRIPTION
[...]
> diff --git a/man8/tzselect.8 b/man8/tzselect.8
> index 2319c6158..3b69587f3 100644
> --- a/man8/tzselect.8
> +++ b/man8/tzselect.8
> @@ -1,53 +1,128 @@
>  .\" %%%LICENSE_START(PUBLIC_DOMAIN)
> -.\" This page is in the public domain
> +.\" This file is in the public domain, so clarified as of
> +.\" 2009-05-17 by Arthur David Olson.
>  .\" %%%LICENSE_END
>  .\"
>  .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 :/.

>  .SH NAME
>  tzselect \- select a timezone
>  .SH SYNOPSIS

Cheers,

Alex

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

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

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

[Paul Eggert]

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

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

[-- Attachment #2: 0001-Use-lowercase-.TH-titles.patch --]
[-- Type: text/x-patch, Size: 1978 bytes --]

From 393ad035dc20c14e43ff33435552290b0db5b5e8 Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@cs.ucla.edu>
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

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

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 4357 bytes --]

Hi Paul,

On 3/8/23 22:54, Paul Eggert wrote:
> On 3/8/23 11:44, Alejandro Colomar wrote:>> 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'll report this in mandoc(1) then.  Thanks for confirming.  Although
maybe this is expected of mandoc(1), since it's not a generic roff(7)
interpreter...  I CCd Ingo (mandoc(1) maintainer) in case he's interested
in the bug.


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

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

I prefer if we come up with some good upstream TH line that I can keep.  :)

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

That patch looks good to me.  If you use these:

Reviewed-by: Alejandro Colomar <alx@kernel.org>


>  If mandoc complains about this, that's mandoc's problem not 
> ours.

Indeed.  It complains, but Ingo was in favor of removing that warning, and
modifying their own pages to use lowercase too.

In the Linux man-pages I'm ignoring that warning with:

! (mandoc -man -Tlint  man5/tzfile.5 2>&1 \
   | grep -v 'STYLE: lower case character in document title:' \
   | grep -v 'UNSUPP: ignoring macro in table:' \
   | grep -v 'WARNING: cannot parse date, using it verbatim: TH (date)' \
   | grep -v 'WARNING: empty block: UR' \
   ||:; \
) \
| grep '.' >&2

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

Makes sense.  In that case, I suggest using the project name without a
version.  How about the following?

.TH tzfile 5 "" tzdb

(or alternatively:)

.TH tzfile 5 "" "Time Zone Database"

The "" (3rd field) is for the date, which we don't want to be updating.
The 4th field has only the project name, but not the version, since it
would also be complicated to update.  (You could use 'tzbd' or "Time
Zone Database", whatever you prefer.)  The 5th field is also missing,
since the default value is good enough (for section 5 it's "File Formats
Manual").

If you use that line upstream, I'd keep it untouched in the Linux man-pages.

> 
> Another way the files differ is in the lack of 
> "%%%LICENSE_START(PUBLIC_DOMAIN)" and "%%%LICENSE_END" boilerplate 
> upstream.

I removed it in most pages.  Most pages now use SPDX-License-Identifier.
If that's the only remaining difference from upstream, I'd also remove it, 

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

I don't :-)

$ wtf is SBOM
Gee...  I don't know what SBOM means...
$ wtf is SSDF
Gee...  I don't know what SSDF means...
$ wtf is SCA
Gee...  I don't know what SCA means...
$ dict SBOM
No definitions found for "SBOM", perhaps you mean:
gcide:  Bom  Swom
wn:  som
vera:  bom  som  sbod
foldoc:  bsom  som  sbm
$ dict SSDF
No definitions found for "SSDF", perhaps you mean:
vera:  sdf  ssf  ssd  sadf  sidf  srdf  sscf  ssrf  ssda  ssdc
  ssdd  ssdp  ssdu
foldoc:  sdf  ssd


There's a dict(1) entry for SCA, but I don't think it's related to
this :).

Cheers,

Alex

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

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

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

[Paul Eggert]

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

On 3/8/23 14:15, Alejandro Colomar wrote:

> That patch looks good to me.  If you use these:
> 
> Reviewed-by: Alejandro Colomar <alx@kernel.org>

Oh, we don't use those in tzdb; instead your name is mentioned in the 
commit message. I installed it that way.


> I suggest using the project name without a
> version.  How about the following?
> 
> .TH tzfile 5 "" tzdb
> 
> (or alternatively:)
> 
> .TH tzfile 5 "" "Time Zone Database"

Yes, that should work. I installed the attached proposed patch into the 
tzdb development repository. Feel free to migrate this into man-pages at 
your convenience. No rush of course.


>> 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 :-).
> 
> I don't :-)

https://www.nist.gov/itl/executive-order-14028-improving-nations-cybersecurity/software-security-supply-chains-open

[-- Attachment #2: 0001-Append-tzdb-arg-4-to-.TH-lines.patch --]
[-- Type: text/x-patch, Size: 3580 bytes --]

From 27148539e699d9abe50df84371a077fdf2bc13de Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@cs.ucla.edu>
Date: Wed, 8 Mar 2023 14:40:58 -0800
Subject: [PROPOSED] Append tzdb arg 4 to .TH lines

Suggested by Alejandro Colomar in:
https://lore.kernel.org/linux-man/08a72d2c-e7cb-4390-2cb1-7601b344ce9e@gmail.com/T/#t
---
 date.1        | 2 +-
 newctime.3    | 2 +-
 newstrftime.3 | 2 +-
 newtzset.3    | 2 +-
 time2posix.3  | 2 +-
 tzfile.5      | 2 +-
 tzselect.8    | 2 +-
 zdump.8       | 2 +-
 zic.8         | 2 +-
 9 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/date.1 b/date.1
index 8670ff1..e810721 100644
--- a/date.1
+++ b/date.1
@@ -1,6 +1,6 @@
 .\" This file is in the public domain, so clarified as of
 .\" 2009-05-17 by Arthur David Olson.
-.TH date 1
+.TH date 1 "" "Time Zone Database"
 .SH NAME
 date \- show and set date and time
 .SH SYNOPSIS
diff --git a/newctime.3 b/newctime.3
index 70d8e54..05bb7de 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 "" "Time Zone Database"
 .SH NAME
 asctime, ctime, difftime, gmtime, localtime, mktime \- convert date and time
 .SH SYNOPSIS
diff --git a/newstrftime.3 b/newstrftime.3
index 75d88c8..432c3e8 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 "" "Time Zone Database"
 .SH NAME
 strftime \- format date and time
 .SH SYNOPSIS
diff --git a/newtzset.3 b/newtzset.3
index e16ae6b..78b6b6c 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 "" "Time Zone Database"
 .SH NAME
 tzset \- initialize time conversion information
 .SH SYNOPSIS
diff --git a/time2posix.3 b/time2posix.3
index e13c431..f48402b 100644
--- a/time2posix.3
+++ b/time2posix.3
@@ -1,6 +1,6 @@
 .\" This file is in the public domain, so clarified as of
 .\" 1996-06-05 by Arthur David Olson.
-.TH time2posix 3
+.TH time2posix 3 "" "Time Zone Database"
 .SH NAME
 time2posix, posix2time \- convert seconds since the Epoch
 .SH SYNOPSIS
diff --git a/tzfile.5 b/tzfile.5
index eb5d4e8..59d9f6b 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 "" "Time Zone Database"
 .SH NAME
 tzfile \- timezone information
 .SH DESCRIPTION
diff --git a/tzselect.8 b/tzselect.8
index 9828848..4578090 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 "" "Time Zone Database"
 .SH NAME
 tzselect \- select a timezone
 .SH SYNOPSIS
diff --git a/zdump.8 b/zdump.8
index 170e18d..f77c0c7 100644
--- a/zdump.8
+++ b/zdump.8
@@ -1,6 +1,6 @@
 .\" This file is in the public domain, so clarified as of
 .\" 2009-05-17 by Arthur David Olson.
-.TH zdump 8
+.TH zdump 8 "" "Time Zone Database"
 .SH NAME
 zdump \- timezone dumper
 .SH SYNOPSIS
diff --git a/zic.8 b/zic.8
index e9fccfe..c467efe 100644
--- a/zic.8
+++ b/zic.8
@@ -1,6 +1,6 @@
 .\" This file is in the public domain, so clarified as of
 .\" 2009-05-17 by Arthur David Olson.
-.TH zic 8
+.TH zic 8 "" "Time Zone Database"
 .SH NAME
 zic \- timezone compiler
 .SH SYNOPSIS
-- 
2.39.2