[tz] [PROPOSED] Improve tzfile.5 formatting and clarity

[Paul Eggert]

* tzfile.5: Break out field descriptions into bulleted lists, to
make them easier to follow.  This does not change the technical
content of the spec, just its presentation.
---
 tzfile.5 | 77 ++++++++++++++++++++++++++++++++++++++++------------------------
 1 file changed, 48 insertions(+), 29 deletions(-)

diff --git a/tzfile.5 b/tzfile.5
index 52c5301..b7dc828 100644
--- a/tzfile.5
+++ b/tzfile.5
@@ -10,17 +10,29 @@ tzfile \- time zone information
 \\$3\*(lq\\$1\*(rq\\$2
 ..
 The time zone information files used by
-.IR tzset (3)
-begin with the magic characters "TZif" to identify them as
-time zone information files,
-followed by a character identifying the version of the file's format
-(as of 2013, either an ASCII NUL, or '2', or '3')
-followed by fifteen bytes containing zeroes reserved for future use,
-followed by six four-byte integer values
+.BR tzset (3)
+are typically found under a directory with a name like
+.IR /usr/share/zoneinfo .
+These files begin with a 44-byte header containing the following fields:
+.IP * 2
+The magic four-byte ASCII sequence
+.q "TZif"
+identifies the file as a time zone information file.
+.IP *
+A byte identifying the version of the file's format
+(as of 2017, either an ASCII NUL, or
+.q "2",
+or
+.q "3" ).
+.IP *
+Fifteen bytes containing zeros reserved for future use.
+.IP *
+Six four-byte integer values
 written in a standard byte order
 (the high-order byte of the value is written first).
 These values are,
 in order:
+.RS
 .TP
 .I tzh_ttisgmtcnt
 The number of UT/local indicators stored in the file.
@@ -40,28 +52,30 @@ The number of local time types for which data entries are stored
 in the file (must not be zero).
 .TP
 .I tzh_charcnt
-The number of characters of time zone abbreviation strings
+The number of bytes of time zone abbreviation strings
 stored in the file.
+.RE
 .PP
-The above header is followed by
+The above header is followed by the following fields, whose lengths
+vary depend on the contents of the header:
+.IP * 2
 .I tzh_timecnt
 four-byte signed integer values sorted in ascending order.
 These values are written in standard byte order.
 Each is used as a transition time (as returned by
-.IR time (2))
+.BR time (2))
 at which the rules for computing local time change.
-Next come
+.IP *
 .I tzh_timecnt
 one-byte unsigned integer values;
 each one tells which of the different types of local time types
 described in the file is associated with the time period
 starting with the same-indexed transition time.
-These values serve as indices into an array of
-.I ttinfo
-structures (with
+These values serve as indices into the next field.
+.IP *
 .I tzh_typecnt
-entries) that appears next in the file;
-these structures are defined as follows:
+.I ttinfo
+entries, each defined as follows:
 .in +.5i
 .sp
 .nf
@@ -87,20 +101,19 @@ gives the number of seconds to be added to UT,
 tells whether
 .I tm_isdst
 should be set by
-.I localtime (3)
+.BR localtime (3)
 and
 .I tt_abbrind
-serves as an index into the array of time zone abbreviation characters
+serves as an index into the array of time zone abbreviation bytes
 that follow the
 .I ttinfo
 structure(s) in the file.
-.PP
-Then there are
+.IP *
 .I tzh_leapcnt
 pairs of four-byte values, written in standard byte order;
 the first value of each pair gives the nonnegative time
 (as returned by
-.IR time(2))
+.BR time (2))
 at which a leap second occurs;
 the second gives the
 .I total
@@ -109,16 +122,14 @@ 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.
-.PP
-Then there are
+.IP *
 .I tzh_ttisstdcnt
 standard/wall indicators, each stored as a one-byte value;
 they tell whether the transition times associated with local time types
 were specified as standard time or wall clock time,
 and are used when a time zone file is used in handling POSIX-style
 time zone environment variables.
-.PP
-Finally there are
+.IP *
 .I tzh_ttisgmtcnt
 UT/local indicators, each stored as a one-byte value;
 they tell whether the transition times associated with local time types
@@ -126,7 +137,9 @@ were specified as UT or local time,
 and are used when a time zone file is used in handling POSIX-style
 time zone environment variables.
 .PP
-.I Localtime
+The
+.BR localtime (3)
+function
 uses the first standard-time
 .I ttinfo
 structure in the file
@@ -137,11 +150,12 @@ if either
 .I tzh_timecnt
 is zero or the time argument is less than the first transition time recorded
 in the file.
-.PP
+.SS Version 2 format
 For version-2-format time zone files,
 the above header and data are followed by a second header and data,
 identical in format except that
 eight bytes are used for each transition time or leap second time.
+(Leap second counts remain four bytes.)
 After the second header and data comes a newline-enclosed,
 POSIX-TZ-environment-variable-style string for use in handling instants
 after the last transition time stored in the file
@@ -154,7 +168,7 @@ then if a last transition time is in July, the transition's local time
 type must specify a daylight-saving time abbreviated
 .q "WEST"
 that is one hour east of UT.
-.PP
+.SS Version 3 format
 For version-3-format time zone files, the POSIX-TZ-style string may
 use two minor extensions to the POSIX TZ format, as described in
 .IR newtzset (3).
@@ -166,6 +180,11 @@ between daylight saving and standard time.
 .PP
 Future changes to the format may append more data.
 .SH SEE ALSO
-newctime(3), newtzset(3), zdump(8), zic(8)
+.BR time (2),
+.BR localtime (3),
+.BR tzset (3),
+.BR tzselect (8),
+.BR zdump (8),
+.BR zic (8)
 .\" This file is in the public domain, so clarified as of
 .\" 1996-06-05 by Arthur David Olson.
-- 
2.7.4