[tz] Update for tz-how-to.html?

[Paul Eggert]

Kerry Shetline wrote:
> Could we get an update to the tz-how-to.html document which:
> 
> 1) Explains how to parse tzdata files for vanguard, rearguard, and standard versions?

They should all be parsed the same way, using the rules documented in the zic 
man page. The only difference is that the non-vanguard formats might use subsets 
of the zic-documented features.

> It looks like the way vanguard sections are not commented out, and rearguard sections are, that any third-party parser for tzdata is going to pick up vanguard zones and rules by default, rather than main.

Yes, the intent was to move negative DST from vanguard to main format in 2018e, 
so if a 3rd-party parser picks up the main data it will now see negative DST. If 
a 3rd-party parser does not support negative DST, its users can either run 'make 
rearguard.zi' and feed that file to the parser, or use the rearguard-format 
tarball mentioned in the "PS" section of the most recent announcement (that 
tarball was built with "make rearguard_tarballs" so you can build it yourself if 
you like).

I'm hoping that the need for rearguard tarballs dies out in due course, as the 
kinks get worked out in 3rd-party parsers.

> What I’d like to know how to parse the tzdata files, directly as they are found in a standard distribution, with rearguard, main, or vanguard results in mind

Are you asking for documentation of exactly how to generate rearguard.zi and 
vanguard.zi from main.zi? That kind of processing is ad-hoc and it can change as 
new features are added and/or deprecated, so it is deliberately not documented 
elsewhere. For example, as of 2018e main.zi and vanguard.zi are identical so the 
only differences are between rearguard and everything else, but this may not be 
true of 2018f.

Although the source code for converting among the data formats is available in 
ziguard.awk, this code is ad hoc and is subject to change. The point of the 
vanguard/rearguard business is to accommodate format changes, after all.

> 2) Demonstrates the usage of the new ’s' and ‘d' suffixes in SAVE columns?

An example of the 'd' suffix is given in the zic man page, which is the place 
where SAVE columns are discussed. Look for "1:00d".