RE: [Hubmib] RE: RFC 4836

Alfred, thanks for reporting your findings.
As Edward already suggested, I think it is best to
just file these comments so we can pick them up if
we ever do another revision in the future.

Bert Wijnen
Chair of the IETF HUBMIB WG

> -----Original Message-----
> From: Edward Beili [mailto:EdwardB@actelis.com] 
> Sent: Tuesday, May 22, 2007 9:12 AM
> To: Alfred H?nes
> Cc: dromasca@avaya.com; hubmib@ietf.org; Wijnen, Bert (Bert); 
> rfc-editor@rfc-editor.org
> Subject: [Hubmib] RE: RFC 4836 - (minor) textual flaws
> 
>  
> Alfred,
> 
> Thank you for the comments. I agree with all of them, however 
> I don't feel they warrant an RFC errata.
> I'm forwarding your email to the HUBMIB mailing list for 
> archiving purposes, so if RFC 4836 is updated your comments 
> would be implemented.
> 
> A note on the table formatting - I used xml2rfc tool 
> (http://xml.resource.org/) to convert the XML source into TXT 
> and HTML formats. Unfortunately current XML format (defined 
> in RFC 2629 and its unofficial successor) provides only very 
> basic attributes controlling tables appearance - there's no 
> way to specify COLSPAN or ROWSPAN, border thickness or text 
> alignment within a cell. That is why the tables look like 
> that - I wanted the final draft to be produced directly from 
> the XML file, without additional post-processing. My repeated 
> requests to the xml2rfc team for the support of table 
> formatting attributes have so far been unanswered (I urge the 
> other authors on the list using xml2rfc to submit a feature 
> request to the xml2rfc mailing list).
> 
> Regards,
> -E.
> 
> 
> > -----Original Message-----
> > From: Alfred H־nes [mailto:ah@tr-sys.de]
> > Sent: Wednesday, May 16, 2007 15:10
> > To: Edward Beili; rfc-editor@rfc-editor.org
> > Subject: RFC 4836 - (minor) textual flaws
> > 
> > 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:  ah@TR-Sys.de             
> >         |
> > +------------------------+------------------------------------
> > --------+
> > 
> 
> _______________________________________________
> Hubmib mailing list
> Hubmib@ietf.org
> https://www1.ietf.org/mailman/listinfo/hubmib
> 

_______________________________________________
Hubmib mailing list
Hubmib@ietf.org
https://www1.ietf.org/mailman/listinfo/hubmib

RE: [Hubmib] RE: RFC 4836 - (minor) textual flaws