Subject: RFC 4836 - (minor) textual flaws

From: Alfred Hönes <[email-masked]>
Date: Wed, 16 May 2007 14:09:52 +0200 (MESZ)

Hello,
after studying the recently published RFC 4836 (revised MAU MIB)
authored/edited by you, I would like to submit a few comments,
pointing out some minor textual flaws I found in the RFC text.

Some of these are legacy flaws (I had decided not to report
previously) or instances of recurring editorial issues, but
some have been newly introduced.

The intent of this note is to make you aware of the issues,
and to possibly address these in future related / derived work.
Although published policy would perhaps admit the publication
of an RFC Errata Note, IMHO that is not necessary in this case.

The items below are presented in (almost) RFC textual order.
I use change bars ('|' in column 1) and occasionally
up/down pointing marker lines ('^^^'/'vvv') to emphasize
the location of textual issues and/or proposed corrections.
Modified text has been re-adjusted to match RFC formatting
rules, where necessary.

(1)  Section 3 -- 'rational' quotation -- [legacy]

At the end of the first paragraph of Section 3, on page 4 of RFC 4836,

|  "interface MAUs."
                  ^^
should be written as:

|  "interface MAUs".
                  ^^

Rationale: AFAICS, This is the only place left in the RFC violating
  RFC-Ed policy on 'rational' quotation.

(2)  Section 3.1 -- typos -- [new]

The third paragraph of Section 3.1 says:

|  In addition, the new definitions are added to the IANA-maintained MIB
|  module, to support Ethernet in the First Mile (EFM) and 10GBASE-CX4
   interfaces, defined in [...]

It should say:

|  In addition, new definitions are added to the IANA-maintained MIB
|  module to support Ethernet in the First Mile (EFM) and 10GBASE-CX4
   interfaces, defined in [...]

Rationale:
a) '*the* new definitions' seems to be inappropriate because these
   new definitions have not been introduced so far in the text;
b) the comma separates the subject and the verb in the sentence,
   which better should be avoided.

(3)  Section 3.2.1 -- typo / text formatting -- [new]

In the second paragraph of Section 3.2.1, in the 5th line from the
bottom of page 5,  "non- 10GBASE-W type"  should be spelled
"non-10GBASE-W type".

Note to the RFC-Ed:
  Aparently, this is a recurring text-reformatting problem
  which I have observed multiple times in various recent RFCs.
  According to my experience, matches to the regular expression
    /[a-z0-9]- [a-z0-9]/  (in case-ignoring mode)
  will help find similar problems -- unfortunately, there are
  perfectly feasible matches as well, but finding the candidate
  flaws as always is the first step required.  Maybe, something
  like that search can be added to your nits-checking toolkit.

(4)  Section 3.4 -- table formatting -- [new]

In the tables on pages 7 / 8, the structure of the IEEE Managed
Object names has been hidden even more by the added separator
lines.  E.g., in Table 1, on top of page 7, the table formatting
IMHO hides the fact that  "oMAU"  is the prefix to all subsequent
(partial) object names, and neaer the bottom of page 7, the
'group change' to the next prefix "oAutoNegotiation" is not
obvious any more.
Perhaps this is an artifact of new tools used.
The most simple suggestion for improving the visible grouping in
such tables that comes to my mind is to use modified separator lines
for grouping, and omit the column separator in group headlines, e.g.,

- on top of page 7, modify:

   +----------------------------------+--------------------------------+
   | IEEE 802.3 Managed Object        | Corresponding SNMP Object      |
   +----------------------------------+--------------------------------+
   | oMAU                             |                                |
   +----------------------------------+--------------------------------+
   | .aMAUID                          | rpMauIndex or ifMauIndex or    |
   |                                  | broadMauIndex                  |
   +----------------------------------+--------------------------------+
   | ....                             | ...                            |

to:

   +----------------------------------+--------------------------------+
   | IEEE 802.3 Managed Object        | Corresponding SNMP Object      |
   +==================================+================================+
   | oMAU                                                              |
   +----------------------------------+--------------------------------+
   | .aMAUID                          | rpMauIndex or ifMauIndex or    |
   |                                  | broadMauIndex                  |
   +----------------------------------+--------------------------------+
   | ....                             | ...                            |

- and near the bottom of page 7, change:

   | ...                              | ...                            |
   +----------------------------------+--------------------------------+
   | .nJabber                         | rpMauJabberTrap or             |
   |                                  | ifMauJabberTrap                |
   +----------------------------------+--------------------------------+
   | oAutoNegotiation                 |                                |
   +----------------------------------+--------------------------------+
   | .aAutoNegID                      | ifMauIndex                     |
   +----------------------------------+--------------------------------+
   | ...                              | ...                            |

to:

   | ...                              | ...                            |
   +----------------------------------+--------------------------------+
   | .nJabber                         | rpMauJabberTrap or             |
   |                                  | ifMauJabberTrap                |
   +==================================+================================+
   | oAutoNegotiation                                                  |
   +----------------------------------+--------------------------------+
   | .aAutoNegID                      | ifMauIndex                     |
   +----------------------------------+--------------------------------+
   | ...                              | ...                            |

An additional artifact has subtly changed the apparent semantics
in table 2, on page 8.  The 'Reason for exclusion' given for
oAutoNegotiation.aAutoNegLocalSelectorAbility in fact applies
to all three objetcs in the oAutoNegotiation group.  The published
form of the table does not properly represent this fact.  In HTML,
the corresponding cell could be given a vertical span of three rows.
Incorporating the modification for better grouping support proposed
above, the Table 2,

   +------------------------------------+------------------------------+
   | IEEE 802.3 Managed Object          | Reason for exclusion         |
   +------------------------------------+------------------------------+
   | oMAU                               |                              |
   +------------------------------------+------------------------------+
   | .aIdleErrorCount                   | Only useful for 100BaseT2,   |
   |                                    | which is not widely          |
   |                                    | implemented.                 |
   +------------------------------------+------------------------------+
   | oAutoNegotiation                   |                              |
   +------------------------------------+------------------------------+
   | .aAutoNegLocalSelectorAbility      | Only needed for support of   |
   |                                    | isoethernet (802.9a), which  |
   |                                    | is not supported by MAU-MIB. |
   +------------------------------------+------------------------------+
   | .aAutoNegAdvertisedSelectorAbility |                              |
   +------------------------------------+------------------------------+
   | .aAutoNegReceivedSelectorAbility   |                              |
   +------------------------------------+------------------------------+

should perhaps better be presented as:

   +------------------------------------+------------------------------+
   | IEEE 802.3 Managed Object          | Reason for exclusion         |
   +====================================+==============================+
   | oMAU                                                              |
   +------------------------------------+------------------------------+
   | .aIdleErrorCount                   | Only useful for 100BaseT2,   |
   |                                    | which is not widely          |
   |                                    | implemented.                 |
   +====================================+==============================+
   | oAutoNegotiation                                                  |
   +------------------------------------+------------------------------+
   | .aAutoNegLocalSelectorAbility      | Only needed for support of   |
   +------------------------------------+ isoethernet (802.9a), which  |
   | .aAutoNegAdvertisedSelectorAbility | is not supported by the MAU- |
   +------------------------------------+ MIB.                         |
   | .aAutoNegReceivedSelectorAbility   |                              |
   +------------------------------------+------------------------------+

Note: I have also added the missing article in front of "MAU-MIB".

(5)  Section 4 (MAU-MIB Module)

(5a)  rpMauMediaAvailable -- missing article -- [new]

The DESCRIPTION clause in the rpMauMediaAvailable OBJECT-TYPE macro
invocation, at the bottom of page 16, says:
                                             v
|         DESCRIPTION "This object identifies Media Available state of
                      the MAU, complementary to the rpMauStatus.  [...]

It should say:
                                             vvvvv
|         DESCRIPTION "This object identifies the Media Available state
                      of the MAU, complementary to the rpMauStatus.
                      [...]

(5b)  ifMauMediaAvailable -- missing article -- [new]

Similarly to the preceding item, the DESCRIPTION clause in the
ifMauMediaAvailable OBJECT-TYPE declaration, on top of page 23, says:
                                             v
|         DESCRIPTION "This object identifies Media Available state of
                      the MAU, complementary to the ifMauStatus.  [...]

It should say:
                                             vvvvv
|         DESCRIPTION "This object identifies the Media Available state
                      of the MAU, complementary to the ifMauStatus.
                      [...]

(5c)  ifMauTypeListBits              (page 27
(5d)  ifMauAutoNegCapabilityBits     (page 33)
(5e)  ifMauAutoNegCapAdvertisedBits  (page 34)
(5f)  ifMauAutoNegCapReceivedBits    (page 34)

For completeness and uniformity, it would be useful to amend the
textual references to the bOther bit value in the DESCRIPTION clauses
of these OBJECT-TYPE declarations by adding the numerical value in
parentheses, as it has been done in all similar places in the text:

Change   "bOther"   -->   "bOther(0)" .

(5g)  ifMauAutoNegCapability -- tabular formatting -- [legacy]

The latest additions to the table in the DESCRIPTION clause of the
deprecated ifMauAutoNegCapability OBJECT-TYPE declaration have not
been aligned properly.
Near the top of page 32, the RFC says:

                       [...]
                       17       (reserved)
                       18       (reserved)
|                      19      100BASE-T2 half duplex mode
|                      20      100BASE-T2 full duplex mode
                               ^^
It should say:

                       [...]
                       17       (reserved)
                       18       (reserved)
|                      19       100BASE-T2 half duplex mode
|                      20       100BASE-T2 full duplex mode
                               ^^

(5h)  mauIfGrp100Mbs -- spurious blank line -- [legacy/repagination]

Perhaps as an artifact of the text reformatting (new pagination),
there now is a spurious blank line in the mauIfGrp100Mbs OBJECT-GROUP
macro invocation, on top of page 40.
The RFC says:

                      }
|
          STATUS      deprecated

It should say:

                      }
          STATUS      deprecated

Note to the RFC-Ed:
  This is a recurring artifact observed repeatedly in MIB modules,
  but also in other places; where older editions of the text
  (previous RFC or I-D) had a page break and this is removed
  in the RFC, sometimes such spurious blank line(s) remain.

(5i)  mauModRpCompl2 -- spurious blank line -- [legacy/repagination]

Similarly as above, the mauModRpCompl2 MODULE-COMPLIANCE macro
invocation contains a spurious blank line, after the 8th non-blank
text line on page 45.
The RFC says:

              GROUP       rpMauNotifications
|
              DESCRIPTION "Implementation of this group is recommended
                          for MAUs attached to repeater ports."

It should say:

              GROUP       rpMauNotifications
              DESCRIPTION "Implementation of this group is recommended
                          for MAUs attached to repeater ports."

(5j)  mauModIfCompl3 -- lost blank line -- [legacy/repagination]

In contrast to the two preceding items, in the mauModIfCompl3
MODULE-COMPLIANCE macro invocation, a separating blank line
has been lost.
At the top of page 46, the RFC says:

              GROUP       mauIfGrpAutoNeg2
              DESCRIPTION "Implementation of this group is mandatory
                          for MAUs that support managed
                          auto-negotiation."
              GROUP       mauIfGrpAutoNeg1000Mbps
              DESCRIPTION "Implementation of this group is mandatory
                          [...]

It should say:

              GROUP       mauIfGrpAutoNeg2
              DESCRIPTION "Implementation of this group is mandatory
                          for MAUs that support managed
                          auto-negotiation."
|
              GROUP       mauIfGrpAutoNeg1000Mbps
              DESCRIPTION "Implementation of this group is mandatory
                          [...]

(6)  Section 5 (IANA-MAU-MIB Module)

(6a)  IANAifMauTypeListBits TC -- formatting -- [legacy++]

The SYNTAX clause of the IANAifMauTypeListBits TEXTUAL-CONVENTION,
on page 48 of RFC 4836, contains three blank lines.
I suspect that these initially were intended to visually group
the lines according to the speed classes; but this was never
handled correctly; e.g., in :

       SYNTAX       BITS {
              bOther(0),          -- other or unknown
              bAUI(1),            -- AUI
              b10base5(2),        -- 10BASE-5
              bFoirl(3),          -- FOIRL
|
              b10base2(4),        -- 10BASE-2

a break would perhaps have been appropiate below bOther(0), not
below bFoirl(3), thus not disrupting the group of 10 Mbps MAU types,
i.e.:

       SYNTAX       BITS {
              bOther(0),          -- other or unknown
|
              bAUI(1),            -- AUI
              b10base5(2),        -- 10BASE-5
              bFoirl(3),          -- FOIRL
              b10base2(4),        -- 10BASE-2

In RFC 3636, there was a page break between the 10 Mbps MAU types
and the 100 Mbps MAU types; in RFC 4836, there's no separating blank
line there.
The addition of the new MAU types (on page 49) finally has made
this grouping scheme impossible/obsolete.

I therefore recommend to remove these embedded separating blank lines
from the IANA-MAU-MIB module at the next update, under the control of
the designated expert.

(6b)  IANAifMauMediaAvailable -- typo -- [new]

Within the DESCRIPTION clause of the IANAifMauMediaAvailable TC,
in the first line of the last paragraph on page 51, a comma has
been dropped.
For consistency of style and grammar, I recommend to change back
in the IANA-MAU-MIB module (at the next update) the line,

         For 10 Gb/s the enumerations map to value of the link_fault

to say:

         For 10 Gb/s, the enumerations map to value of the link_fault

(6c)  OBJECT IDENTITIES for MAU types -- visual enhancement

For enhanced readability, I also recommend to insert additional blank
lines below the ASN.1 comments, "-----  new since ..." in the section
listing the OBJECT IDENTITIES for MAU types.

This could be done at the next regular update of the IANA-MAU-MIB
module, at the places corresponding to page 56, 57, 59, and 60 in
RFC 4836, respectively; e.g. (on page 56), change

     ------ new since RFC 1515:
     dot3MauType10BaseTHD OBJECT-IDENTITY
        STATUS     current
        [...]
to:

     ------ new since RFC 1515:
|
     dot3MauType10BaseTHD OBJECT-IDENTITY
        STATUS     current
        [...]

(7)  Section 7 -- missing article -- [new]

The first paragraph of Section 7, on page 63, says:

                        v
|  This document defines first version of the IANA-maintained IANA-MAU-
   MIB module.  [...]

It should say:
                        vvvvv
|  This document defines the first version of the IANA-maintained IANA-
   MAU-MIB module.  [...]

If you anyway consider adressing some of the above issues by an RFC
Errata Note, please make freely use of the material supplied above.

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