RE: XML2RFC template for MIB modules

["C. M. Heard" <heard@pobox.com>]

On Tue, 27 Sep 2005, David B Harrington wrote:
> Picky? Yes. And you hit some sensitive spots with me, and my responses
> will reflect that. 

Yep.

> I appreciate your review and suggestions, even when I disagree with
> you.

Understood.

> 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. ;-)

Sorry about that (but it did seem easier that way).

[ skipping down a ways ]

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

I was not aware of this limitation.  I do know that 2223bis section
4.7e explicitly recommends appendices first, references later, and
the reasons seemed like good ones to me.  Oh well, they appear both
ways in RFCs (even by the same author ... cf. 3637 and 4181).

> 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 was also unaware of this limitation.  Here, too, both styles appear
in recent RFCs (3637/4188 vs. 4181).

> 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

Yep.

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

Here we just have to agree to disagree.  As you say, cases do exist
where a document contains "meat" other than a MIB module, but I think
that it NOT true of the vast majority of the documents we are asked
to review.  In EVERY case where I've been asked to give a MIB
Doctor review the only meat in the document was the MIB module.  For
those documents there is a reasonably well accepted style (as you
note even 3418 uses it), and it works.  If the purpose of making a
standardized style template is to minimize reviewer and author
workload for the things that are incidental to the main task, then
it does not seem wise to change something that is accepted and works
well in the most common cases.

That said, if this is something that most people want to change I'm
happy to shut up and go along.  Particularly since you are doing the
leg work (for which I am thankful, BTW).

//cmh