RE: FW: issues with RFC 4319

I can support to create an errata-note to RFC-Editor.
RFC-Editor will then keep it linked to the RFC, so current
readers can see then notes. Also in future, editors of
a possib;e revision of the RFC can then find the notes and 
make the changes.

I am OK will all suggested notes except:

- issue (3) 
  the part that suggests to change "This version" into
  "Revised version" seems a style matter, and I believe we
  have many such "This version" samples in other RFCs.
- issue (7) might be nice, but I would rather make a not
  to ourselves to consider this in a future version (if any)
  In any event, without exact proposed text we can't submit it.
- issue (10) also needs exact proposed text first before we 
  can act on it.

Thanks to Alfred.

Let me also encourage Alfred to try and read IETF Last Called
documents and try to submit his review at that time (or 
earlier if possible). That way we can fix it BEFORE the doc
actually becomes an RFC.

Bert

> -----Original Message-----
> From: Clay Sikes [mailto:[email protected]]
> Sent: Saturday, January 21, 2006 18:37
> To: IETF ADSL MIB Working Group; Michael Sneed; Bob Ray; 
> Menachem Dodge;
> Bert Wijnen; Randy Presuhn; Alfred HÎnes; IETF ADSL MIB Working Group
> Subject: Re: FW: issues with RFC 4319
> 
> 
> Hi,
> 
> Alfred HÎnes has discovered some issues in RFC 4319.  The 
> issues are included below and I made some in-line comments. 
> IMHO, although Alfred has found real problems in the RFC and 
> many of these problems exist in the obsoleted RFC 3276 as 
> well, I don't see the problems as being significant enough to 
> require an Errata Note because I don't see any of them as 
> causing a hard outage in implementation. I'm not sure what 
> drives an Errata Note, but it would seem that it would be 
> driven by an error that causes an implementation issue and 
> not just a usability or readability improvement. 
> 
> My purpose of sending this to the ADSL MIB Working Group List is:
> 
> Capture the issues in case something happens such as a 
> technology change that requires this RFC to be obsoleted.  If 
> that occurs, a clean-up effort should be undertaken based on 
> these issues.
> 
> Ask the list if the issues raised by Alfred require an Errata 
> Note.  If a note is required, I will move forward on that work.
> 
> Finally, I would like to extend a thanks to Alfred HÎnes for 
> his time in the generation of the issues.  I would like to 
> strongly encourage Alfred to subscribe to the ADSL MIB List 
> at https://www1.ietf.org/mailman/listinfo/adslmib and utilize 
> his awesome review talent in providing review of the ADSL2 
> MIB work that is under way and the up-and-coming VDSL2 MIB 
> work.  As an editor of an RFC, I know that the more that 
> review an ID, the better the quality of the RFC.
> 
> Best Regards,
> Clay Sikes 
> 
> 
> 
> 
>  
> 
> -----Original Message-----
> From: Alfred HÎnes [mailto:[email protected]] 
> Sent: Wednesday, January 18, 2006 4:32 PM
> To: [email protected]; Ray, Robert; [email protected]
> Cc: [email protected]
> Subject: issues with RFC 4319
> 
> Hello,
> after studying the recently published RFC 4319 authored by 
> you I'd like to report the textual issues I found in that memo.
> 
> I use change bars '|' in column 1 and '^^^' / 'vvv' style 
> tags on extar lines to emphasize the location of the textual 
> issues and/or the proposed corrections.
> If necessary, I also have adjusted the line folding of 
> proposed text to keep it conformant with RFC formatting rules.
> 
> 
> (1)
> 
> Apparently, Figure 2 on page 10 has not been adapted from RFC 
> 3276 to remain aligned with the extensions covered by RFC 4319.
> To keep the changes minimal, I propose to just amend the 
> Figure caption, replacing:
> 
>        Key:  <////> HDSL2/SHDSL span
>              <~~~~> HDSL2/SHDSL segment
>              =1=    HDSL2/SHDSL wire-pair-1
>              =2=    SHDSL optional wire-pair-2 (Not 
> applicable to HDSL2)
>              C      Customer side segment endpoint (modem)
>              N      Network side segment endpoint (modem)
> 
> by:
> 
>        Key:  <////> HDSL2/SHDSL span
>              <~~~~> HDSL2/SHDSL segment
>              =1=    HDSL2/SHDSL wire-pair-1
> |            =2=    SHDSL optional wire-pair-2 (not 
> applicable to HDSL2)
> |                   and SHDSL.bis optional wire-pair-3 and wire-pair-4
> |                   (not applicable to HDSL2 and 'classic' SHDSL)
>              C      Customer side segment endpoint (modem)
>              N      Network side segment endpoint (modem)
>   
> I agree that this proposal in that it would nice to provide 
> clarification and it would have been nice to explicitly have 
> text referring to the existence of the additional wire-pairs 
> added with G.shdsl.bis.   I don't see that leaving it as in 
> its current state as causing any significant problems either.
> 
> 
> 
> (2)
> 
> Section 2.7, on page 11, contains a bulleted list with two entries.
> It turns out that the second (indented) paragraph of the 2nd 
> bullet in fact applies to both entries and hence should
>   -  not be indented so much, and
>   -  be adapted for plural grammar.
> Thus, the paragraph saying:
>                             vvv      vv
>       The index value for this profile is a locally-unique
>       administratively-assigned name for the profile having 
> the textual
>       convention 'SnmpAdminString' (RFC 3411 [RFC3411]).
> 
> should be modified to say:
>                          vvv       vv
> |  The index value for these profiles is a locally-unique  
> | administratively-assigned name for the profile having the textual  
> | convention 'SnmpAdminString' (RFC 3411 [RFC3411]).
> 
>   
> I agree that the proposed change would be an improvement.  I 
> don't see that leaving it as in its current state as causing 
> any significant problems either.
> 
> 
> (3)
> 
> The REVISION / DESCRIPTION clause pairs in MODULE-IDENTITY 
> macro invocations preferrably should be formulated in an 
> 'update-friendly'
> manner, i.e. such that the text does not need to be modified 
> when another revision of the MIB module is published in the future.
> 
> Therefore, I propose to change the DESCRIPTION clause for the 
> RFC 4319 revision of the HDSL2-SHDSL-LINE-MIB, at the bottom 
> of page 15 to follow this requirement.
> The text there contains improper wording as well, the 
> correction of which justifies a combined Erratum entry.
> Hence, the lines:
> 
>    REVISION    "200512070000Z" -- December 7, 2005
>    DESCRIPTION "This version, published as RFC 4319.
>          The following changes have been made in this version:
>            1.  Added a 3rd and 4th wire pair.
>            2.  Modified all rates such that their rates are only
>                constrained by an unsigned 32-bit value and not by
>                what today's perceived technology limitations are.
> 
> should be changed to say:
> 
>    REVISION    "200512070000Z" -- December 7, 2005
> |  DESCRIPTION "Revised version, published as RFC 4319.
>          The following changes have been made in this version:
>            1.  Added a 3rd and 4th wire pair.
> |          2.  Modified all rates such that they are only
>                constrained by an unsigned 32-bit value and not by
>                what today's perceived technology limitations are.
> 
>   
> I don't feel that this change should be applied unless this 
> RFC was obsoleted by another RFC and that the "This" verses 
> "Revised" words are approved by Charter Advisors.  I don't 
> think this change should be an Errata Note.
> 
> (4)
> 
> On page 16 (lower half), the 2nd paragraph of the DESCRIPTION 
> clause of the Hdsl2ShdslPerfCurrDayCount TEXTUAL-CONVENTION 
> contains a mis- spelled syntax name (of another TEXTUAL-CONVENTION).
> 
> The sentence,
> 
>                                 [ ... ]  At that time, the 
> value of the
>          gauge is stored in the previous 1-day history interval, as
>          defined in a companion object of type
>          Hdsl2Shdsl1DayIntevalCount, and the current interval gauge
>          is restarted at zero.
> 
> should say:
> 
>                                 [ ... ]  At that time, the 
> value of the
>          gauge is stored in the previous 1-day history interval, as
>          defined in a companion object of type
> |        Hdsl2Shdsl1DayIntervalCount, and the current interval gauge
>          is restarted at zero.
>                            ^
> 
>   
> This spelling error, the missing "r", exists in RFC 3276 as well.
> 
> 
> (5)
> 
> On page 17 (lower half), the DESCRIPTION clause of the 
> Hdsl2ShdslPerfIntervalThreshold TEXTUAL-CONVENTION suffers 
> from the lack of a verb in its 2nd sentence.
> The paragraph,
> 
>         "This convention defines a range of values that may be set in
>          a fault threshold alarm control.  As the number of seconds in
>          a 15-minute interval numbers at most 900, objects of 
> this type
>          may have a range of 0...900, where the value of 0 
> disables the
>          alarm."
> 
> should say:
> 
>         "This convention defines a range of values that may be set in
>          a fault threshold alarm control.  As the number of seconds in
> |        a 15-minute interval numbers is at most 900, objects of this
>          type may have a range of 0...900, where the value of 
> 0 disables
>          the alarm."
> 
>   
> It seems like the addition of "is" is needed.  Note that "is" 
> is missing in RFC 3278 as well.
> 
> 
> (6)
> 
> On page 18, there is a word omission in the DESCRIPTION 
> clause of the Hdsl2ShdslWirePair TEXTUAL-CONVENTION.
> The paragraph,
> 
>         "This is the referenced pair of wires in an 
> HDSL2/SHDSL segment.
>          HDSL2 only supports a single pair (wirePair1 or two wire),
>          SHDSL lines support an optional second pair 
> (wirePair2 or four
>          wire), and G.shdsl.bis support an optional third pair
>          (wirePair3 or six wire) and an optional fourth pair
>          (wirePair4 or eight wire)."
> 
> should say:
> 
>         "This is the referenced pair of wires in an 
> HDSL2/SHDSL segment.
>          HDSL2 only supports a single pair (wirePair1 or two wire),
>          SHDSL lines support an optional second pair 
> (wirePair2 or four
> |        wire), and G.shdsl.bis lines support an optional third pair
>          (wirePair3 or six wire) and an optional fourth pair
>          (wirePair4 or eight wire)."
> 
>   
> The addition of the word "lines" improves the readability of 
> the sentence. This issue doesn't exist in RFC 3276; it is a 
> result of an addition I made to support G.shdsl.bis.
> 
> 
> (7)
> 
> On pages 45..49 it would be very useful to have REFERENCE 
> clauses added to the OBJECT-TYPE declarations for the 
> technology specific objects in the Span Configuration Profile 
> Table (similarly to what has been done for the OBJECT-TYPE 
> declarations for the objects in the Unit Inventory Group, on 
> pp. 24..27).
> 
>   
> This would be nice. However, it would take some research to 
> figure out which objects apply to which technology. The issue 
> applies to RFC 3276 as well.
> 
> 
> (8)
> 
> The DESCRIPTION clause of the hdsl2ShdslSpanConfMinLineRate 
> OBJECT- TYPE declaration contains a reference to a truncated 
> object name.
> 
> That clause says:
> 
>         "This object configures the minimum transmission rate for
>          the associated SHDSL Line in bits-per-second (bps) 
> and includes
>          both payload (user data) and any applicable framing overhead.
>          If the minimum line rate equals the maximum line rate
>          (hdsl2ShdslSpanMaxLineRate), the line rate is considered
>          'fixed'.  If the minimum line rate is less than the
>          maximum line rate, the line rate is considered
>          'rate-adaptive'."
> 
> It should say:
> 
>         "This object configures the minimum transmission rate for
>          the associated SHDSL Line in bits-per-second (bps) 
> and includes
>          both payload (user data) and any applicable framing overhead.
>          If the minimum line rate equals the maximum line rate
> |        (hdsl2ShdslSpanConfMaxLineRate), the line rate is considered
>          'fixed'.  If the minimum line rate is less than the
>          maximum line rate, the line rate is considered
>          'rate-adaptive'."
> 
>   
> The object misspelled in that it is missing the "Conf" part 
> for its name. This issue applies to 
> hdsl2ShdslSpanConfMaxLineRate as well. RFC 3276 has this 
> anomaly as well.
> 
> 
> (9)
> 
> The DESCRIPTION clauses of OBJECT-TYPE declarations 
> preferrably should be 'self-centric', i.e. describe context 
> as seen from the respective object. Therefore, text 
> replications from one object to another object without proper 
> adaptation are sub-optimal, at best.
> In particular, referencing an object within its DESCRIPTION 
> clause by name, while omitting to call another object 
> (referenced there) by its name does not add much to the 
> clarity of the DESCRIPTION.
> 
> Therefore, I propose to slightly modify the DESCRIPTION 
> clause of the hdsl2ShdslSpanConfMaxLineRate OBJECT-TYPE 
> declaration, on top of page 46.  This clause is affected by 
> issue (7) as well.
> 
> The clause says:
> 
>         "This object configures the maximum transmission rate for
>          the associated SHDSL Line in bits-per-second (bps) 
> and includes
>          both payload (user data) and any applicable framing overhead.
>          If the minimum line rate equals the maximum line rate
>          (hdsl2ShdslSpanMaxLineRate), the line rate is considered
>          'fixed'.  If the minimum line rate is less than the
>          maximum line rate, the line rate is considered
>          'rate-adaptive'."
> 
> It better should say:
> 
>         "This object configures the maximum transmission rate for
>          the associated SHDSL Line in bits-per-second (bps) 
> and includes
>          both payload (user data) and any applicable framing overhead.
> |        If the minimum line rate 
> (hdsl2ShdslSpanConfMinLineRate) equals
> |        the maximum line rate the line rate is considered 'fixed'.
>          If the minimum line rate is less than the maximum line rate,
>          the line rate is considered 'rate-adaptive'."
> 
>   
> This issue applies to hdsl2ShdslSpanConfMinLineRate as well.  
> The wording exist in RFC 3276.
> 
> 
> (10)
> 
> On pages 47/48, the DESCRIPTION clauses for the four objects:
>     hdsl2ShdslSpanConfCurrCondTargetMarginDown,
>     hdsl2ShdslSpanConfWorstCaseTargetMarginDown,
>     hdsl2ShdslSpanConfCurrCondTargetMarginUp,  and
>     hdsl2ShdslSpanConfWorstCaseTargetMarginUp
> contain mainly identical text.  This emphasizes the 
> similarities between these objects but leaves the reader 
> alone as to the use and differing purpose of the objects.  It 
> would be very desirable to have additional expanatory text 
> added to these four descriptions to clarify the intended use 
> (e.g., as an alarm limit).
> 
>   
> This issue exists in  RFC 3276.
> 
> 
> 
> IMHO, most of these issues are worth of being considered for 
> inclusion in an Errata Note to be posted on the RFC Editor's 
> web site.  Of cause, things like item (9) might as well just 
> be noted for consideration at the time of the next update (if 
> any ...).
> 
> Please comment, and either deliberately make use of the above 
> material to directly submit such Errata Note, or give me 
> direction as to what would obtain your (the author's) consent 
> if formally submitted by me.
> 
> Best regards,
>   Alfred HÎnes.
> 
>   
>