Subject: [IETFMIBS] References in MIBs

From: "Glenn M. Keeni" <[email-masked]>
Date: Sat, 24 Feb 2007 15:40:20 +0900

Hi,
  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.

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: ?

  b. an internet-draft which is a normative reference and
   is expected to become an RFC (probably sometime before
   the document in question becomes an RFC)

    [RFCABCD] ( pointer to the References section
               of the container document)
     RFCXXXX
        -- Note to RFC Editor: RFCXXXX refers to I-D
        -- "draft-xxx-yyyy-abc.nn.txt"
        --  please replace XXXX by the assigned RFC number
        --  when the I-D becomes an RFC and remove this note.

2. If the suggested mode of reference in (1) above is (iii)
   then should that mode be followed for every instance of a
   reference or, should all the references be collected and
   presented in a REFERENCE section in the MIB module ( this
   will be a subset of the Reference section of the container
   document)?

I checked RFC 4181 I could not find any  hints. Any pointers
will be helpful.

Thanks

Glenn

_______________________________________________
IETFMIBS mailing list
[email-masked]
https://www1.ietf.org/mailman/listinfo/ietfmibs

---

From: "Romascanu, Dan \(Dan\)" <[email-masked]>
Date: Sun, 25 Feb 2007 17:51:40 +0200

See in-line. 

I hope this helps. 

Dan

> -----Original Message-----
> From: Glenn M. Keeni [mailto:[email-masked]] 
> Sent: Saturday, February 24, 2007 8:40 AM
> To: [email-masked]
> Subject: [IETFMIBS] References in MIBs
> 
> Hi,
> 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. 

>        Abc.,D., Def.,G. "RFC name", RFC 1234 section p.q

I prefer (i) or a combination of (i) and (iii) because it becomes
readable even in the case of an extracted MIB module. 

>         --  when the I-D becomes an RFC and remove this note.

Yes, this helps, although the RFC Editor should also know to do it, or
you (as author) can help him do it in final phases of the publication
process. 

>    will be a subset of the Reference section of the container

It is not clear to me what you mean here, or maybe I do not understand
well what you mean by a REFERENCE section in the MIB module, The proper
thing to do is 

- to use REFERENCE clauses specific for objects in the MIB module
wherever this applies
- to list the reference RFC for IMPORT-ed objects and TCs

---

From: "Glenn M. Keeni" <[email-masked]>
Date: Mon, 26 Feb 2007 12:22:31 +0900

Dan,
    Thanks, that is helpful.

Glenn

---

From: "Adrian Farrel" <[email-masked]>
Date: Mon, 26 Feb 2007 11:29:38 -0000

Hi,

My $0.02

> This recommendation aims to help people who extract the MIB
> modules from an RFC use easily their extracted documents.
>

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.

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

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

Adrian

---

From: "Romascanu, Dan \(Dan\)" <[email-masked]>
Date: Mon, 26 Feb 2007 14:58:41 +0200

> From: Adrian Farrel [mailto:[email-masked]] 
> Sent: Monday, February 26, 2007 1:30 PM
> To: Romascanu, Dan (Dan); Glenn M. Keeni; [email-masked]
> Subject: Re: [IETFMIBS] References in MIBs
> 
> Hi,
> 
> 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.
> >
> (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

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. 

Dan

(speaking as a contributor)

---

From: "Adrian Farrel" <[email-masked]>
Date: Mon, 26 Feb 2007 13:34:28 -0000

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

Adrian

---

From: "Wijnen, Bert \(Bert\)" <[email-masked]>
Date: Mon, 26 Feb 2007 15:57:30 +0100

When I was AD, I had been applying these rules (I was not 
always 100% strict).

- In an RFC abstract, one uses: RFC xxxx and not [RFCxxxx]

- In DESCRIPTION and REFERENCE clauses I prefered: RFC xxxx
  In fact I often tried to convince people to
  change a [RFCxxxx] into an RFC xxxx
  and I indeed also rpefered that they added title of RFC and a section
  if possible.

- But in the MIB module I would be OK (accept) with comment lines aka
      IMPORT mib-2 FROM SNMPv2-SMI   -- [RFC2579]
  although I liked better 
      IMPORT mib-2 FROM SNMPv2-SMI   -- RFC 2579
  with text as below advise
 
- And I have been advising to use a structure aka

   X.  MIB DEFINITION

       The following MIB module IMPORTS from [RFCxxxx] and [RFCyyyy],
       and it further refers to [RFCzzzz] in REFERENCE and/or
DESCRIPTION
       clauses.

       XXX-MIB :: DEFINITIONS BEGIN

Hope this helps at least insofar as to describe what I had been trying
to 
promote. I think the above area reasonable approaches.

Bert

> Sent: maandag 26 februari 2007 12:30
> about the use of
> 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
> 
> 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], ...."
> 
> 
> Adrian 
> 
> 
>

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Mon, 26 Feb 2007 17:03:08 +0100

>        XXX-MIB :: DEFINITIONS BEGIN

While I understand all the motivations behind this, I like to note 
that this is potentially misleading in case modules get revised. 
I would prefer to have actually no RFC referenced in the MIB modules
themself (except the reference to the RFC which defined the module) 
and in the RFC there could be language that says "The following MIB 
modules imports from the modules AA-MIB and BB-MIB. At the time of 
this writing, the latest version of AA-MIB was published in [RFCXXXX] 
and the latest version of BB-MIB in [RFCYYYY]."

/js

-- 
Juergen Schoenwaelder		 Jacobs University Bremen
<http://www.eecs.iu-bremen.de/>	 P.O. Box 750 561, 28725 Bremen, Germany

---

From: "Eduardo Cardona" <[email-masked]>
Date: Mon, 26 Feb 2007 10:01:00 -0700

See below, 

-----Original Message-----
From: Juergen Schoenwaelder [mailto:[email-masked]] 
Sent: Monday, February 26, 2007 9:03 AM
To: Wijnen, Bert (Bert)
Cc: [email-masked]
Subject: Re: [IETFMIBS] References in MIBs

/js

Juergen, 
The other case is the MIB object referencing a protocol specification,
(in the REFERENCE Clause) either an RFC (the problem here)  or a
external specification and using [] or not. 

Note that in this case the protocol  reference also corresponds to the
latest (or not the latest but the appropiated) protocol specification
available.

What I recall on Bert's structure to place [RFC xxxx] in the imports is
to cover at least once the reference in the document so the nits tool
will not find an unused reference

That is covered as well with:

"The following MIB module IMPORTS from [RFCxxxx] and [RFCyyyy],
 and it further refers to [RFCzzzz] in REFERENCE and/or [AAA-proto]"

 or in your text: 

"The following MIB modules imports from the modules AA-MIB and BB-MIB.
At the time of this writing, the latest version of AA-MIB was published
in [RFCXXXX] and the latest version of BB-MIB in [RFCYYYY].
The MIB modules also include in REFERENCE the appropiated versions of
[RFCZZZ] ,,, and [AAA-proto]"

This is to cover the protocols referenced by particular MIB objects
independent of RFCs or not, if those are not perviously discussed in the
module description sections. 

One issue - maybe marginal: 
What if you want to point to a TC not defined in IETF, but publicly
available in IETF liaison organizations such as IEEE? - which had IETF
MIB Doctor's review process, etc. 
IS that prohibited for IETF RFCs ? Or should those be redefined? - I
mean the problem here is RFC references is one subset of possible
references.

Thanks

Eduardo

---

From: "Wijnen, Bert \(Bert\)" <[email-masked]>
Date: Mon, 26 Feb 2007 18:06:56 +0100

Juergen (and others), I think that would indeeed even be better

Bert 

> Sent: maandag 26 februari 2007 17:03
> To: Wijnen, Bert (Bert)
> Cc: Adrian Farrel; Romascanu, Dan (Dan); Glenn M. Keeni; 
> [email-masked]
> While I understand all the motivations behind this, I like to 
> note that this is potentially misleading in case modules get revised. 
> I would prefer to have actually no RFC referenced in the MIB 
> modules themself (except the reference to the RFC which 
> defined the module) and in the RFC there could be language 
> that says "The following MIB modules imports from the modules 
> AA-MIB and BB-MIB. At the time of this writing, the latest 
> version of AA-MIB was published in [RFCXXXX] and the latest 
> version of BB-MIB in [RFCYYYY]."
> 
> /js
> 
> --

---

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

On Mon, 26 Feb 2007, Adrian Farrel wrote:
> 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. 

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.

> When a MIB module is extracted, there is no such references section.

I agree with Adrian on these points.

> - rules to help writers and reviewers are helpful

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

Mike

---

From: "Romascanu, Dan \(Dan\)" <[email-masked]>
Date: Mon, 26 Feb 2007 22:10:33 +0200

> From: C. M. Heard [mailto:[email-masked]] 
> >> 
> 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.
> 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.
> 

I respectfully disagree on this with Mike for two reasons.

1. The recommendation about not using references in Abstract section is
not specific to MIB documents and needs not be applied to the rest of
the document, the MIB modules included 
2. Including bracketed references in the MIB modules would allow the
references to be checked by id-nits or other tools for reference
problems. If the style [RFC1234] is used for references rather than [1]
or [MGT:6] it will be not problem for a reader of an extracted MIB
module to understand what this reference means, which is I believe what
Mike means by the MIB module being 'able of standing alone'. 

Dan

---

From: "tom.petch" <[email-masked]>
Date: Tue, 27 Feb 2007 10:27:09 +0100

To expand on one detail, inline ...

Tom Petch

----- Original Message -----
From: "C. M. Heard" <[email-masked]>
To: "IETF MIBs" <[email-masked]>
Sent: Monday, February 26, 2007 7:52 PM
Subject: Re: [IETFMIBS] References in MIBs

> ban on citation tags (whatever their style) should apply there, too.

My experience is that it is the REFERENCE clause that needs to be stand alone,
not the whole of the MIB module, since that clause is what is displayed by a
Manager to a user.

I note that the recent RFC4750 omits any mention of an RFC in the REFERENCE
clause.  I prefer the approach of draft-ietf-pwe3-pw-mib which uses, eg,
"Martini, et al, 'Pseudowire Setup and Maintenance using the Label Distribution
Protocol.', RFC 4447." although that would be even better if it also had a
section number for each reference.