Oops, I should have CCd tech@, not discuss@. On Sun, Oct 22, 2023 at 12:58:17PM +0200, Alejandro Colomar wrote: > Hi Paul, > > On Sat, Oct 21, 2023 at 05:36:03PM -0700, Paul Eggert wrote: > > On 2023-10-18 04:16, Alejandro Colomar wrote: > > > > > I guess using '\[bu]' (or '\(bu') might not be appropriate for the tz > > > project, as it may be less portable to old systems > > > > We should be ok with \(bu even with older nroff; I just checked with Solaris > > 10 nroff and it generated an ASCII 'o', same as GNU/Linux. > > > > > > > The change would be to use '.IP * 3' instead of '.IP * 2'. 3 is for the > > > width of '*' +2. > > > > 3 is equivalent to 3n, which is too much for PDF output. I installed the > > attached, which uses \w'\(bu 'u instead of 3. This is equivalent for to 3 > > for nroff, and has a better look for troff. > > Hmm, interesting trick. To me, 3 doesn't look so excessive; it's at the > verge of being it, but still acceptable, but can understand your > preference. > > The only downside I see to your approach (appart from making the source > more complex, but I'm willing to pay that for better output), is that > mandoc(1) doesn't seem to understand that, and falls back to the default > indentation, which is even more excessive. > > Maybe we can report the problem to the maintainers of mandoc(1), > although I'm not sure how much they'll enjoy such low level roff(7) > stuff. > > > > > This patch also cleans up some of the other indenting irregularities in TZDB > > man pages; for example, plain ".TP" is good enough, and we don't need ".TP > > 10". Hope it works for you. > > Thanks! LGTM. > > > From 4a577028c65c70f6a85726ee34d307ee4a51b24d Mon Sep 17 00:00:00 2001 > > From: Paul Eggert > > Date: Sat, 21 Oct 2023 16:10:29 -0700 > > Subject: [PROPOSED] Be more systematic about man page indenting > > > > This responds to a suggestion by Alejandro Colomar in: > > https://mm.icann.org/pipermail/tz/2023-October/033116.html > > --- > > newtzset.3 | 6 ++-- > > time2posix.3 | 2 +- > > tzfile.5 | 86 +++++++++++++++++++++++++++++----------------------- > > zdump.8 | 5 ++- > > zic.8 | 48 ++++++++++++++--------------- > > 5 files changed, 78 insertions(+), 69 deletions(-) > > > > diff --git a/newtzset.3 b/newtzset.3 > > index 80617cd7..45ddbd24 100644 > > --- a/newtzset.3 > > +++ b/newtzset.3 > > @@ -115,7 +115,7 @@ it must have the following syntax (spaces inserted for clarity): > > .PP > > Where: > > .RS > > -.TP 15 > > +.TP > > .IR std " and " dst > > Three or more bytes that are the designation for the standard > > .RI ( std ) > > @@ -205,7 +205,7 @@ The format of > > .I date > > is one of the following: > > .RS > > -.TP 10 > > +.TP > > .BI J n > > The Julian day > > .I n > > @@ -238,7 +238,7 @@ first week in which the > > .IR d' th > > day occurs. Day zero is Sunday. > > .RE > > -.IP "" 15 > > +.IP > > The > > .I time > > has the same format as > > diff --git a/time2posix.3 b/time2posix.3 > > index f48402b9..6644060a 100644 > > --- a/time2posix.3 > > +++ b/time2posix.3 > > @@ -100,7 +100,7 @@ and back from, > > the POSIX representation over the leap second inserted at the end of June, > > 1993. > > .nf > > -.ta \w'93/06/30 'u +\w'23:59:59 'u +\w'A+0 'u +\w'X=time2posix(T) 'u > > +.ta \w'93/06/30\0'u +\w'23:59:59\0'u +\w'A+0\0'u +\w'X=time2posix(T)\0'u > > DATE TIME T X=time2posix(T) posix2time(X) > > 93/06/30 23:59:59 A+0 B+0 A+0 > > 93/06/30 23:59:60 A+1 B+1 A+1 or A+2 > > diff --git a/tzfile.5 b/tzfile.5 > > index 59d9f6ba..55280282 100644 > > --- a/tzfile.5 > > +++ b/tzfile.5 > > @@ -26,23 +26,24 @@ a signed binary integer is represented using two's complement, > > and a boolean is represented by a one-byte binary integer that is > > either 0 (false) or 1 (true). > > The format begins with a 44-byte header containing the following fields: > > -.IP * 2 > > +.RS "\w' 'u" > > +.IP \(bu "\w'\(bu 'u" > > The magic four-byte ASCII sequence > > .q "TZif" > > identifies the file as a timezone information file. > > -.IP * > > +.IP \(bu > > A byte identifying the version of the file's format > > (as of 2021, either an ASCII NUL, > > .q "2", > > .q "3", > > or > > .q "4" ). > > -.IP * > > +.IP \(bu > > Fifteen bytes containing zeros reserved for future use. > > -.IP * > > +.IP \(bu > > Six four-byte integer values, in the following order: > > -.RS > > -.TP > > +.RS "\w' \(bu 'u" > > +.TP "\w' 'u" > > .B tzh_ttisutcnt > > The number of UT/local indicators stored in the file. > > (UT is Universal Time.) > > @@ -68,14 +69,15 @@ stored in the file. > > .PP > > The above header is followed by the following fields, whose lengths > > depend on the contents of the header: > > -.IP * 2 > > +.RS "\w' 'u" > > +.IP \(bu "\w'\(bu 'u" > > .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 * > > +.IP \(bu > > .B tzh_timecnt > > one-byte unsigned integer values; > > each one but the last tells which of the different types of local time types > > @@ -85,20 +87,20 @@ and continuing up to but not including the next transition time. > > (The last time type is present only for consistency checking with the > > POSIX-style TZ string described below.) > > These values serve as indices into the next field. > > -.IP * > > +.IP \(bu > > .B tzh_typecnt > > .B ttinfo > > entries, each defined as follows: > > -.in +.5i > > +.in +2 > > Hmm, I think I'll take this. The Linux man-pages currently use .in +4n > for examples, but maybe I can simplify to just +4 without the 'n'. I'll > check if the PDF isn't excessive. > > Cheers, > Alex > > > .sp > > .nf > > -.ta .5i +\w'unsigned char\0\0'u > > +.ta \w'\0\0\0\0'u +\w'unsigned char\0'u > > struct ttinfo { > > int32_t tt_utoff; > > unsigned char tt_isdst; > > unsigned char tt_desigidx; > > }; > > -.in -.5i > > +.in > > .fi > > .sp > > Each structure is written as a four-byte signed integer value for > > @@ -132,7 +134,8 @@ Also, in realistic applications > > 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 * > > +.RS "\w' 'u" > > +.IP \(bu "\w'\(bu 'u" > > .B tzh_charcnt > > bytes that represent time zone designations, > > which are null-terminated byte strings, each indexed by the > > @@ -140,7 +143,7 @@ which are null-terminated byte strings, each indexed by the > > 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 * > > +.IP \(bu > > .B tzh_leapcnt > > pairs of four-byte values, written in network byte order; > > the first value of each pair gives the nonnegative time > > @@ -167,18 +170,19 @@ 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 * > > +.IP \(bu > > .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 * > > +.IP \(bu > > .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. > > If a UT/local indicator is set, the corresponding standard/wall indicator > > must also be set. > > +.RE > > .PP > > The standard/wall and UT/local indicators were designed for > > transforming a TZif file's transition times into transitions appropriate > > @@ -312,15 +316,17 @@ This section documents common problems in reading or writing TZif files. > > Most of these are problems in generating TZif files for use by > > older readers. > > The goals of this section are: > > -.IP * 2 > > +.RS "\w' 'u" > > +.IP \(bu "\w'\(bu 'u" > > to help TZif writers output files that avoid common > > pitfalls in older or buggy TZif readers, > > -.IP * > > +.IP \(bu > > to help TZif readers avoid common pitfalls when reading > > files generated by future TZif writers, and > > -.IP * > > +.IP \(bu > > to help any future specification authors see what sort of > > problems arise when the TZif format is changed. > > +.RE > > .PP > > When new versions of the TZif format have been defined, a > > design goal has been that a reader can successfully use a TZif > > @@ -335,21 +341,22 @@ workarounds, as well as to document other common bugs in > > readers. > > .PP > > Interoperability problems with TZif include the following: > > -.IP * 2 > > +.RS "\w' 'u" > > +.IP \(bu "\w'\(bu 'u" > > Some readers examine only version 1 data. > > As a partial workaround, a writer can output as much version 1 > > data as possible. > > However, a reader should ignore version 1 data, and should use > > version 2+ data even if the reader's native timestamps have only > > 32 bits. > > -.IP * > > +.IP \(bu > > Some readers designed for version 2 might mishandle > > 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 * > > +.IP \(bu > > Some readers designed for version 2 do not support > > permanent daylight saving time with transitions after 24:00 > > \(en e.g., a TZ string > > @@ -367,22 +374,22 @@ for the next time zone east \(en e.g., > > .q "AST4" > > for permanent > > Atlantic Standard Time (\-04). > > -.IP * > > +.IP \(bu > > 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 * > > +.IP \(bu > > Some readers ignore the footer, and instead predict future > > timestamps from the time type of the last transition. > > As a partial workaround, a writer can output more transitions > > than necessary. > > -.IP * > > +.IP \(bu > > Some readers do not use time type 0 for timestamps before > > the first transition, in that they infer a time type using a > > heuristic that does not always select time type 0. > > As a partial workaround, a writer can output a dummy (no-op) > > first transition at an early time. > > -.IP * > > +.IP \(bu > > Some readers mishandle timestamps before the first > > transition that has a timestamp not less than \-2**31. > > Readers that support only 32-bit timestamps are likely to be > > @@ -391,11 +398,11 @@ more prone to this problem, for example, when they process > > bits. > > As a partial workaround, a writer can output a dummy > > transition at timestamp \-2**31. > > -.IP * > > +.IP \(bu > > Some readers mishandle a transition if its timestamp has > > the minimum possible signed 64-bit value. > > Timestamps less than \-2**59 are not recommended. > > -.IP * > > +.IP \(bu > > Some readers mishandle POSIX-style TZ strings that > > contain > > .q "<" > > @@ -407,11 +414,11 @@ or > > .q ">" > > for time zone abbreviations containing only alphabetic > > characters. > > -.IP * > > +.IP \(bu > > Many readers mishandle time zone abbreviations that contain > > non-ASCII characters. > > These characters are not recommended. > > -.IP * > > +.IP \(bu > > Some readers may mishandle time zone abbreviations that > > contain fewer than 3 or more than 6 characters, or that > > contain ASCII characters other than alphanumerics, > > @@ -419,7 +426,7 @@ contain ASCII characters other than alphanumerics, > > and > > .q "+". > > These abbreviations are not recommended. > > -.IP * > > +.IP \(bu > > Some readers mishandle TZif files that specify > > daylight-saving time UT offsets that are less than the UT > > offsets for the corresponding standard time. > > @@ -435,7 +442,7 @@ 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 * > > +.IP \(bu > > 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 > > @@ -446,38 +453,41 @@ instead of mapping the latter to 01:23:46, and they will map 78796815 to > > This has not yet been a practical problem, since no civil authority > > has observed such UTC offsets since leap seconds were > > introduced in 1972. > > +.RE > > .PP > > Some interoperability problems are reader bugs that > > are listed here mostly as warnings to developers of readers. > > -.IP * 2 > > +.RS "\w' 'u" > > +.IP \(bu "\w'\(bu 'u" > > Some readers do not support negative timestamps. > > Developers of distributed applications should keep this > > in mind if they need to deal with pre-1970 data. > > -.IP * > > +.IP \(bu > > Some readers mishandle timestamps before the first > > transition that has a nonnegative timestamp. > > Readers that do not support negative timestamps are likely to > > be more prone to this problem. > > -.IP * > > +.IP \(bu > > Some readers mishandle time zone abbreviations like > > .q "\*-08" > > that contain > > .q "+", > > .q "\*-", > > or digits. > > -.IP * > > +.IP \(bu > > Some readers mishandle UT offsets that are out of the > > traditional range of \-12 through +12 hours, and so do not > > support locations like Kiritimati that are outside this > > range. > > -.IP * > > +.IP \(bu > > Some readers mishandle UT offsets in the range [\-3599, \-1] > > seconds from UT, because they integer-divide the offset by > > 3600 to get 0 and then display the hour part as > > .q "+00". > > -.IP * > > +.IP \(bu > > Some readers mishandle UT offsets that are not a multiple > > of one hour, or of 15 minutes, or of 1 minute. > > +.RE > > .SH SEE ALSO > > .BR time (2), > > .BR localtime (3), > > diff --git a/zdump.8 b/zdump.8 > > index f77c0c79..c3f0bba6 100644 > > --- a/zdump.8 > > +++ b/zdump.8 > > @@ -152,10 +152,9 @@ tabbed columns line up.) > > .nf > > .sp > > .if \n(.g .ft CR > > -.if t .in +.5i > > -.if n .in +2 > > +.in +2 > > .nr w \w'1896-01-13 'u+\n(.i > > -.ta \w'1896-01-13 'u +\w'12:01:26 'u +\w'-103126 'u +\w'HWT 'u > > +.ta \w'1896-01-13\0\0'u +\w'12:01:26\0\0'u +\w'-103126\0\0'u +\w'HWT\0\0'u > > TZ="Pacific/Honolulu" > > - - -103126 LMT > > 1896-01-13 12:01:26 -1030 HST > > diff --git a/zic.8 b/zic.8 > > index 6bcef7ae..a958ddd1 100644 > > --- a/zic.8 > > +++ b/zic.8 > > @@ -95,7 +95,7 @@ as local time. > > .B zic > > will act as if the input contained a link line of the form > > .sp > > -.ti +.5i > > +.ti +2 > > .ta \w'Link\0\0'u +\w'\fItimezone\fP\0\0'u > > Link \fItimezone\fP localtime > > .sp > > @@ -118,7 +118,7 @@ TZ strings like "EET\*-2EEST" that lack transition rules. > > .B zic > > will act as if the input contained a link line of the form > > .sp > > -.ti +.5i > > +.ti +2 > > Link \fItimezone\fP posixrules > > .sp > > If > > @@ -330,19 +330,19 @@ abbreviation must be unambiguous in context. > > .PP > > A rule line has the form > > .nf > > -.ti +.5i > > +.ti +2 > > .ta \w'Rule\0\0'u +\w'NAME\0\0'u +\w'FROM\0\0'u +\w'1973\0\0'u +\w'\*-\0\0'u +\w'Apr\0\0'u +\w'lastSun\0\0'u +\w'2:00w\0\0'u +\w'1:00d\0\0'u > > .sp > > Rule NAME FROM TO \*- IN ON AT SAVE LETTER/S > > .sp > > For example: > > -.ti +.5i > > +.ti +2 > > .sp > > Rule US 1967 1973 \*- Apr lastSun 2:00w 1:00d D > > .sp > > .fi > > The fields that make up a rule line are: > > -.TP "\w'LETTER/S'u" > > +.TP > > .B NAME > > Gives the name of the rule set that contains this line. > > The name must start with a character that is neither > > @@ -404,7 +404,7 @@ Month names may be abbreviated. > > Gives the day on which the rule takes effect. > > Recognized forms include: > > .nf > > -.in +.5i > > +.in +2 > > .sp > > .ta \w'Sun<=25\0\0'u > > 5 the fifth of the month > > @@ -413,7 +413,7 @@ lastMon the last Monday in the month > > Sun>=8 first Sunday on or after the eighth > > Sun<=25 last Sunday on or before the 25th > > .fi > > -.in -.5i > > +.in > > .sp > > A weekday name (e.g., > > .BR "Sunday" ) > > @@ -440,7 +440,7 @@ Gives the time of day at which the rule takes effect, > > relative to 00:00, the start of a calendar day. > > Recognized forms include: > > .nf > > -.in +.5i > > +.in +2 > > .sp > > .ta \w'00:19:32.13\0\0'u > > 2 time in hours > > @@ -454,7 +454,7 @@ Recognized forms include: > > \*-2:30 2.5 hours before 00:00 > > \*- equivalent to 0 > > .fi > > -.in -.5i > > +.in > > .sp > > Although > > .B zic > > @@ -532,18 +532,18 @@ the variable part is null. > > A zone line has the form > > .sp > > .nf > > -.ti +.5i > > +.ti +2 > > .ta \w'Zone\0\0'u +\w'Asia/Amman\0\0'u +\w'STDOFF\0\0'u +\w'Jordan\0\0'u +\w'FORMAT\0\0'u > > Zone NAME STDOFF RULES FORMAT [UNTIL] > > .sp > > For example: > > .sp > > -.ti +.5i > > +.ti +2 > > Zone Asia/Amman 2:00 Jordan EE%sT 2017 Oct 27 01:00 > > .sp > > .fi > > The fields that make up a zone line are: > > -.TP "\w'STDOFF'u" > > +.TP > > .B NAME > > The name of the timezone. > > This is the name used in creating the time conversion information file for the > > @@ -663,15 +663,15 @@ For example: > > .br > > .ne 7 > > .nf > > -.in +2m > > +.in +2 > > .ta \w'# Rule\0\0'u +\w'NAME\0\0'u +\w'FROM\0\0'u +\w'2006\0\0'u +\w'\*-\0\0'u +\w'Oct\0\0'u +\w'lastSun\0\0'u +\w'2:00\0\0'u +\w'SAVE\0\0'u > > .sp > > # Rule NAME FROM TO \*- IN ON AT SAVE LETTER/S > > Rule US 1967 2006 - Oct lastSun 2:00 0 S > > Rule US 1967 1973 - Apr lastSun 2:00 1:00 D > > -.ta \w'Zone\0\0America/Menominee\0\0'u +\w'STDOFF\0\0'u +\w'RULES\0\0'u +\w'FORMAT\0\0'u > > -# Zone\0\0NAME STDOFF RULES FORMAT [UNTIL] > > -Zone\0\0America/Menominee \*-5:00 \*- EST 1973 Apr 29 2:00 > > +.ta \w'# Zone\0\0'u +\w'America/Menominee\0\0'u +\w'STDOFF\0\0'u +\w'RULES\0\0'u +\w'FORMAT\0\0'u > > +# Zone NAME STDOFF RULES FORMAT [UNTIL] > > +Zone America/Menominee \*-5:00 \*- EST 1973 Apr 29 2:00 > > \*-6:00 US C%sT > > .sp > > .in > > @@ -687,13 +687,13 @@ interprets this more sensibly as a single transition from 02:00 CST (\*-05) to > > A link line has the form > > .sp > > .nf > > -.ti +.5i > > +.ti +2 > > .ta \w'Link\0\0'u +\w'Europe/Istanbul\0\0'u > > Link TARGET LINK-NAME > > .sp > > For example: > > .sp > > -.ti +.5i > > +.ti +2 > > Link Europe/Istanbul Asia/Istanbul > > .sp > > .fi > > @@ -717,7 +717,7 @@ For example: > > .sp > > .ne 3 > > .nf > > -.in +2m > > +.in +2 > > .ta \w'Zone\0\0'u +\w'Greenwich\0\0'u > > Link Greenwich G_M_T > > Link Etc/GMT Greenwich > > @@ -737,13 +737,13 @@ The file that describes leap seconds can have leap lines and an > > expiration line. > > Leap lines have the following form: > > .nf > > -.ti +.5i > > +.ti +2 > > .ta \w'Leap\0\0'u +\w'YEAR\0\0'u +\w'MONTH\0\0'u +\w'DAY\0\0'u +\w'HH:MM:SS\0\0'u +\w'CORR\0\0'u > > .sp > > Leap YEAR MONTH DAY HH:MM:SS CORR R/S > > .sp > > For example: > > -.ti +.5i > > +.ti +2 > > .sp > > Leap 2016 Dec 31 23:59:60 + S > > .sp > > @@ -791,13 +791,13 @@ option is used. > > .PP > > The expiration line, if present, has the form: > > .nf > > -.ti +.5i > > +.ti +2 > > .ta \w'Expires\0\0'u +\w'YEAR\0\0'u +\w'MONTH\0\0'u +\w'DAY\0\0'u > > .sp > > Expires YEAR MONTH DAY HH:MM:SS > > .sp > > For example: > > -.ti +.5i > > +.ti +2 > > .sp > > Expires 2020 Dec 28 00:00:00 > > .sp > > @@ -816,7 +816,7 @@ Here is an extended example of > > .B zic > > input, intended to illustrate many of its features. > > .nf > > -.in +2m > > +.in +2 > > .ta \w'# Rule\0\0'u +\w'NAME\0\0'u +\w'FROM\0\0'u +\w'1973\0\0'u +\w'\*-\0\0'u +\w'Apr\0\0'u +\w'lastSun\0\0'u +\w'2:00\0\0'u +\w'SAVE\0\0'u > > .sp > > # Rule NAME FROM TO \*- IN ON AT SAVE LETTER/S > > -- > > 2.39.2 > > > > > -- > --