RE: RFC 4836 - (minor) textual flaws
"Edward Beili" <[email protected]> Tue, 22 May 2007 10:11:59 +0300
| Newsgroups | gmane.ietf.hubmib |
|---|---|
| Message-ID | <[email protected]> |
=20 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=CEnes [mailto:[email protected]]=20 > Sent: Wednesday, May 16, 2007 15:10 > To: Edward Beili; [email protected] > Subject: RFC 4836 - (minor) textual flaws >=20 > Hello, > after studying the recently published RFC 4836 (revised MAU=20 > MIB) authored/edited by you, I would like to submit a few=20 > comments, pointing out some minor textual flaws I found in=20 > the RFC text. >=20 > Some of these are legacy flaws (I had decided not to report > previously) or instances of recurring editorial issues, but=20 > some have been newly introduced. >=20 > The intent of this note is to make you aware of the issues,=20 > and to possibly address these in future related / derived work. > Although published policy would perhaps admit the publication=20 > of an RFC Errata Note, IMHO that is not necessary in this case. >=20 > The items below are presented in (almost) RFC textual order. > I use change bars ('|' in column 1) and occasionally up/down=20 > pointing marker lines ('^^^'/'vvv') to emphasize the location=20 > of textual issues and/or proposed corrections. > Modified text has been re-adjusted to match RFC formatting=20 > rules, where necessary. >=20 >=20 > (1) Section 3 -- 'rational' quotation -- [legacy] >=20 > At the end of the first paragraph of Section 3, on page 4 of RFC 4836, >=20 > | "interface MAUs." > ^^ > should be written as: >=20 > | "interface MAUs". > ^^ >=20 > Rationale: AFAICS, This is the only place left in the RFC violating > RFC-Ed policy on 'rational' quotation. >=20 >=20 > (2) Section 3.1 -- typos -- [new] >=20 > The third paragraph of Section 3.1 says: >=20 > | In addition, the new definitions are added to the=20 > IANA-maintained MIB =20 > | module, to support Ethernet in the First Mile (EFM) and 10GBASE-CX4 > interfaces, defined in [...] >=20 > It should say: >=20 > | In addition, new definitions are added to the IANA-maintained MIB =20 > | module to support Ethernet in the First Mile (EFM) and 10GBASE-CX4 > interfaces, defined in [...] >=20 > 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. >=20 >=20 > (3) Section 3.2.1 -- typo / text formatting -- [new] >=20 > In the second paragraph of Section 3.2.1, in the 5th line=20 > from the bottom of page 5, "non- 10GBASE-W type" should be=20 > spelled "non-10GBASE-W type". >=20 > 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. >=20 > (4) Section 3.4 -- table formatting -- [new] >=20 > In the tables on pages 7 / 8, the structure of the IEEE=20 > Managed Object names has been hidden even more by the added=20 > separator lines. E.g., in Table 1, on top of page 7, the=20 > table formatting IMHO hides the fact that "oMAU" is the=20 > prefix to all subsequent > (partial) object names, and neaer the bottom of page 7, the=20 > 'group change' to the next prefix "oAutoNegotiation" is not=20 > obvious any more. > Perhaps this is an artifact of new tools used. > The most simple suggestion for improving the visible grouping=20 > in such tables that comes to my mind is to use modified=20 > separator lines for grouping, and omit the column separator=20 > in group headlines, e.g., >=20 > - on top of page 7, modify: >=20 > =20 > +----------------------------------+--------------------------------+ > | IEEE 802.3 Managed Object | Corresponding SNMP=20 > Object | > =20 > +----------------------------------+--------------------------------+ > | oMAU | =20 > | > =20 > +----------------------------------+--------------------------------+ > | .aMAUID | rpMauIndex or=20 > ifMauIndex or | > | | broadMauIndex =20 > | > =20 > +----------------------------------+--------------------------------+ > | .... | ... =20 > | >=20 > to: >=20 > =20 > +----------------------------------+--------------------------------+ > | IEEE 802.3 Managed Object | Corresponding SNMP=20 > Object | > =20 > = +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+ > | oMAU =20 > | > =20 > +----------------------------------+--------------------------------+ > | .aMAUID | rpMauIndex or=20 > ifMauIndex or | > | | broadMauIndex =20 > | > =20 > +----------------------------------+--------------------------------+ > | .... | ... =20 > | >=20 > - and near the bottom of page 7, change: >=20 > | ... | ... =20 > | > =20 > +----------------------------------+--------------------------------+ > | .nJabber | rpMauJabberTrap or =20 > | > | | ifMauJabberTrap =20 > | > =20 > +----------------------------------+--------------------------------+ > | oAutoNegotiation | =20 > | > =20 > +----------------------------------+--------------------------------+ > | .aAutoNegID | ifMauIndex =20 > | > =20 > +----------------------------------+--------------------------------+ > | ... | ... =20 > | >=20 > to: >=20 > | ... | ... =20 > | > =20 > +----------------------------------+--------------------------------+ > | .nJabber | rpMauJabberTrap or =20 > | > | | ifMauJabberTrap =20 > | > =20 > = +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+ > | oAutoNegotiation =20 > | > =20 > +----------------------------------+--------------------------------+ > | .aAutoNegID | ifMauIndex =20 > | > =20 > +----------------------------------+--------------------------------+ > | ... | ... =20 > | >=20 >=20 > An additional artifact has subtly changed the apparent=20 > semantics in table 2, on page 8. The 'Reason for exclusion'=20 > given for oAutoNegotiation.aAutoNegLocalSelectorAbility in=20 > fact applies to all three objetcs in the oAutoNegotiation=20 > group. The published form of the table does not properly=20 > represent this fact. In HTML, the corresponding cell could=20 > be given a vertical span of three rows. > Incorporating the modification for better grouping support=20 > proposed above, the Table 2, >=20 > =20 > +------------------------------------+------------------------------+ > | IEEE 802.3 Managed Object | Reason for=20 > exclusion | > =20 > +------------------------------------+------------------------------+ > | oMAU | =20 > | > =20 > +------------------------------------+------------------------------+ > | .aIdleErrorCount | Only useful for=20 > 100BaseT2, | > | | which is not widely=20 > | > | | implemented. =20 > | > =20 > +------------------------------------+------------------------------+ > | oAutoNegotiation | =20 > | > =20 > +------------------------------------+------------------------------+ > | .aAutoNegLocalSelectorAbility | Only needed for=20 > support of | > | | isoethernet=20 > (802.9a), which | > | | is not supported by=20 > MAU-MIB. | > =20 > +------------------------------------+------------------------------+ > | .aAutoNegAdvertisedSelectorAbility | =20 > | > =20 > +------------------------------------+------------------------------+ > | .aAutoNegReceivedSelectorAbility | =20 > | > =20 > +------------------------------------+------------------------------+ >=20 > should perhaps better be presented as: >=20 > =20 > +------------------------------------+------------------------------+ > | IEEE 802.3 Managed Object | Reason for=20 > exclusion | > =20 > = +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+ > | oMAU =20 > | > =20 > +------------------------------------+------------------------------+ > | .aIdleErrorCount | Only useful for=20 > 100BaseT2, | > | | which is not widely=20 > | > | | implemented. =20 > | > =20 > = +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+ > | oAutoNegotiation =20 > | > =20 > +------------------------------------+------------------------------+ > | .aAutoNegLocalSelectorAbility | Only needed for=20 > support of | > +------------------------------------+ isoethernet=20 > (802.9a), which | > | .aAutoNegAdvertisedSelectorAbility | is not supported by=20 > the MAU- | > +------------------------------------+ MIB. =20 > | > | .aAutoNegReceivedSelectorAbility | =20 > | > =20 > +------------------------------------+------------------------------+ >=20 > Note: I have also added the missing article in front of "MAU-MIB". >=20 >=20 > (5) Section 4 (MAU-MIB Module) >=20 > (5a) rpMauMediaAvailable -- missing article -- [new] >=20 > The DESCRIPTION clause in the rpMauMediaAvailable OBJECT-TYPE=20 > macro invocation, at the bottom of page 16, says: > v > | DESCRIPTION "This object identifies Media Available state of > the MAU, complementary to the=20 > rpMauStatus. [...] >=20 > It should say: > vvvvv > | DESCRIPTION "This object identifies the Media=20 > Available state > of the MAU, complementary to the rpMauStatus. > [...] >=20 > (5b) ifMauMediaAvailable -- missing article -- [new] >=20 > Similarly to the preceding item, the DESCRIPTION clause in=20 > the ifMauMediaAvailable OBJECT-TYPE declaration, on top of=20 > page 23, says: > v > | DESCRIPTION "This object identifies Media Available state of > the MAU, complementary to the=20 > ifMauStatus. [...] >=20 > It should say: > vvvvv > | DESCRIPTION "This object identifies the Media=20 > Available state > of the MAU, complementary to the ifMauStatus. > [...] >=20 > (5c) ifMauTypeListBits (page 27 > (5d) ifMauAutoNegCapabilityBits (page 33) > (5e) ifMauAutoNegCapAdvertisedBits (page 34) > (5f) ifMauAutoNegCapReceivedBits (page 34) >=20 > For completeness and uniformity, it would be useful to amend=20 > the textual references to the bOther bit value in the=20 > DESCRIPTION clauses of these OBJECT-TYPE declarations by=20 > adding the numerical value in parentheses, as it has been=20 > done in all similar places in the text: >=20 > Change "bOther" --> "bOther(0)" . >=20 > (5g) ifMauAutoNegCapability -- tabular formatting -- [legacy] >=20 > The latest additions to the table in the DESCRIPTION clause=20 > of the deprecated ifMauAutoNegCapability OBJECT-TYPE=20 > declaration have not been aligned properly. > Near the top of page 32, the RFC says: >=20 > [...] > 17 (reserved) > 18 (reserved) > | 19 100BASE-T2 half duplex mode > | 20 100BASE-T2 full duplex mode > ^^ > It should say: >=20 > [...] > 17 (reserved) > 18 (reserved) > | 19 100BASE-T2 half duplex mode > | 20 100BASE-T2 full duplex mode > ^^ >=20 > (5h) mauIfGrp100Mbs -- spurious blank line -- [legacy/repagination] >=20 > Perhaps as an artifact of the text reformatting (new=20 > pagination), there now is a spurious blank line in the=20 > mauIfGrp100Mbs OBJECT-GROUP macro invocation, on top of page 40. > The RFC says: >=20 > } > | > STATUS deprecated >=20 > It should say: >=20 > } > STATUS deprecated >=20 > 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. >=20 > (5i) mauModRpCompl2 -- spurious blank line -- [legacy/repagination] >=20 > Similarly as above, the mauModRpCompl2 MODULE-COMPLIANCE=20 > macro invocation contains a spurious blank line, after the=20 > 8th non-blank text line on page 45. > The RFC says: >=20 > GROUP rpMauNotifications > | > DESCRIPTION "Implementation of this group is recommended > for MAUs attached to repeater ports." >=20 > It should say: >=20 > GROUP rpMauNotifications > DESCRIPTION "Implementation of this group is recommended > for MAUs attached to repeater ports." >=20 > (5j) mauModIfCompl3 -- lost blank line -- [legacy/repagination] >=20 > In contrast to the two preceding items, in the mauModIfCompl3=20 > MODULE-COMPLIANCE macro invocation, a separating blank line=20 > has been lost. > At the top of page 46, the RFC says: >=20 > 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 > [...] >=20 > It should say: >=20 > 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 > [...] >=20 >=20 > (6) Section 5 (IANA-MAU-MIB Module) >=20 > (6a) IANAifMauTypeListBits TC -- formatting -- [legacy++] >=20 > The SYNTAX clause of the IANAifMauTypeListBits=20 > TEXTUAL-CONVENTION, on page 48 of RFC 4836, contains three=20 > blank lines. > I suspect that these initially were intended to visually=20 > group the lines according to the speed classes; but this was=20 > never handled correctly; e.g., in : >=20 > SYNTAX BITS { > bOther(0), -- other or unknown > bAUI(1), -- AUI > b10base5(2), -- 10BASE-5 > bFoirl(3), -- FOIRL > | > b10base2(4), -- 10BASE-2 >=20 > a break would perhaps have been appropiate below bOther(0),=20 > not below bFoirl(3), thus not disrupting the group of 10 Mbps=20 > MAU types, > i.e.: >=20 > SYNTAX BITS { > bOther(0), -- other or unknown > | > bAUI(1), -- AUI > b10base5(2), -- 10BASE-5 > bFoirl(3), -- FOIRL > b10base2(4), -- 10BASE-2 >=20 > In RFC 3636, there was a page break between the 10 Mbps MAU=20 > types and the 100 Mbps MAU types; in RFC 4836, there's no=20 > separating blank line there. > The addition of the new MAU types (on page 49) finally has=20 > made this grouping scheme impossible/obsolete. >=20 > I therefore recommend to remove these embedded separating=20 > blank lines from the IANA-MAU-MIB module at the next update,=20 > under the control of the designated expert. >=20 > (6b) IANAifMauMediaAvailable -- typo -- [new] >=20 > Within the DESCRIPTION clause of the IANAifMauMediaAvailable=20 > TC, in the first line of the last paragraph on page 51, a=20 > comma has been dropped. > For consistency of style and grammar, I recommend to change=20 > back in the IANA-MAU-MIB module (at the next update) the line, >=20 > For 10 Gb/s the enumerations map to value of the link_fault >=20 > to say: >=20 > For 10 Gb/s, the enumerations map to value of the link_fault >=20 > (6c) OBJECT IDENTITIES for MAU types -- visual enhancement >=20 > For enhanced readability, I also recommend to insert=20 > additional blank lines below the ASN.1 comments, "----- new=20 > since ..." in the section listing the OBJECT IDENTITIES for MAU types. >=20 > This could be done at the next regular update of the=20 > IANA-MAU-MIB module, at the places corresponding to page 56,=20 > 57, 59, and 60 in RFC 4836, respectively; e.g. (on page 56), change >=20 > ------ new since RFC 1515: > dot3MauType10BaseTHD OBJECT-IDENTITY > STATUS current > [...] > to: >=20 > ------ new since RFC 1515: > | > dot3MauType10BaseTHD OBJECT-IDENTITY > STATUS current > [...] >=20 >=20 > (7) Section 7 -- missing article -- [new] >=20 > The first paragraph of Section 7, on page 63, says: >=20 > v > | This document defines first version of the IANA-maintained=20 > IANA-MAU- > MIB module. [...] >=20 > It should say: > vvvvv > | This document defines the first version of the=20 > IANA-maintained IANA- > MAU-MIB module. [...] >=20 >=20 >=20 > If you anyway consider adressing some of the above issues by=20 > an RFC Errata Note, please make freely use of the material=20 > supplied above. >=20 > Best regards, > Alfred H=CEnes. >=20 > --=20 >=20 > +------------------------+------------------------------------ > --------+ > | TR-Sys Alfred Hoenes | Alfred Hoenes Dipl.-Math.,=20 > Dipl.-Phys. | > | Gerlinger Strasse 12 | Phone: (+49)7156/9635-0, Fax: -18=20 > | > | D-71254 Ditzingen | E-Mail: [email protected] =20 > | > +------------------------+------------------------------------ > --------+ >=20