Subject: issues with RFC 4319

From: Alfred Hönes <[email-masked]>
Date: Wed, 18 Jan 2006 23:32:19 +0100 (MEZ)

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)

(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]).

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

(3)

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

(4)

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

(5)

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

(6)

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

(7)

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

(8)

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

(9)

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

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.

-- 

+------------------------+--------------------------------------------+
| TR-Sys Alfred Hoenes   |  Alfred Hoenes   Dipl.-Math., Dipl.-Phys.  |
| Gerlinger Strasse 12   |  Phone: (+49)7156/9635-0, Fax: -18         |
| D-71254  Ditzingen     |  E-Mail:  [email-masked]                     |
+------------------------+--------------------------------------------+