Subject: [Lager] [lager] #36 (specification): Editorial Feedback

From: "lager issue tracker" <[email-masked]>
Date: Fri, 19 Feb 2016 04:47:24 -0000

#36: Editorial Feedback

 Received on the list from A. Sullivan

 Dear colleagues,

 I have read draft-ietf-lager-specification-08, but I haven't reviewed
 the appendices.  I have a few comments.  These are all pretty minor,
 but I think that fixing them would make IETF last call easier.  I
 think the document could go ahead without any of these changes if you
 like.

 I note the document uses RFC 2119 keywords, but there's no reference
 to it.  Any reason?  (Probably wise to fix this; I think it's a
 shepherd checklist thing anyway.)

 §3.2: to follow the 2119 convention more closely, this could say

     Each "lgr" element MAY contain zero or one "meta" element, MUST
     contain exactly one "data" element, and MAY contain zero or one
     "rules" element; these three elements MUST be in that order.

 I don't feel strongly about this.

 §3.3

     The "unicode-version" element MUST be used by
    a consumer of the table to identify that it has the correct Unicode
    property data to perform operations on the table.

 Given that the meta element is optional, what does a consumer do if
 it's not there?

 If a document is not versioned (3.3.1), that would seem to make it
 possible for two interoperating consumers to use the "same" LGR and
 get different results.  That would seem to be a bad thing.  Maybe say
 that an LGR SHOULD have either a version or a date (or both), and note
 the possibile consequences for interoperation if that fails?

 §3.3.3 uses "specific" a lot, and I don't understand what distinction
 it is making.  For instance, "If the LGR applies to a specific
 script…" Is this to distinguish LGRs that apply to generic scripts?
 If so, some text here explaining that would help.  Is this the point
 of the "specific set of multiple languages or scripts" text?  (In that
 case, I'm not sure "specific" is wanted.)

 §3.3.4, "MUST be a valid absolute domain name, without a trailing
 dot."  I'd spell that "a domain name written relative to the root
 zone, in presentation format."  But that makes the whole thing kind of
 strange, because you can represent the root zone (with ".").  Also,
 what is a valid domain?  Is this a name that conforms to STD 13?  I
 think that won't work, because there's no way to tell what encoding
 the name is in, so you can't tell what the octets are.  I'd restate
 this all as 'MUST be a valid domain name under IDNA2008 (i.e. a name
 either containing at least one U-label or else a name made entirely of
 NR-LDH labels).  It MUST be written relative to the root zone, in
 presentation format; or else it MUST refer to the root zone itself,
 using the presentation format ".".'  This is slightly problematic,
 however, because it means that it wouldn't be possible to use this
 mechanism to refer to policies that permitted (say) plain Unicode
 characters in domain name labels.  Given the use case, that's probably
 ok, but it means this mechanism won't work for names in (say)
 apple.com (which reportedly uses spaces in SRV labels for wide-area
 Bonjour).

 This section also says 'values must be in a namespace "apptype"
 previously defined in the document,' but doesn't say how to do that.
 (Might be ok, but say something like "according to usual XML document
 rules" or something?)

 In §4, would it be prudent to say that a consumer of the LGR that
 encounters either indistinct cp elements or ranges overlapping a cp
 should simply reject the whole LGR?  Or what should they do?  That is,
 does an error invalidate the document or just cause the element to be
 ignored?  (I guess this is a general question.)

 In §4.3.2: if you don't use the pre-defined dispositions, what bad
 thing happens?  That is, why is this SHOULD?  (I guess I'm asking
 whether this is 2119 SHOULD or whether it's just a pretty good idea.)

 §4.3.5 has a STRONGLY RECOMMENDED, which is really just advice (and
 anyway isn't a 2119 keyword).  I think the reasoning is clear.

 In § 5.2, it's a little strange that the text goes out of its way to
 talk about not using the term "set", and then goes on to use the same
 word freely.  I'd stick to "character class" for the reasons given.

 §6.3 uses that pretty-good-idea meaning of RECOMMENDED again.  Why is
 it recommended?  What bad thing happens if not?  In the description of
 blocked, there's something wrong with the text such that I can't
 understand it: "variant that has is undesirable as" I think the "has"
 is just superfluous?  Also, in all of this, why "should"?  Isn't this
 mostly "may"?

 Best regards,

 A

 --
 Andrew Sullivan
 [email-masked]

-- 
-------------------------+-------------------------------------------------
 Reporter:               |      Owner:  draft-ietf-lager-
  [email-masked]   |  [email-masked]
     Type:  defect       |     Status:  new
 Priority:  minor        |  Milestone:
Component:               |    Version:
  specification          |   Keywords:
 Severity:  -            |
-------------------------+-------------------------------------------------

Ticket URL: <https://trac.tools.ietf.org/wg/lager/trac/ticket/36>
lager <https://tools.ietf.org/lager/>

---

From: "lager issue tracker" <[email-masked]>
Date: Fri, 19 Feb 2016 04:50:03 -0000

#36: Editorial Feedback

Comment (by [email-masked]):

 While they touch many instances in the document, the changes are minor, as
 they do not reflect a change in what is specified or the intent of the
 spec, but are more about editorial conventions / wording / clarification.
 (Except for the suggestion of how to specify the contents of the scope
 element).

 Here's my take on it. The results will be pushed up to the github for
 review.

 > think the document could go ahead without any of these changes if you

 I've created a version that attempts to address most of these and pushed
 it up to
 the github pending review.

 This version also fixes the example noted in
 https://trac.tools.ietf.org/wg/lager/trac/ticket/35
 (but I have not done anything about the schema)

 > shepherd checklist thing anyway.)
 I put a citation in to the normative references, but haven't referenced it
 from the text.
 If we want it we can add that  - where?, if not, it's easy to take out.
 > I don't feel strongly about this.

 I think your wording is fine. I also checked the language for cases where
 optional->OPTIONAL makes sense and made a few may->MAY and cannot -> MUST
 NOT where appropriate (e.g. description of when attributes cannot occur).

 I have generally aimed at using the rfc2119 language only where an
 attribute is defined (or its use for an element is described in detail,
 not for first mention in an earlier context).

 > Given that the meta element is optional, what does a consumer do if

 The intent was that a valid unicode-version becomes mandatory if and when
 a construct

         < class property="ppp:vvvv" />

 is encountered. In that case, the spec intends that the consumer MUST NOT
 evaluate this construct, unless it can support the given version of the
 Unicode Standard.

 I believe the existing language adequately expresses that; perhaps you
 could suggest more specific improvements to the wording. (There's that
 word again ;) ).

 We did not want to require a Unicode version in cases where an LGR just
 lists code points(*), and we also didn't want to force processes that do
 not need to run the whole label evaluation rules to reject the XML, just
 because, for example, they don't support Unicode property access or the
 correct version. (For example, I can write an LGR-merge processor or LGR-
 diff engine that would need to process the file, but does not evaluate
 such property-based classes).

 (*) for that case, if one wanted to know which Unicode version is
 minimally required one could compute that based on the "DerivedAge"
 property (highest value for any code point encountered is the minimally
 required version of Unicode). So the version is not needed for static
 lists of code points.

 > the possibile consequences for interoperation if that fails?

 Perhaps this simple note in the <metadata> section addresses the issue:

                    <t>While neither a version nor a date element are
 required, their
                     omission makes it harder for interoperating consumers
 to ensure that
                     they are using the correct LGR. Their inclusion
 RECOMMENDED.</t>

 > case, I'm not sure "specific" is wanted.)
 Point well taken. In some cases the word is used where "some" or "a given"
 is intended.
 I've made those changes.

 I propose to resolve two specific instances of "specific" in this specific
 way:

     Each optional "language" element identifies a language or script for
 which the LGR is intended... The tag may refer to a script plus undefined
 language if the LGR is not intended for a specific language.

 The original language had "associated with" and "referring to" as the
 verbs, but I believe "intended for" is what we intended to get across.
 "Applies to" also works, so I kept that in the following sentence where I
 moved the "specific" from "script" to "language"

         If the LGR applies to a script, rather than a specific language..
 > apple.com (which reportedly uses spaces in SRV labels for wide-area

 I think we would want to discuss this a bit further.
 > (Might be ok, but say something like "according to usual XML document

 Not sure about the best language, so no change.
 > ignored?  (I guess this is a general question.)
 It's a bit of a general question. Some constraints are in the schema and
 make the document invalid on that level, but others are not, yet are
 definite error conditions where the document should be rejected (rather
 than an element ignored). I've identified four places where one could make
 that statement without having to repeat it at every level, but also close
 enough to the definitions as to not be totally generic.

 I think this addition would be useful (at the end of §4):

         An LGR that defines the same code point more than once by any
 combination of "char" or "range" elements MUST be rejected.

 And at the end of §4.3.1 (on variants being unique)

              ....attributes, otherwise the document MUST be rejected.

 And at the end of §5.1

         An LGR containing incorrectly defined or nested rules or match
 operators, or rules and match operators with invalid attributes or invalid
 or undefined attribute values MUST be rejected. Note that not all of the
 constraints defined here are validated by the schema.

 And finally in §6.1, a change to the second paragraph:

         An action MUST NOT contain both a "match" and a "not-match"
 attribute, and the value of either attribute MUST be the name of a
 previously defined rule, otherwise the document MUST be rejected. An
 action without any attributes is triggered by all labels unconditionally.

 Incidentally, there's no such restriction on the contents of the other
 attributes and for the variant triggers I now note that explicitly. (We
 want to allow actions that are "no-ops" unless specific types of variants
 occur in the LGR, so that we can write default actions. However, for
 rules, we want to be able to make sure that the processor can locate a
 rule, so those are mandatorily defined - all of this is not new, just more
 explicit thanks to your comment.

 > whether this is 2119 SHOULD or whether it's just a pretty good idea.)

 The intent is to really discourage people from using novel names for
 standard
 dispositions. (Makes the whole thing more interoperable).
 > anyway isn't a 2119 keyword).  I think the reasoning is clear.

 Actually, I would go so far and suggest that parsers MAY reject documents
 that they can't verify are symmetric and transitive, so I could see using
 lower case for strongly, but I think this is "RECOMMENDED" in the sense
 that it's something you should think twice before doing it differently.

 For now, have changed STRONGLY --> strongly

 The main reason it's not a MUST is that we don't want to burden parsers to
 actually have to verify this. However, for those parsers that do check for
 symmetry and transitivity, we could formally allow them to reject poorly
 specified contexts on variants). This would be a change not in the wording
 but the content of the spec.
 > word freely.  I'd stick to "character class" for the reasons given.

 We are not avoiding the term "set" as much as "character set". I just went
 through section 4 searching for "set" and the most common mention is in
 the context "set combination", referring to the mathematical operations on
 sets. I see no issue with those.

 In 4.3.5 the bullets uses set twice by itself and I've chanted that to
 class.
 > it recommended?  What bad thing happens if not?

 If simple / standard LGRs all define custom dispositions it becomes
 difficult to compare them. Yet some non-simple/non-standard ones cannot be
 restricted a-prirori (not without loss of desirable generality).

 I believe the "think twice" rule applies here, but it's aimed at a higher
 level of interoperability than just whether a parser can successfully
 parse the LGR on its own.

 >  In the description of
 fixe.

  specification          |  Resolution:
 Keywords:               |

Ticket URL: <https://trac.tools.ietf.org/wg/lager/trac/ticket/36#comment:1>
lager <https://tools.ietf.org/lager/>