Re: [apps-discuss] Appsdir review of draft-ietf-geopriv-relative-location

[Martin Thomson <[e-mail]>]

Hi Henry,

Thanks for the review.  I apologize for the delay in responding to your email.

I can't update the draft to address your concerns, but I'll work with Brian to ensure that the changes happen.

> From: Henry S. Thompson [mailto:[e-mail]]
> Minor Issues:
> 
>   3 The use of the phrases '"baseline" location' and '"reference"
>     location' to mean the same thing (?) is confusing in the extreme
>     (as is the fact that sometimes the phrase includes scare-quotes,
>     but sometimes not).
> 
>     For example, in the following, what is meant to be the difference
>     between the two highlighted phrases?
> 
>       "In particular, while it is possible to put all location
>        information into the 'reference' location (leaving an
>                              ^^^^^^^^^
>        universally broad 'baseline'), location objects SHOULD NOT have
>        all location information in the baseline location.  Doing this
>                                        ^^^^^^^^
>        would cause clients that do not understand relative location to
>        incorrectly interpret the baseline location (i.e., the
>        reference point) as the actual, precise location of the
>        client."
> 
>    Furthermore wrt this passage, either I'm confused, or there's a
>    mistake at the second highlighted point.  I was expecting
>    "relative", not "baseline" (or "reference").  After all, if all the
>    information is in the baseline, then there is no information in the
>    relative part, and so not processing it misses nothing???
> 
>    Ah, repeated re-readings have uncovered the origin of the problem,
>    further back:
> 
>      "A client that does understand this extension will interpret the
>       location within the relative element as a refinement of the
>       baseline location, which gives the reference location for the
>       relative offset."
> 
>    I read that the first five times as if it were bracketed like this:
> 
>       [a refinement of [the baseline location, which gives the
>        reference location for the relative offset]].
> 
>    But you mean it as if it were bracketed like this:
> 
>     [a refinement of the baseline location], [which gives the
>        reference location for the relative offset].
> 
>    So, I suggest you rephrase the whole sentence along the following
>    lines:
> 
>      "A client that does understand this extension will interpret the
>       location within the relative element as a refinement of the
>       baseline location.  The resulting refined location then gives
>       the reference location for the relative offset."
> 
>   With that change, the paragraph containing the first quote above
>   (the para beginning "The baseline location SHOULD be general
>   enough") is comprehensible, but still very dense.  I know
>   illustrations are hard when one is restricted to ASCII-art, but a
>   pair of examples would be a great help here, where one obeys the
>   rules, and is not understood wrongly by a non-extension-supporting
>   app, but the other breaks the rules, and therefore liable to be
>   interpreted wrongly by such an app.
> 
>   And, finally, perhaps just _after_ the example now at the end of
>   this section, just a brief gloss along the lines of
> 
>     The baseline location, given by the first ca:civicAddress element,
>     the first child of the gp:location-info, is a street address, to
>     the level of detail of the house number (123).  The reference
>     location is [now the front door, something else if you fix the 5.1
>     issue below].  The actual location, which is still within the
>     baseline building, is a point 100m east and 50m north [?] of the
>     front door.

Oh.  That's a bigger issue than you make out.  Baseline != reference.

Imagine if locations were boxes.  A baseline location is a big box.  A reference location is a small box inside the big box.  A relative location is another small box inside the big box.  To people that don't know this reference/relative stuff, they just see the big box.

I think that Brian and I will have to sit down and make some edits.  Your feedback will make that easier.

>   4.11.1
> 
>     "An 'http:' or 'https:' URL MUST be used unless . . ."
> 
>   Wouldn't it be more in the spirit of 2119 to say "A URI with scheme
>   other than 'http:' or 'https:' SHOULD NOT be used unless" ?

"SHOULD" is a weasel-word that SHOULD be avoided.  I like to reserve SHOULD for cases where I am not providing a clear description of the exception cases.  Most times, MUST works perfectly well if properly qualified.  As I believe this is.

>   5.1 Civic PIDF with Polygon Offset [also at end of section 3]
> 
>   This example uses the ca:INT element, which as far as I can tell is
>   only defined in the expired draft-rosen-geopriv-pidf-interior [1].

Yes, that does need to go.  We aren't pursuing that particular solution any more.  Those elements can just be eliminated.

>   5.2 Geo PIDF with Circle Offset
> 
>   Once the cut-and-paste error identified below in the 'Nits' section
>   is fixed, the result has 4 schema-validity errors, all of which I
>   presume should be straightforward to correct[[MT]] ...

Brian, please fix these.

> Nits:
> 
>   5.1, 5.2 [examples]
> 
>   These examples rely on schema documents which require moderately
>   tedious indirection via the XML registry [2] to find -- it would be
>   helpful if the references section at least included the relevant
>   RFCs, at least 3863, 4479 and 5139.

Please accept my apologies.  These are all indirectly referenced, but we can tighten that up.

>   6. Schema Definition
> 
>   The repeated pattern used for complex type definition in this schema
>   doc is[[MT]]  ...
>   This is overly . . . complex and invites confusion, [[MT]] ...
>   Please simplify all your complex type definitions along these lines.

I'm going to hold the line on this point.  XML Schema defines two ways to do the same thing and this draft consistently uses the form that permits other uses than complex type restrictions of the ur-type.  I see no good reason to switch to the syntactic sugar variant.