Question on abbreviations

[Ken Pizzini]

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