Subject: [Ltru] editorial comments on draft-07 (part 1)

From: Martin Duerst <[email-masked]>
Date: Mon, 05 Dec 2005 19:13:16 +0900

[chair hat off]
These are my editorial comments on draft-ietf-ltru-matching-07.
Some may be duplicates of things already fixed.

General:
Some of the examples appear as "Figures". But the numbers are
not consecutive. None of the examples are really figures, and
they are all completely integrated into the text, so I propose
no not use any 'figure' stuff. (things might look slightly
different in the HTML version, but it's the ASCII version
that ultimately counts)

Abstract:
- should contain the words 'filtering' and 'lookup'

Section 1, second para, 1st sentence: "Information ... need ..."
   need -> needs

Section 1, End: Please given a short overview over the document.

Section 2, first para, last sentence: "These": It's not clear
what "These" refers to.

Section 2.1: Lists of Language Ranges:
- We are using the term "Language Priority List", so probably
   better to use it in title, too.
- This section should come after 2.3, or possibly even after
   2.4 (if after 2.3, then 2.4 might be renamed to "Choosing Language Ranges"
- second para: A ... List" consists of ... a ... list:
   'consists of' -> is
- last para: 'include considerations': If we don't define any actual
   syntax, we should clearly say so:
   "This document does not define any syntax for a "Language Priority List";
   defining such a syntax is the responsibility of the
   protocol/implementation/application." [see separate mail]

Section 2.2: Basic Language Range
- "A basic language range is identified by its 'language range' tag...":
   I think we should call tags tags, and ranges ranges.
- Refers to RFC 2616 for 'language-tag'. We should say that this
   is equivalent (in whatever way it is, probably just well-formed)
   to a language-tag from RFC3066bis.
- last para: 'as simply a "language range"' -> 'simply as "languge ranges"'
   (make numbers agree)

Section 2.3: Extended Language Range
- First line of ABNF looks as if it were part of text. Add some space
   before ABNF, and make sure at least comment alligns.
- last paragraph: We have two MAYs here. These get combined with
   the MAYs in the various matching scheme sections. And then this
   gets combined with the implementation/protocol/application issue.
   It may be worth checking whether the various matching sections
   do not already cover, in one way or another, the MAYs in this
   section, and if they do so almost but not quite, whether we
   could not fix it.

Section 2.4: Coosing a language range
- first para: "for given user" -> "for a given user"
- A lot of the advice in this section is dependent on which
   matching scheme is used. It should therefore be moved to
   section 4.
- 3rd para: 'orthogonal': What does that mean in this context?
- 3rd para: 'users SHOULD avoid using these subtags': True
   for filtering, wrong for lookup. Overall, we should be
   clearer and say that for filtering, use the shortest
   possible tags, or add shorter tags as an alternative to
   longer ones [the text from the HTTP spec about adding 'en'
   if you have 'en-GB' could be reused], but for lookup,
   use longest possible tags to make sure you get your
   preferred selection if it is available.
- 4th para: Having a numbered list here doesn't make sense,
   it looks like just a continuation of the first three
   paragraphs.
- 4th para: 'users SHOULD note': if there is anything
   relevant to interoperability that users should DO, then
   say so. But please try to avoid SHOULD for 'note'.
- 4th para, 1.: "Implementations ... SHOULD ...": this
   belongs into the relevant matching scheme sections,
   not in the section about user advice. Same for the
   rest of the numbered list.
- 4th para, 2., last sentence:
   "... if services ... would ..." => "... to services ... that ..."
- 4th para, 3.: "the one of the": remove first 'the'

Section 3, first para: "types of matching scheme" =>
   "types of matching schemes"

Section 3.1 Choosing a type of matching
- second para: "one might use" => "one can use"
- numbered list: I think it would be better to have four
      items here, making lookup the fourth, and change the
      introductory sentence to "This document describes three
      types of filtering and one type of lookup:" or
      "This document defines the following matching schemes:".
- numbered list, 2.: 'implementations' [see separate mail]
- numbered list, 3.: "using either basic or extended language
      ranges": I haven't found an option 'basic range only'
      in Scored Filtering. If there is, it wouldn't make
      sense to me, actually. So I propose we remove this
      phrase, or change it to "using extended langugage ranges".

- first para after numbered list: "when each request MUST":
      From the viewpoint of our spec, this is just a precondition.
      So a MUST is inappropriate.

Part two to follow tomorrow.      Regards,    Martin. 

_______________________________________________
Ltru mailing list
[email-masked]
https://www1.ietf.org/mailman/listinfo/ltru

---

From: "Addison Phillips" <[email-masked]>
Date: Tue, 6 Dec 2005 12:03:09 -0800

Comments follow...

Addison P. Phillips
Globalization Architect, Quest Software

Internationalization is not a feature.
It is an architecture. 

> -----Original Message-----
> From: Martin Duerst [mailto:[email-masked]]
> Sent: Monday, December 05, 2005 11:23 PM
> To: Addison Phillips; LTRU Working Group
> Subject: RE: [Ltru] editorial comments on draft-07 (part 1)
> 
> Hello Addison,
> 
> Many thanks for your speedy work. Some comments below:
> (all the stuff I cut out is okay with me)
> 
> At 04:58 05/12/06, Addison Phillips wrote:
> 
>  >> -----Original Message-----
>  >> Martin Duerst
>  >> Sent: Monday, December 05, 2005 2:13 AM
> 
>  >> [chair hat off]
> Did you do anything about this? All the other items at least
> say 'DONE'.
[Addison Phillips] 

Simply: I missed this comment. I'll note that I went through previously and inserted 'id' attributes for everything, which are the source of the figure numbers, etc. I can remove as necessary, but haven't done it yet.
>  >[Addison Phillips]
>  >Uh... okay. I added:
>  >--
>  ><t>This document is divided into three main sections. The first section
>  >described language ranges, which are used to specify a user's
> preferences.
>  >The second describes different mechanisms for matching ranges to content.
>  >The third main section deals with various considerations that apply to
>  >using the mechanisms described in this document.</t>
>  >--
> 
> Nice, except for the fact that what you call 'first section' is
> Section 2, and so on. Can you change that as follows?
> 
> <t>The rest of this document is divided into three main sections. Section
> 2
> describes language ranges, which are used to specify a user's preferences.
> Section 3 describes different mechanisms for matching ranges to content.
> Section 4 deals with various considerations that apply to
> using the mechanisms described in this document.</t>
[Addison Phillips] 

How about being less specific about placement:

--
<t>This document is divided into three main sections. One describes how to indicate a user's preferences using language ranges. Then a section describes various schemes for matching these ranges to a set of language tags in order to select specific content. There is also a section that deals with various practical considerations that apply to implementing and using these schemes.</t>
--
>  >[Addison Phillips]
>  >It actually refers to language tags defined by RFC 3066. We could
> reference
>  >RFC 3066 instead. Notice that language ranges are not required to be
> either
>  >well-formed or valid! There should probably be a health warning for
> invalid
>  >or not-well-formed ones....
> 
> Okay, yes, please say so. Looking at the original text again,
> I'd probably just say something very short like:
> "A Language Range is defined by the following ABNF" before
> the ABNF, and then after the ABNF mention that this is the
> same as in HTTP and RFC 3066, but different [details here]
> from RFC 3066bis.
[Addison Phillips] 

Okay. This required massive text reconstruction. A look at the editor's copy (when I post it in a bit) is the best way to check that text. If the date on the copy is today's date (6 December 2005) then you're looking at the new text.
> 
> On an aside, why is RFC 2616 normative? We have a complete
> definition of language-range, so we don't need it normative
> here. And I don't remember any other place where it is normative.
[Addison Phillips] 

It doesn't need to be. Moved it to informative.
>  >[Addison Phillips]
>  >I don't think we can remove these MAYs: they define the syntax.
> 
> Not exactly. Syntax just says which things are extended language
> ranges, and which are not. So we should just say that en-US and
> en-*-US are extended language ranges.
> 
> The semantics of these ranges, although to some extent defined
> in section 2, is really only fully clear from section 3. If it
> turns out that under all (relevant) schemes, with all options,
> en-US and en-*-US are indeed equivalent, we should say this
> directly. If they are not equivalent for all schemes/options,
> then we better remove these MAYs.
[Addison Phillips] 

This is an important point for implementers who normalize a user's input. Thus both "sl-nedis" and "sl-*-*-nedis" can be formatted as "sl-*-nedis". To make this clear and normative, I changed this para to:

--
<t>A field not present in the middle of an extended language range is treated as if the field contained a "*". Implementations that normalize extended language ranges SHOULD expand missing fields to be "*" so that the semantic meaning of the language range is clear to the user. At the same time, multiple wildcards in a row are redundant and implementations SHOULD collapse these to a single wildcard when normalizing the range (for brevity). For example, both the range "sl-nedis" and the range "sl-*-*-nedis" are equivalent to and should be normalized as "sl-*-nedis".</t>
--
>  >[Addison Phillips]
>  >"It" meaning the section? Or the advice?
> 
> The section, with the advice in it, or the advice, with
> the section it is in, whichever you prefer :-).
[Addison Phillips] 

Very well. Done.
>  >[Addison Phillips]
>  >Users really should avoid extensions when doing lookup too.
> 
> Can you explain why? They don't hurt at all, or do they?
[Addison Phillips] 

There are a variety of reasons. Mainly they obscure meaning and might skew results as subtags are truncated. Secondly, if a subtag is really orthogonal, it probably has no bearing on the text selection. Finally, a range might be used in both filtering and lookup operations from the same request. The result there might be confusing indeed.
> 
>  >I agree about the second point, though. I need to mull over text (please
>  >suggest some and a location?)
> 
> I suggested text from
> http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.4:
> 
> Note: When making the choice of linguistic preference available to
>        the user, we remind implementors of  the fact that users are not
>        familiar with the details of language matching as described above,
>        and should provide appropriate guidance. As an example, users
>        might assume that on selecting "en-gb", they will be served any
>        kind of English document if British English is not available. A
>        user agent might suggest in such a case to add "en" to get the
>        best matching behavior.
> 
> This doesn't exactly fit the viewpoint that our document takes,
> so here's a very drafty rewrite.
> 
> For filtering, users should use the shortest applicable language
> range, or should add shorter language ranges to a language priority
> list after longer language ranges if they want to express their
> priorities while also accessing more general content.
> As an example, somebody who prefers British English, in addition
> to "en-gb" should add "en" to their language priority list
> to make sure English documents are found even if British
> English isn't available.
> 
> As for location, after the place we talk about using longer
> tags for lookup should work, or maybe even before.
> 
> 
>  >[Addison Phillips]
>  >Very well. Changed to symbols. Previously we used numbers to make things
>  >easier to reference...
> 
> No, what I meant is that it's strange to have a series of
> paragraphs containing advice, and then suddenly a few
> of them are numbered, or bulleted, or whatever.
> Or in other words, in "Coosing a Language Range", I don't
> understand why some parts are simple paragraphs, and others
> are part of a list.
[Addison Phillips] 

Because the editor was told to insert a list? I can make it not a list.
>  >[Addison Phillips]
>  >Good point. Rewrote the bullet items here to make them applicable to
> users.
>  >Then inserted this into the section on lookup:
>  >
>  >--
>  ><t>Implementations SHOULD ignore extensions and unrecognized private-use
>  >subtags when performing lookup, since these subtags are usually
> orthogonal
>  >to the user's request.</t>
> 
> I still don't see why we need to say that. Longer tags
> don't hurt lookup, and if the user put some subtags
> there, it's probably because they mean it. Or did I get
> something wrong here?
[Addison Phillips] 

They don't necessarily hurt anything, except to make the ranges less obvious and more difficult to work with. Also, since extensions are expected to be orthogonal, lookups that use them may produce less desirable results?
>  >[Addison Phillips]
>  >This might not have occurred to anyone else, but (well-formed, which is
> a
>  >bit of a presumption) basic language ranges are already extended ranges
> 
> Yes. Maybe the best thing to do is to say so in the section on
> extended ranges?
> 
Done.