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 <eggert@cs.ucla.edu> 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