Re: [Tzdist] AD review of draft-ietf-tzdist-service-07 - Section 5

[Cyrus Daboo <[e-mail]>]

Hi Barry,
Replying to comments on Section 5 only.

--On May 7, 2015 at 9:57:05 AM +0100 Barry Leiba <[e-mail]> 
wrote:

> -- Section 5 subsections --
> *** Some of the URI templates (I'm thinking of 5.4 in particular) look
> confusing being split across lines.  I think you can get rid of that
> effect by starting the template on a new line from the heading.  Like
> this:
>
> OLD (5.1)
>    Request-URI Template:  {/service-prefix}/capabilities
> NEW
>    Request-URI Template:
>      {/service-prefix}/capabilities
> END
>
> OLD (5.2)
>    Request-URI Template:  {/service-prefix,data-
>       prefix}/zones{?changedsince}
> NEW
>    Request-URI Template:
>      {/service-prefix,data-prefix}/zones{?changedsince}
> END
>
> OLD (5.3)
>    Request-URI Template:  {/service-prefix,data-
>       prefix}/zones{/tzid}{?start,end}
> NEW
>    Request-URI Template:
>      {/service-prefix,data-prefix}/zones{/tzid}{?start,end}
> END
>
> OLD (5.4)
>    Request-URI Template:  {/service-prefix,data-prefix}/zones{/tzid}
>
>       /observances{?start,end}
> NEW
>    Request-URI Template:
>      {/service-prefix,data-prefix}/zones{/tzid}/observances{?start,end}
> END
>
> OLD (5.5)
>    Request-URI Template:  {/service-prefix,data-prefix}/zones{?pattern}
> NEW
>    Request-URI Template:
>      {/service-prefix,data-prefix}/zones{?pattern}
> END
>
> OLD (5.6)
>    Request-URI Template:  {/service-prefix,data-prefix}/leapseconds
> NEW
>    Request-URI Template:
>      {/service-prefix,data-prefix}/leapseconds
> END
>
> (I think it's best to be consistent with that, even for the ones that
> will fit on one line.)

Fixed.

> *** The >> Request << examples in Sections 5.3.4 and 5.4.1 are a bit
> more problematic.  The way you've broken it across multiple lines
> isn't consistent.  Take 5.4.1:
>
>    >> Request <<
>
>    GET /zones/America%2FNew_York/observances
>                       ?start=2008-01-01T00:00:00Z
>                       &end=2009-01-01T00:00:00Z
>                       HTTP/1.1
>
> The problem is that in the real protocol, there's no space before the
> "?" or the "&", but there is one before "HTTP/1.1"... and the way it's
> written gives no idea of that.  I'm not *too* worried about that,
> because it's an example, and because readers really do need to already
> know how HTTP GET requests work.  But it might be nice to try to think
> of a way to be clearer, without getting all wound up.
>
> Maybe it just works to merge the last three lines and reduce the
> indentation, and then add an explanation that the resulting two bits
> are meant to be one line, with no space between them.  As there are
> only two occurrences of this situation, it's not too cumbersome.  Like
> this:
>
> OLD
>    In this example the client requests a time zone in the expanded form.
>
>    >> Request <<
>
>    GET /zones/America%2FNew_York/observances
>                       ?start=2008-01-01T00:00:00Z
>                       &end=2009-01-01T00:00:00Z
>                       HTTP/1.1
>    Host: tz.example.com
>
> NEW
>    In this example the client requests a time zone in the expanded form.
>    (In the actual protocol, the "?start" follows "observances" on the
>    same line, with no intervening space.)
>
>    >> Request <<
>
>    GET /zones/America%2FNew_York/observances
>      ?start=2008-01-01T00:00:00Z&end=2009-01-01T00:00:00Z HTTP/1.1
>    Host: tz.example.com
>
> END
>
> What do you think?

I will make that change but will put the explanatory text into the 
Conventions section

> -- Section 5.1.1 --
> Is it really likely that servers will redirect "/.well-known/timezone"
> to "/" ?  Might it not be better to say in Section 5 something like,
> << The examples in the following subsections presume that the timezone
> context path has been discovered to be "/servlet/timezone" (as in the
> example in Section 4.2.1.3.1). >>, and then to change the examples
> accordingly:
>
> OLD
>    GET /capabilities HTTP/1.1
>    Host: tz.example.com
> NEW
>    GET /servlet/timezone/capabilities HTTP/1.1
>    Host: tz.example.com
> END
>
> ...and so on?

Fixed.

> -- Section 5.2 --
>
>    Parameters:
>       changedsince  OPTIONAL, but MUST occur only once.
>
> Oops; no.  It is not true that it MUST occur:
>
> NEW
>    Parameters:
>       changedsince  OPTIONAL, and MUST NOT occur more than once.
> END
>
> Similarly in Section 5.3.

Fixed.

> -- Section 5.2.1 --
> Entirely optional, but I think it would help the readability of the
> example to put blank lines before and after the ellipsis, and perhaps
> to change the ellipsis to "...other time zones...".  As it is, it's
> easy to miss the "..." by eye (at least I found it so, with my aging
> eyes).  (FWIW, the ellipses in 5.3.1 work fine for me, probably
> because they're not surrounded by punctuation and indentation.)

Fixed.

> -- Section 5.3 --
>
>       The "tzid" variable value is REQUIRED to distinguish this action
>       from the "list" action.
>
> It's easy to read this as saying that the value has to do something.
> Maybe make it "is REQUIRED, in order to".

Fixed.

> -- Section 5.3.5 --
> A nit, but the title doesn't make much sense:
>
> OLD
> 5.3.5.  Example: Get a non-existent time zone data
>
>    In this example the client requests the time zone with a specific
>    time zone identifier to be returned.
> NEW
> 5.3.5.  Example: Request data for a non-existent time zone
>
>    In this example the client requests the time zone with a specific
>    time zone identifier to be returned.  As it turns out, no time
>    zone exists with that identifier.
> END

Fixed.

> -- Section 5.5 --
> The explanation of pattern matching with "*" does not explain what
> happens if you put the wildcard character in the middle of the string.
> If I use "x*z", is that an error (with
> urn:ietf:params:tzdist:error:invalid-pattern
> )?  If so, you should say that explicitly.  If not, what does it do?

I'll add a statement that "*" MUST only appear at the start or end of the 
string, and use anywhere else MUST result in an error.

>       In addition, when matching, underscore characters (0x5F) SHOULD be
>       mapped to a single space character (0x20) prior to string
>       comparison.  This allows time zone identifiers such as "America/
>       New_York" to match a query for "*New York*".  ASCII characters in
>       the range 0x41 ("A") through 0x5A ("Z") SHOULD be mapped to their
>       lowercase equivalents.
>
> *** Why are these "SHOULD"s instead of "MUST"s?  That seems to be an
> interop problem, because "*new york*" can return various things,
> depending upon whether "_" mapping is or isn't used and whether case
> mapping is or isn't used.  The same query that worked for years could
> stop working because we switched to a new server or because the server
> software was changed.  Please explain and discuss.

Unless anyone objects I am OK with changing those to a MUST.

>       To match characters 0x2A ("*") and 0x5C
>       ("\") in the pattern, a single 0x5C ("\") is prepended to act as
>       an "escaping" mechanism. i.e., a pattern "Test\*" implies an exact
>       match test against the string "Test*".
>
> *** How is a query for "*New York*" (in the text above) done?  You
> can't send the space character in the GET command without making it
> "%20", and the mechanism for sending patterns doesn't appear to allow
> %-encoding.

I think percent encoding and decoding of the ?pattern URI query parameter 
is implicit in the nature of URI processing. However, I will make the 
following change as a reminder of that fact:

    Pattern match strings (which have to be %-encoded and then decoded when
    used in the URI query parameter) have the following options:

> Also, the "i.e." needs to be "e.g.", please.
>

Fixed.

-- 
Cyrus Daboo