[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
RE: XML2RFC template for MIB modules
Hi Mike,
Picky? Yes. And you hit some sensitive spots with me, and my responses
will reflect that.
I appreciate your review and suggestions, even when I disagree with
you.
This would be easier if you discussed what you would like changed in
the document I provided rather than pointing to a different document
and discussing what you'd like changed in that document. This is
time-consuming enough as is. ;-)
So let me review what you're asking for.
1) put "Security Considerations" before "IANA Considerations" (this is
arbitrary but is what is in 2223bis and rfc 4181)
Absolutely; I don't know how I've ever managed to use SNMP to manage
my networks with MIB modules where the IANA Considerations came before
the Security Considerations ;-)
Done. Actually it was already done that way in my template, just not
RFC4188 which you chose to use as a model document. Sigh.
2) - either leave out "Contact Information" or change it to
"Contributors"
(the latter being more common, especially for new work)
My template suggested a possible "Contributors" section.
RFC 4188 used Contact Information because the listed people are
authors.
see http://www.rfc-editor.org/policy.html#policy.auth2, Authors versus
Contributors
3) add some appendices just before the "References" section, and give
them appendix labels rather than section numbers;
Xml2rfc doesn't permit appendices before the references. Xml2rfc has
its own CLRs about layouts and numbering, and the developers of
xml2rfc have worked closely with the I-D and RFC editors to develop
those CLRs. Hopefully the tool will be updated to match rfc2223bis.
4) make the References section (and its subsections) unnumbered.
Xml2rfc numbers the references sections. Xml2rfc has its own CLRs
about layouts and numbering, and the developers of xml2rfc have worked
closely with the I-D and RFC editors to develop those CLRs. Hopefully
the tool will be updated to match rfc2223bis.
I note that draft-rfc-editor-rfc2223bis-08.txt doesn't number its
reference sections, but section 4.7f, which specifies the format,
shows numbering:
s. Normative References
xxx
...
xxx
s+1. Informative References
xxx
...
Xxx
5) Put the "Internet Standard Managemnt Framework" first.
I actually disagree with this. In most other documents that do not
have a mib module, the first section is an introduction - see
draft-rfc-editor-rfc2223bis-08.txt for example. For many other
documents that do have a MIB module, the first section is an
Introduction, and the second section is the ISMF boilerplate.
Putting the ISMF text first works fine when the document is ONLY a mib
module definition, and all the narrative text is about the MIB module,
but if it's a document that describes a protocol and includes a MIB
module, I think an Introduction is called for. See RFC2578, RFC2579,
RFC2580, RFC3411, RFC3412, RFC3413, RFC3415, RFC3416, RFC3417,
RFC3419, RFC4149, RFC4087, and so on.
Note that RFC3418 contains only a MIB and starts with the ISMF text,
so the SNMPv3 authors were inconsistent as well.
If MIB modules were always done as separate documents from the
documents that describe the technology being managed, then starting
with the ISMF text might make sense, for consistency among all MIB
documents, but not all documents containing MIB modules contain only
MIB modules. So I'd rather see MIB documents be consistent with other
RFCs that don't necessarily contain MIB modules, and within that
larger consistency, be consistent across MIB documents.
Having an Introduction first also gives you a natural place to put the
citations that are not allowed to be put into the abstract. It is a
fairly common practice to copy the abstract as the first part of the
introduction, and insert the citations.
I think the ISMF text makes sense as the section following the
Introduction.
6) Promote the ISMF text to a full section rather than a subsection. I
can do that.
7) Promote the RFC2119 text to a full section rather than a
subsection. I can do that, although I think it's silly to promote one
sentence of text to a full section of its own.
<soap>
Note that the Conventions section in my template was originally called
"boilerplates" so it was easier for readers to actually find where
something meaningful started in the document. Cluttering up the the
document with boilerplates seems rather stupid to me. Forcing editors
to put in all this boilerplate, and then delaying publications if the
boilerplates aren't perfect or in the right order is one reason it
takes so long to get a document through the process now, and a good
economic reason why companies have been reducing sponsorship of
editors.
It took two years to resolve all the CLRs in RFC4188, after the MIB in
that document had been converted from SMIv1 format. This doesn't help
people manage their networks.
</soap>
David Harrington
dbharrington@comcast.net
> -----Original Message-----
> From: owner-mreview@ops.ietf.org
> [mailto:owner-mreview@ops.ietf.org] On Behalf Of C. M. Heard
> Sent: Tuesday, September 27, 2005 4:39 PM
> To: 'Mreview (E-mail)'
> Subject: Re: XML2RFC template for MIB modules
>
> On Tue, 27 Sep 2005, David B Harrington wrote:
> > I have enclosed a text document that is the output of my xml2rfc
MIB
> > module template, so you can see roughly what will get generated,
and
> > can comment on the layout, etc.
>
> Thanks for kicking this off. It's a good start, but I have some
> criticisms of the proposed section organization. Looking at the
> template's table of contents I see:
>
> 1. Introduction . . . . . . . . . . . . . . . . . . . . .
> . . . . 4
> 2. Conventions . . . . . . . . . . . . . . . . . . . . .
> . . . . 4
> 2.1 The Internet-Standard Management Framework . . . .
> . . . . 4
> 2.2 Key Words . . . . . . . . . . . . . . . . . . . .
> . . . . 4
> 2.3 Textual Conventions . . . . . . . . . . . . . . .
> . . . . 4
> 3. Narrative Sections . . . . . . . . . . . . . . . . . .
> . . . . 4
> 3.1 Overview . . . . . . . . . . . . . . . . . . . . .
> . . . . 4
> 3.2 Design Principles . . . . . . . . . . . . . . . .
> . . . . 5
> 3.3 Structure of the MIB Module . . . . . . . . . . .
> . . . . 6
> 3.3.1 The sample Group . . . . . . . . . . . . . . .
> . . . . 6
> 3.3.2 The sample999 Group . . . . . . . . . . . . .
> . . . . 6
> 3.3.3 The Notifications Group . . . . . . . . . . .
> . . . . 6
> 3.4 Relationship to Other MIB Modules . . . . . . . .
> . . . . 6
> 3.4.1 Relationship to the SNMPv2-MIB . . . . . . . .
> . . . . 7
> 3.4.2 Relationship to the IF-MIB . . . . . . . . . .
> . . . . 7
> 3.4.3 MIB modules required for Imports . . . . . . .
> . . . . 7
> 4. Definitions . . . . . . . . . . . . . . . . . . . . .
> . . . . 7
> 5. Security Considerations . . . . . . . . . . . . . . .
> . . . . 13
> 5.1 Sensitive Modifiable Objects . . . . . . . . . . .
> . . . . 13
> 5.2 Sensitive Readable Objects . . . . . . . . . . . .
> . . . . 13
> 5.3 Protocol Security . . . . . . . . . . . . . . . .
> . . . . 13
> 6. IANA Considerations . . . . . . . . . . . . . . . . .
> . . . . 14
> 7. Acknowledgements . . . . . . . . . . . . . . . . . . .
> . . . . 14
> 8. References . . . . . . . . . . . . . . . . . . . . . .
> . . . . 15
> 8.1 Normative References . . . . . . . . . . . . . . .
> . . . . 15
> 8.2 Informative References . . . . . . . . . . . . . .
> . . . . 15
> Author's Address . . . . . . . . . . . . . . . . . . .
> . . . . 16
> A. Appendice A . . . . . . . . . . . . . . . . . . . . .
> . . . . 16
> B. Changes from RFC BBBB (the previous RFC for this
> specification) . . . . . . . . . . . . . . . . . . . .
> . . . . 16
> C. Open Issues . . . . . . . . . . . . . . . . . . . . .
> . . . . 16
> Intellectual Property and Copyright Statements . . . .
> . . . . 18
>
> I think this is too elaborate. It's not the way most MIB
> documents are
> done today and I can't see a good reason for that. To see
> what I mean,
> here is the TOC from ftp://ftp.isi.edu/in-notes/authors/rfc4188.txt,
> which is the current BRIDGE-MIB galley proof:
>
> 1. The Internet-Standard Management Framework
> ......................2
> 2. Conventions
> .....................................................2
> 3. Overview
> ........................................................3
> 3.1. Structure of the MIB Module
> ................................3
> 3.1.1. The dot1dBase Subtree
> ...............................6
> 3.1.2. The dot1dStp Subtree
> ................................6
> 3.1.3. The dot1dSr Subtree
> .................................6
> 3.1.4. The dot1dTp Subtree
> .................................6
> 3.1.5. The dot1dStatic Subtree
> .............................6
> 3.2. Relationship to Other MIB Modules
> ..........................6
> 3.2.1. Relationship to the SNMPv2-MIB
> ......................7
> 3.2.2. Relationship to the IF-MIB
> ..........................7
> 4. Definitions
> .....................................................8
> 5. IANA Considerations
> ............................................39
> 6. Security Considerations
> ........................................39
> 7. Acknowledgements
> ...............................................40
> 8. Contact Information
> ............................................41
> 9. Changes from RFC 1493
> ..........................................42
> 10. References
> ....................................................42
> 10.1. Normative References
> .....................................42
> 10.2. Informative References
> ...................................43
> Authors' Addresses
> ................................................43
> Full Copyright Statement
> ..........................................44
> Intellectual Property
> .............................................44
>
> Note: the last two sections aren't actually listed in the TOC of the
> RFC-to-be, but are included here for the sake of our discussion.
>
> I would call this near to ideal as a template. The things I
> would change
> would be:
>
> - put "Security Considerations" before "IANA Considerations" (this
is
> arbitrary but is what is in 2223bis and rfc 4181)
>
> - either leave out "Contact Information" or change it to
> "Contributors"
> (the latter being more common, especially for new work)
>
> - add some appendices just before the "References" section, and give
> them appendix labels rather than section numbers;
>
> - make the References section (and its subsections) unnumbered.
>
> Note that the MIB boilerplate comes first and has the title
> and section
> number EXACTLY as in
> http://www.ops.ietf.org/mib-boilerplate.html. That
> is a feature I would like to see in any MIB document
> template. I would
> also like to see a stand-alone "Conventions" section follow,
> since that
> seems to be the most common practice. If that gives heartburn, a
good
> alternate choice would be "Terminology". It seems to me that any
> discussion of TEXTUAL-CONVENTIONS should go in the "Structure of the
> MIB Module" part.
>
> I am sorry to be so picky, but one thing I don't think this template
> should be is inventive! It should simply copy the most common set
of
> best current practices that MIB documents actually use.
>
> Thanks for listening.
>
> Mike
>
>
>