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

From: "Addison Phillips" <[email-masked]>
Date: Mon, 5 Dec 2005 11:58:51 -0800

Comments follow...

Addison

Addison P. Phillips
Globalization Architect, Quest Software

Internationalization is not a feature.
It is an architecture. 

> -----Original Message-----
> From: [email-masked] [mailto:[email-masked]] On Behalf Of
> Martin Duerst
> Sent: Monday, December 05, 2005 2:13 AM
> To: LTRU Working Group
> Subject: [Ltru] editorial comments on draft-07 (part 1)
> 
> [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'
[Addison Phillips] 

Change a sentence to read:

--
Possible algorithms for language negotiation or content selection, filtering, and lookup are described.
--
> 
> Section 1, second para, 1st sentence: "Information ... need ..."
>    need -> needs
[Addison Phillips] 

Done.
> 
> Section 1, End: Please given a short overview over the document.
[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>
--
> 
> Section 2, first para, last sentence: "These": It's not clear
> what "These" refers to.
[Addison Phillips] 

Changed to read:

--
<t>For example, <xref target="RFC2616">HTTP/1.1</xref> describes one such mechanism in its discussion of the Accept-Language header (Section 14.4), which is used when selecting content from servers based on the language of that content.</t>
--
> 
> Section 2.1: Lists of Language Ranges:
> - We are using the term "Language Priority List", so probably
>    better to use it in title, too.
[Addison Phillips] 

Done

> - 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"
[Addison Phillips] 

It was moved before 2.4 (which discussed choosing a list as well!)

> - second para: A ... List" consists of ... a ... list:
>    'consists of' -> is
[Addison Phillips] 

Done.

> - 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]
[Addison Phillips] 

Inserted it thusly:

This document does not define any syntax for a language priority list; defining such a syntax is the responsibility of the protocol, application, or implementation that uses it.
> 
> 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.
[Addison Phillips] 

I changed the sentence to cover this in a cleaner manner:

---
A "Basic Language Range" identifies the set of content whose language tags begin with the same sequence of subtags. A basic language range is a sequence of alphanumeric subtags separated by hyphens following the ABNF in HTTP/1.1 :
---

> - 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.
[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....

> - last para: 'as simply a "language range"' -> 'simply as "languge
> ranges"'
[Addison Phillips] 

Went the other direction and changed the subject to singular.

> 
> 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.
[Addison Phillips] 

Done.

> - 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.
[Addison Phillips] 

I don't think we can remove these MAYs: they define the syntax. How schemes deal with that syntax can vary.
> 
> Section 2.4: Coosing a language range
> - first para: "for given user" -> "for a given user"
[Addison Phillips] 

Already fixed.

> - A lot of the advice in this section is dependent on which
>    matching scheme is used. It should therefore be moved to
>    section 4.
[Addison Phillips] 

"It" meaning the section? Or the advice?

> - 3rd para: 'orthogonal': What does that mean in this context?
[Addison Phillips] 

Reworked this para to say:

--
<t>When working with tags and ranges, note that extensions and most private-use subtags are orthogonal to language tag matching, in that they specify additional attributes of the text not related to the goals of most matching schemes. Users SHOULD avoid using these subtags in language ranges, since they interfere with the selection of available content. When used in language tags (as opposed to ranges), these subtags normally do not interefer with <xref target="types">filtering</xref>, since they appear at the end of the tag and will match all prefixes.</t>
---

> - 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.
[Addison Phillips] 

Users really should avoid extensions when doing lookup too.

I agree about the second point, though. I need to mull over text (please suggest some and a location?)

> - 4th para: Having a numbered list here doesn't make sense,
>    it looks like just a continuation of the first three
>    paragraphs.
[Addison Phillips] 

Very well. Changed to symbols. Previously we used numbers to make things easier to reference...

> - 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'.
[Addison Phillips] 

Okay. Changed from "users SHOULD note" to "note that"

> - 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.
[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>
--

> - 4th para, 2., last sentence:
>    "... if services ... would ..." => "... to services ... that ..."
[Addison Phillips] 

Done.

> - 4th para, 3.: "the one of the": remove first 'the'
[Addison Phillips] 

Done.
> 
> Section 3, first para: "types of matching scheme" =>
>    "types of matching schemes"
[Addison Phillips] 

Okay.... except I changed it to the less exclusive "several different matching schemes". There might be others: we don't preclude their existence.

> 
> Section 3.1 Choosing a type of matching
> - second para: "one might use" => "one can use"
[Addison Phillips] 

That text was already modified. The "one ..." syntax was removed.

> - 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:".
[Addison Phillips] 

That does look better. Done.

> - numbered list, 2.: 'implementations' [see separate mail]
[Addison Phillips] 

See separate thread.

> - 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".
[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 and thus can be used in scored matching quite easily. Hence the text here. But I changed it.
> 
> - 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.
[Addison Phillips] 

Done.
> 
> 
> Part two to follow tomorrow.      Regards,    Martin.
> 
> 
> _______________________________________________
> Ltru mailing list
> [email-masked]
> https://www1.ietf.org/mailman/listinfo/ltru
_______________________________________________
Ltru mailing list
[email-masked]
https://www1.ietf.org/mailman/listinfo/ltru

---

From: Martin Duerst <[email-masked]>
Date: Tue, 06 Dec 2005 16:23:10 +0900

Hello Addison,

Many thanks for your speedy work. Some comments below:
(all the stuff I cut out is okay with me)

 >> different in the HTML version, but it's the ASCII version

Did you do anything about this? All the other items at least
say 'DONE'.

 ><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>

(please note that I also changed one 'described' to 'describes')

 ><t>For example, <xref target="RFC2616">HTTP/1.1</xref> describes one such
 >mechanism in its discussion of the Accept-Language header (Section 14.4),
 >which is used when selecting content from servers based on the language of
 >that content.</t>
 >--

Looks fine.

 >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.

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.

 >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.

 >"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 :-).

 >Users really should avoid extensions when doing lookup too.

Can you explain why? They don't hurt at all, or do they?

 >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.

 >Very well. Changed to symbols. Previously we used numbers to make things

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.

 >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?

 >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?

Regards,   Martin.

 >and
 >thus can be used in scored matching quite easily. Hence the text here. But
 >I changed it.