Subject: [MIB-DOCTORS] Re: [IETFMIBS] References in MIBs

From: "C. M. Heard" <[email-masked]>
Date: Mon, 26 Feb 2007 10:52:00 -0800 (PST)

On Mon, 26 Feb 2007, Adrian Farrel wrote:
> My $0.02
>
>> >  I understand that a mib module must be an independent
>> >  section. It should  not have pointers to other sections in
>> >  the container document. I have 2 questions.
>>
>>  This recommendation aims to help people who extract the MIB
>>  modules from an RFC use easily their extracted documents.
>> 
>> >  1. What is the recommended practice for referring to
>> > 
>> >     a. an RFC in a MIB module
>> > 
>> >     i  [RFC1234]  (pointer to  the References section of the
>> >                 container document)
>> >     ii  RFC 1234
>> >     iii Abc.,D., et. al, "RFC name", RFC 1234 section p.q or,
>> >         Abc.,D., Def.,G. "RFC name", RFC 1234 section p.q
>> >     iv  any one of the above
>> >      v  other: ?
>>
>>  I prefer (i) or a combination of (i) and (iii) because it becomes
>>  readable even in the case of an extracted MIB module.
>
> MIB Doctors and RFC Editor have previously complained to me about 
> the use of (i) becuase it looks like (and is :-) an RFC citation 
> that is not valid once the MIB module has been extracted. 
> Therefore I have ended up with (ii) or (iii) depending on 
> location.

Right, I'm one of those MIB Doctors who has complained any time I've 
seen something like [RFC1234] anywhere in a MIB module.  My rule has 
been that is something won't pass muster in the abstract -- and 
something like [RFC1234] will not -- then it should not appear in a 
MIB module, either.

To expand on this point, identifiers in square brackets such as 
[RFC1234] in an RFC are citations tags, i.e., pointers to entries in 
the References section, and are exactly on a par with [1] for 
documents that use numbered references or something like [MGT:6] and 
kin used in RFC 1815.  Pointers to the References section are banned 
in the abstract because it is should be able to stand alone.  If a 
MIB module is is supposed to be capable of standing alone, then the 
ban on citation tags (whatever their style) should apply there, too.

> A. In IMPORTS clauses, it is helpful to indicate the location of 
> the MIB module from where the TC is imported. This is done with a 
> simple comment looking like:
>
> -- RFC 1234

Right.  Note that in come cases items may be imported from a MIB 
module whose authoritative version is not in an RFC.  The most 
common examples are items that are imported from an IANA-maintained 
MIB module.  In that case the ASN.1 comment can contain a URL that 
points to the most current version the module.

> B. In REFERNECE clauses, the full ciation is provided using the 
> full text that might appear in the References section of the I-D.
>
> This leaves one wrinkle. Sometimes there is no direct citation to 
> the RFC from where a TC is imported. That makes the RFC Editor's 
> toes curl because there is not allowed to be a reference in the 
> References section without a citation. This is cured by including 
> some text before the BEGIN statement that says...
>
> "The MIB module defined below includes imports from MIB modules 
> defined in [RFC1234], [RFC5678], ...."

Right.  This is as recommended in RFC 4181 Section 3.6.

In a subsequent message Adrian wrote:
> Hi Dan,
>
>> >  MIB Doctors and RFC Editor have previously complained to me
>> >  about the use of (i) becuase it looks like (and is :-) an RFC
>> >  citation that is not valid once the MIB module has been extracted.
>> >  Therefore I have ended up with (ii) or (iii) depending on location.
>> 
>>
>>  I am not sure what this means. Somebody who understands what
>>  RFC 1234 means also understands what [RFC1234] means. The
>>  advantage of using [RFC1234] is that the id-nits tool will now treat
>>  the text as a reference and will catch reference problems as with all
>>  other references in texts of RFCs.
>
> Who am I to comment on what the RFC Editor or MIB Doctors intend their
> comments to mean?
>
> I am told that [RFCxxxx] is common notation meaning "go look up this tag in
> the references section."
> When a MIB module is extracted, there is no such references section.

I agree with Adrian on these points.

> I really don't care about this :-)
> I'm simply reporting what has happened and how I have dealt with it.
>
> But:
> - consistency is good
> - rules to help writers and reviewers are helpful

Indeed.  Communication bcc:'d to the MIB Doctors list for further
discussion.

Mike

_______________________________________________
MIB-DOCTORS mailing list
[email-masked]
https://www1.ietf.org/mailman/listinfo/mib-doctors