RE: Suggestion for Sections in I-Ds(and RFC) containing MIb modules

["David B Harrington" <ietfdbh@comcast.net>]

Hi,

I agree that xml2rfc should be encouraged because it automatically
does the numbering, uses the newest boilerplate revisions for required
boilerplates, generates the table of contents, and enforces many of
the I-D/RFC publication requirements.

These are already generated/made easier by xml2rfc (if I remember
correctly):

1) titles
2) authors
3) date updates and expires (to a degree)
4) abstract section heading (unnumbered)
5) keywords for use in IETF search engine
6) section header numbering and internal references
7) lists
8) artwork
9) figures, including titles
10) "Status of This Memo" 
11) "Copyright Notice" 
12) "Table of Contents" 
13) " Author's Addresses" (to match the front page)
14) appendices (in a manner approved by the I-D/RFC editors)
15) references and citations
16) the xml2rfc website has preformatted references for RFCs, I-Ds,
W3C specs, and other commonly referenced documents. I believe this
feature includes the following good things (I don't use this, so might
be wrong):
	a) you can simply identitify the reference using the URL to
the xml2rfc copy in an <!ENTITY> tag, and it will insert it when it
generates the text document.
	b) for I-Ds, it will insert the latest revision known (which
it can get from the updated-daily XML listing from the I-D and RFc
editors)
17) any section heading you choose will be appropriately numbered
based on position and nesting depth; you choose the title and the
anchor (for internal references), so "Acknowledgments" and/or
"Contributors" can be added as desired.
18) Since the XML is structured and labeled, the RFC-Editor will
actually use the XML during their editing to automate checking some
things, and generating the RFC format rather than the I-D format from
the XML sources.	
19) xml2rfc also generates HTML for posting to web sites, and other
document formats for other purposes.
20) "References" (numbered to suit I-D editor)
21) IPR Boilerplate (author selects which version)

I would like to see some mib-related aspects added to the tool, but my
TCL skills and XML skills are not up to the task (not that I've
tried).

If we asked the current rfc2xml maintainers to add certain features, I
suspect they would be willing to do so, but we would need to be
specific about the features we asked for, and would probably need to
approach it incrementally. I suspect the following would be easy:
1) adding the RFC2119 boilerplate 
2) "The Internet-Standard Management Framework" (MIB boilerplate) PLUS
[RFC 3410] reference.
3) An "Overview" section heading
4) a "Definitions" section heading
5) a "Security Considerations" section heading
6) an "IANA Considerations" section heading

Thiings I believe could not be added easily, because the tool doesn't
handle not overwriting modified templates:
1) an empty MIB module layout
2) mib security considerations 

One problem I find is that people copy existing documents to use as a
template, and the document they choose is out-of-date. It certainly
would be viable to provide an up-to-date template for a MIB module
document in XML2RFC format, to encourage MIB module editors to move
towards this solution.

I probably could have egebrated onw in the time it took to write this
message ;-)

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 11:18 AM
> To: Mreview (E-mail)
> Subject: Re: Suggestion for Sections in I-Ds(and RFC) 
> containing MIb modules
> 
> On Mon, 26 Sep 2005, David T. Perkins wrote:
> > While the actual location of RFC 2119 language is not at all
> > important, and the exact details of other "required" items
> > are not so important, spending time on determining this
> > and other things isn't worth the time of reviewers. There
> > is a simple little script that checks to make sure that
> > some boilerplate text is unmodified. I'm thankful that such
> > a script exists, since it is better done with a script
> > than a human.
> > 
> > The observation that I was making is that there are many
> > little I-D (and RFC) rules that a reviewer is suppose
> > to check. This is both a burden on the document writer
> > and the reviwer. I just wish that for both writers and
> > reviewers that this was "just taken care of".
> 
> I agree with all of this.  One of my least favorite tasks
> when reviewing MIB documents is taking care of the stuff
> that goes under the heading of "General Documentation
> Guidelines" in RFC 4181.  The amount of time that I have
> to spend on any review is finite;  and all of the time
> that I spend worrying about stuff like whether the copyrights
> notices are in order, whether all the boilerplate is included,
> and whether the RFC 2119 imperatives are listed and that
> document is included as a normative reference is time that
> I will not be able to spend looking at the MIB module, which
> after all is the main point of a MIB Doctor review.
> 
> > The other observation was that when there is "creativity"
> > that is allowed in these boiler plate parts, as a reader
> > of multiple documents (especially a collection from the
> > same WG that is produced at the same time), you notice the
> > differences and wonder if there was a reason
> > for the differences. This is wasted time. I don't like
> > people to waste my time, and I bet others don't like
> > wasted time either. 
> > 
> > So my primary suggestion is that a MIB document skeleton
> > be created so that document authors (and reviewers)
> > don't need to spend any time on this aspect of documents.
> > I believe that the suggested organization of sections
> > found in the MIB reviewers guidelines doesn't go far enough.
> 
> I find all of this hard to argue with.
> 
> > To create such a skeleton, someone needs to decide what
> > is in it, and how it is organized. I don't care about
> > things like where the RFC 2119 language is included.
> > There are many other things I passionately care about,
> > such as I included in recent email to this list about
> > what should be included
> > in the DESCRIPTION clauses for tables and rows.
> 
> Here is what would propose for such a skeleton:
> 
> unnumbered first-page header (as specified in 1id-guidelines)
> unnumbered "Status of This Memo" (as specified in 1id-guidelines)
> unnumbered "Copyright Notice" (optional for drafts, but 
> include in template)
> unnumbered "Abstract" (as specified in 1id-guidelines and
rfc2223bis)
> unnumbered "Table of Contents" (required for documents over 15
pages)
> numbered "The Internet-Standard Management Framework" (MIB 
> boilerplate)
> numbered "Conventions" (RFC 2119 stuff, add NOT RECOMMENDED to list)
> numbered "Overview" (as in the MIB review guidelines)
> numbered "Definitions" (as in the MIB review guidelines)
> numbered "Security Considerations" (as in the MIB review guidelines)
> numbered "IANA Considerations" (as in the MIB review guidelines)
> optionally, numbered "Acknowledgments" and/or "Contributors"
sections
> optionally, appendices with appendix labels rather than 
> section numbers
> unnumbered "References" (as in the MIB review guidelines)
> unnumbered "Author's Address" or "Editor's Address"
> unnumbered IPR Boilerplate (full copyright notice & 
> intellectual property)
> 
> Note that the section ordering and the rules about what gets
> numbered and what does not are intended to be consistent with
> current RFC Editor practice.  That will ensure that section numbers
> (and section number references) don't change when the document is
> published.
> 
> Now, the best way to make this happen, in my view, is not to make up
> another batch of CLRs for us to enforce (that will increase reviewer
> workload, I think, rather than decrease it), but rather to dress up
> the tools to encourage people to do this.  So I think Juergen's
> suggestion to add this capability to xml2rfc is the right way to go.
> Any volunteers?
> 
> //cmh
> 
> 
>