[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Last call

On Mon, Dec 19, 2005 at 06:57:57PM -0500, David B Harrington wrote:
 
> I'd like to start a two-week MIB Doctor Last Call on the MIB Template,
> before I ask Bert to post it to the OPS Area web site. 
> 
> I have included the XML2RFC template (which you should review for the
> comments that don't get printed out, and the output file from running
> the template through XML2RFC. 

My main observation is that the document currently mixes information
concerning

(a) how to use the xml2rfc format
(b) how to structure a MIB document
(c) sample text that must be rewritten/removed when you use the template
(d) text intended to be copied verbatim

and it is not always clear what is what. (a) is mostly captured in XML
comments, (b) is captured in the text produced but also in XML
comment, while (c) and (d) are mostly text being produced on the
output. I think it will help clarity if things are dealt with in a
more consistent and easy to recognize way. (Otherwise we will for sure
see MIB modules which tell us something about sampl999 features ;-)

My proposal would be to capture (a) in XML comments, (b) and (d)
should be the output generated when you run xml2rfc and (c) should
either be just XML comments or it should be output (pick one option).
In any case, I think (c) needs to be clearly marked.

My second observation is that the plain .xml is rather hard to read,
most likely because it was produced by a tool which does not care much
of producing human readable output (= nicely indented output with text
broken such that it fits on classic 80 column displays). I tried to
run various XML formatters - they usually get the XML indentation
right but do a poort job to align the text. Does anybody out there
have a pointer to a good free tool to get this straight?

My third observation is that the MIB module fragment should have less
syntax errors. In addition, I recommend to not use comments with lines
consisting of hyphens since many people do not understand the ASN.1
rules for comments and might have interesting surprises when they
add/remove hyphens or insert white space at interesting places. I was
also a bit confused why you have explicit GROUP clauses in the
MODULE-COMPLIANCE statements that repeat that modules are mandatory.

/js

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