On Thu, Sep 28, 2006 at 01:22:09PM +0700, Robert Elz wrote:
| Okay, here's what I came up with --- not so much rewording as | adding clarifications:
I'm not sure that is the best approach - we can keep on adding more and more clarifications, and that just means more and more text to confuse people.
What's really needed is to be as precise as possible, as briefly as possible, so there's less room left for confusion or ambiguity.
Sure, but I wasn't finding a better way to remove the confusion that has been seen than just adding the "clarifications". If someone else can do a better job of making the text less susceptible to misinterpretation I'd be happy to see that text used instead.
| -Input lines are made up of fields. | +Input lines are made up of | +.B specified | +fields.
I doubt that adding that word by itself will accomplish anything, all that leads to is "what are specified fields ?"
Yeah, probably so. My intent was to try and get rid of the "there may be zero to three extra space-separated fields in a Zone line if UNTIL is specified" misunderstanding by claiming that the document only *specifies* the six fields. I was probably being optimistic in thinking that the above "magic word" would help. I like your suggestion about wording for the UNTIL field (below), which handles this problem much more neatly.
However, I'm not sure we should say (anywhere) "saving time", as "saving" (with respect to time, or for that matter, daylight) has nothing at all to do with what is happening (saving energy perhaps). It is probably best just to call them "standard" and "alternate" time offsets (or something like that).
I was just following the current convention: there are currently 79 mentions of "saving time", 28 mentions of "savings time" and zero mentions of "alternate time" in the tzcode+tzdata tree. I probably should have said "summer time" though --- 123 mentions of that term.
| -Gives the first year in which the rule applies. | +Gives the first year in which the transition rule applies.
Adding that word helps nothing, the earlier addition already made clear that the rules are transition rules.
I added it for emphasis. Emphasis is a useful thing; if one skimmed too quickly over the first mention, the modifier here would give one pause about "what is that `transition' adjective there for?"
| +Note that the | +.I offset | +that the rule transitions will continue on until the next | +transition occurs, | +no matter how far in the future of the | +.B FROM | +or | +.B TO | +years that may be.
(That's the one you sent alternative (better) wording for in a later message).
I don't think that's needed at all - simply saying (along with the definition of the rules as transitions) that the offset at time X is that given by the most recent transition before (or at) X should be enough.
Should be: maybe. But will it really be? In this very thread I've seen the misinterpretation that this sentence is addressing crop up after already explaining once about "transitions". The depth of the confusion I've seen on this point makes me think that harping on the correct understanding is a good thing.
| +This might be used, for example, to have a rule which applies only in | +leap years.
That's OK, I guess, but I'm not sure it is needed. As long as the field isn't used, no-one much cares what it might be used for (except the very few people who write data for these files and even then only in unusual cases - most people are concerned with extracting the data). Where the field is used, its purpose is generally both well commented, and really obvious.
I added it because I recall someone once being puzzled about its purpose, and I thought I'd address that as long as I was wordsmithing. The places it is currently used is the "pacificnew" zone, which seems a bit obscure, and the yearistype.sh script itself. While by the very nature of the beast, more folk will refer to this document for the purpose of interpreting the tzdata files, I think that the document should nevertheless also be suitable as stand-alone documentation for those who compose rules. Because the use of a TYPE other than "-" is so rare I felt that it would be useful to spell out its rationale in this "primary documentation" of the file format.
| +Note that, as a special case, references to a rule's | +.B LETTER/S | +field | +(through a %s in a zone line's | +.B FORMAT | +field) | +for a date which predates the oldest date specified in a given rule | +will be assigned the | +.q "variable part" | +specified by the oldest | +.I standard time | +(i.e., with a | +.B SAVE | +value of zero) | +transition specified for the named rule.
It may be better to have something in general which specifies how to process data before the first transition (and for when there are no transitions at all) - both for the zone name abbreviation, and for the offset to use,
My wording is bad: sure. But I think you're misrepresenting the problem being addressed. If a *Zone* transition is in the future of the first *Rule* transition, the only plausible confusion is what to substitute for a variable-text FORMAT --- the "alternate time" offset should be zero seconds away from the GMTOFF. The text above is trying to specify that the *Rule* line with the oldest date that also has a zero SAVE value is the text to use.
as in general we are (or should) be telling people normally to locate the preceding transition - we do need to say what to do when there is no preceding transition.
Other than a match-up issue between Zone and Rule transitions, there is no well-defined concept of "before the first transition". With the sole exception of handling a variable-text part of a FORMAT, a lack of *Rule* transitions preceding the first (or any other) *Zone* transitions means "there are no transitions, so this is a no-op". I guess we could emphasize that the SAVE offset from the GMTOFF would be zero seconds in this case, but that seems excessive to me.
| -It is specified as a year, a month, a day, and a time of day. | +This field, which is logically a single field in the sense of the | +high-level description, consists of whitespace separated subfields | +consisting of a year, a month, a day, and a time of day.
I think this is the wrong way to explain this - better to explain that the final field contains whatever data is left on the input line, white space included, after all previous fields have been assigned values.
Then it wiil be fine to say that the until field contains year month day & time.
I agree: that's a better way.
| -The next line must be a | +The next line | +.I must | +be a
Putting "must" in italics is just wrong - if it needed emphasising at all (which I don't think it does), it should be bold, not italics. Just leave that one the way it was.
*shrug* If this were HTML I'd use <em>must</em>, not <strong>must</strong>, as I just wanted to emphasise this requirement. A minor style point; I'll defer to ADO's discretion of what (if any) font change to apply there. --Ken Pizzini