* Re: [man]: Bullet lists
[not found] ` <ZTUAUNdgca8s1Kkp@debian>
@ 2023-10-22 11:14 ` Alejandro Colomar
0 siblings, 0 replies; only message in thread
From: Alejandro Colomar @ 2023-10-22 11:14 UTC (permalink / raw)
To: Paul Eggert; +Cc: Time Zone Database, mandoc
[-- Attachment #1: Type: text/plain, Size: 21184 bytes --]
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 <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
> >
>
>
> --
> <https://www.alejandro-colomar.es/>
--
<https://www.alejandro-colomar.es/>
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] only message in thread