Subject: Re: Editorial comments about DISMAN-EVENT-MIB

From: Randy Presuhn <[email-masked]>
Date: Wed, 5 Jan 2000 10:49:07 -0800 (PST)

Hi -

I'm forwarding these to the list so no one is surprised.
My recommendations are in-line below.  Thanks to Alan
for the close reading of the document!

> From: Alan Luchuk <[email-masked]>
> Date: Wed, 5 Jan 2000 13:03:34 -0500 (EST)
> Message-Id: <[email-masked]>
> To: [email-masked]
> Subject: Editorial comments about DISMAN-EVENT-MIB
> Cc: [email-masked], [email-masked]
>
> Hi Ram,
>
> As I've carefully read/thought about <draft-ietf-disman-event-mib-09.txt>,
> I have a number of editorial comments.  These are included below.  I have
> not concentrated on your latest E-mails to the DISMAN WG, so if you have
> already addressed these editorial issues, then please disregard my comments.
>
> Thanks for your continued work on this!
>
> Regards,
> --Alan
>
>  -----------------------------------------------------------------------------
>  Alan Luchuk       SNMP Research, Inc.                 Voice:  +1 865 573 1434
>  Software Engineer 3001 Kimberlin Heights Road         FAX:    +1 865 573 9197
>  [email-masked]   Knoxville, TN  37920-9716  U.S.A.   http://www.snmp.com/
>  -----------------------------------------------------------------------------
>
>    Please note that our telephone area code recently changed from 423 to 865.
>    Area 423 should countinue to work until it is phased out in April, 2000.
>
>
>   ------------ DISMAN-EVENT-MIB editorial comments included below ---------
>
> Column alignment:
> ----------------
>
> There are several places where things would look tidier if they
> were column aligned.   A few examples include:
>
>
>    mteResource         OBJECT IDENTIFIER ::= { dismanEventMIBObjects 1 }
>    mteTrigger          OBJECT IDENTIFIER ::= { dismanEventMIBObjects 2 }
>    mteObjects          OBJECT IDENTIFIER ::= { dismanEventMIBObjects 3 }
>    mteEvent       OBJECT IDENTIFIER ::= { dismanEventMIBObjects 4 }
>

This is up to the editor's discretion; it can be handled as part of
the publication process.

>
> Table row definitions (Page 15), like:
>
>
>    MteTriggerEntry ::= SEQUENCE {
>        mteOwner                  SnmpAdminString,
>        mteTriggerName            SnmpAdminString,
>        mteTriggerComment              SnmpAdminString,
>        mteTriggerTest            BITS,
>        mteTriggerSampleType      INTEGER,
>        mteTriggerValueID              OBJECT IDENTIFIER,
>        mteTriggerValueIDWildcard      TruthValue,
>        mteTriggerTargetTag            SnmpTagValue,
>        mteTriggerContextName          SnmpAdminString,
>        mteTriggerContextNameWildcard  TruthValue,
>        mteTriggerFrequency            Unsigned32,
>        mteTriggerObjectsOwner         SnmpAdminString,
>        mteTriggerObjects              SnmpAdminString,
>        mteTriggerEnabled              TruthValue,
>        mteTriggerEntryStatus          RowStatus
>    }
>

ditto.

>
> And (Page 11):
>
>
>      localResourceLack   some local resource such as memory lacking
>                     or mteResourceSampleInstanceMaximum
>                     exceeded
>      badDestination      unrecognized domain name or otherwise
>                     invalid destination address
>      destinationUnreachable   can't get to destination address
>      noResponse          no response to SNMP request
>         badType               the data syntax of a retrieved object
>                     as not as expected
>      sampleOverrun       another sample attempt occurred before
>                     the previous one completed"
>
>

This is so ugly that it probably should be fixed, though this can
be done as part of the publication process.

>
>
> Use of capitalized MAY/SHOULD/MUST, etc.
> ----------------------------------------
>
> RFC 2119 defines the usage of a number of words like MAY/SHOULD/MUST,
> etc.  There are a number of places in draft 9 where these words are
> capitalized, but I'm not sure they should be.
>
> I believe the difference is who or what these words apply to.  If
> the word (like 'may') describes the implementation, then it should
> be capitalized.  Otherwise, the word should be in lowercase.
>
> Example:  On page 8, section 6, the last sentence of paragraph 3
> reads:
>
>    "All of this takes place independently of any additional
>     instances that MAY fill the wildcard."
>
> In this case (and in others throughout the document) I believe the
> word "MAY" should be in lowercase letters.
>
> Getting all of these into the correct case (uppercase/lowercase)
> will require some thought.
>

We've discussed this one, and I believe there is agreement:
the capitalized versions are to be used only in the stating
of conformance requirements.

>
>
> Page 5, the first complete paragraph reads:
> -------------------------------------------
>
>    The trigger table lists what objects are to be monitored and how and
>    relates each trigger to an event.  It has supplementary, companion
>    tables for additional objects that depend on the type of test done for
>    the trigger.
>
>
> I suggest the following text is a little clearer:
>
>
>    The trigger table lists what MIB objects are monitored and how
>    these MIB objects are monitored.  The trigger table also relates
>    triggers to events.  It has supplementary, companion tables for
>    additional objects that depend on the type of test done for the
>    trigger.
>

Indeed, it's the mteTrigger*Tables, and not the mteTriggerTable,
that associate triggers and events.  Neither text communicates this,
unless one considers "trigger table" to be an abstraction that
is implemented in MIB-speak as mteTriggerTable and the various
mteTrigger*Tables.

>
>
> Page 5, the third complete paragraph reads:
> -------------------------------------------
>
>    The event table defines what happens when an event is triggered,
>    sending a notification, setting a MIB object or both.  It has
>    supplementary, companion tables for additional objects that depend
>    on the action taken.
>
>
> I suggest the following punctuation change is a little clearer:
>
>
>    The event table defines what happens when an event is triggered:
>    sending a notification, setting a MIB object, or both.  It has
>    supplementary, companion tables for additional objects that depend
>    on the action taken.
>

I leave the replacement of the "," with a ":" to the editor.

>
> Page 8, second paragraph, last sentence, reads:
> -----------------------------------------------
>
>    A self-management only system MAY not implement remote monitoring.
>
> I suggest the following text is a little clearer:
>
>    An implementation of the DISMAN-EVENT-MIB MAY support only
>    self-management.  That is, an implementation MAY omit remote
>    monitoring.
>

Ok.

>
> Page 8, third paragraph, reads:
> -------------------------------
>
>    Wildcards indicate that the application SHOULD use a GetNext-type
>    operation to find the zero or more instances implied by a truncated
>    object identifier, just like an ordinary SNMP-based management
>    application.  Each instance of a wildcard is treated as if it were a
>    separate entry, that is the instances of a wildcarded object are
>    independent of one another.  For example, a wild-carded object MAY
>    trigger an event and result in the setting of another wildcarded object.
>    The instance that satisfied the trigger function is used to perform the
>    set function.  All of this takes place independently of any additional
>    instances that MAY fill the wildcard.
>
> I suggest the following text has a few grammatical corrections:
>
>    Wildcards indicate that the application should use a GetNext-type

We're on a slippery slope here.  To the extent that the operation
of an implementation of this MIB may result in traffic on the
network, this "should" probably should be a "SHOULD".

>    operation to find the zero or more instances implied by a truncated
>    object identifier, just like an ordinary SNMP-based management
>    application.  Each instance of a wildcard is treated as if it were a
>    separate entry, that is, the instances of a wildcarded object are
>    independent of one another.  For example, a wildcarded object may
>    trigger an event, and may result in the setting of another wildcarded

There's no need for the second may.  I think the phenomenon
is called "gapping" in transformational grammar.

>    object.  The instance that satisfied the trigger function is used
>    to perform the set function.  All of this takes place independently
>    of any additional instances that may fill the wildcard.
>

This looks ok.

>
>
> Page 8, fourth paragraph:
> -------------------------
>
>    Need a few spaces between "[rfcNotificationLogMIB]." and "MIB".

?? The only occurrance of rfcNotificationLogMIB is on page 6.
The "rfc" should be replaced with RFC, though the whole thing
should be replaced during the publication process.

>
> Page 8, sixth paragraph:
> ------------------------
>
> "implementation specific" should be "implementation-specific".
>

Editor's discretion.

>
> Page 14
> -------
>
> Add a "UNITS" clause to mteTriggerFailures.
>

Makes sense.

>
> Page 16, second paragraph:
> --------------------------
>
> Currently reads:
>
>    For 'existence', the specific test is as selected by
>    mteTriggerExistenceTest.  When an object appears or vanishes
>    the trigger fires.  The trigger will not fire again until the
>    object has changed states.
>
> I suggest the following text is a little clearer (and more accurate):
>
>    For 'existence', the specific test is as selected by
>    mteTriggerExistenceTest.  When an object appears, vanishes, or
>    changes value, then the trigger fires.  The trigger will not
>    fire again until the object has changed states.
>

Adding "or changes value" would be a significant technical change.
This would be inappropriate at this time.  Unless there is a good
internal consistency argument that the current text here is in
error, as WG chair I'm inclined to rule "too late" on this one.

>
> Page 25
> -------
>
> The DESCRIPTION clause for the mteTriggerExistenceEventOwner
> references the mteObjectsTable.
>

I believe the current description is correct.
It's consistent with all the other mte*EventOwner objects.

>
> Page 37
> -------
>
> The DESCRIPTION clause for the mteEventNotificationTable reads:
>
>   "A table of management event action notification information."
>
> I suggest the following text is a little clearer:
>
>   "A table of information about all notifications that may be
>    sent in response to management events."
>

I'd suggest a bit more word-smithing:

|   "A table of information about notifications to be
|    sent as a consequence of management events."

but I leave it up to the editor.

 ------------------------------------------------------------------------
 Randy Presuhn           [email-masked]       http://www.bmc.com/
 Voice: +1 408 546-1006  BMC Software, Inc.  1-3141  2141 N. First Street
 Fax:   +1 408 965-0359  San Jose, California 95131  USA
 ------------------------------------------------------------------------
 Any relationship between my opinions and BMC's should be coincidental.
 ------------------------------------------------------------------------

---

From: Randy Presuhn <[email-masked]>
Date: Wed, 5 Jan 2000 14:07:01 -0800 (PST)

Hi -

> Date: Wed, 5 Jan 2000 14:56:36 -0500 (EST)
> Message-Id: <[email-masked]>
> To: [email-masked]
> Subject: Re:  Editorial comments about DISMAN-EVENT-MIB
> Cc: [email-masked], [email-masked], [email-masked]
> List-Id: IETF disman Working Group mailing list <[email-masked]>
...
> I have questions about Randy's replies to my editorial comments on 
> <draft-ietf-disman-event-mib-09.txt>.   In this reply, I deleted 
> most of Randy's comments to shorten the E-mail.  What remains are
> only the few items I have questions about.
> 
> 
> 
> Are we both looking at <draft-ietf-disman-event-mib-09.txt>?

Silly me.  I was looking at the most recent i-d, which is just -08.
Yet another reason why stuff should be posted as i-ds, rather than
just being sent to the mailing list.  My mistake.

> I doubled checked, in my copy, this is in _section_ 6, titled
> "Operation", on _page_ 8.

??  I think you mean there should be a couple of spaces before the
word "Note".  "MIB" and "[rfcNotificationLogMIB]." are on different
lines.

> Why would adding "or changes value" be a significant technical change?
> The mteTriggerExistenceTest object is defined (on page 24) as follows:
> 
>    mteTriggerExistenceTest OBJECT-TYPE
>        SYNTAX      BITS { present(0), absent(1), changed(2) }
>        MAX-ACCESS  read-write
>        STATUS      current
>        DESCRIPTION
>         "The type of existence test to perform.  The trigger fires
>         when the object at mteTriggerValueID is seen to go from
>         present to absent, from absent to present, or to have it's
>         value changed, depending on which tests are selected.
> 
>         Once the trigger has fired for either presence or absence it
>         will not fire again for that state until the object has been
>         to the other state."
>        DEFVAL { { present, absent } }
>        ::= { mteTriggerExistenceEntry 1 }
> 
> 
> Adding "or changes value" (on page 16, second paragraph) simply states 
> in verbiage what the the mteTriggerExistenceTest SYNTAX and DESCRIPTION
> clauses (on page 24) already says.

Ok.  You've convinced me.  Ram, fix it.  :-)

> Personally, I don't really care about whether or not "or changes value"
> is added on page 16, I just thought adding the my suggested text would 
> more accurately reflect the definition of mteTriggerExistenceTest.  I'm 
> asking why this is considered a technical change so I better understand 
> the IETF standards-writing "procedural" stuff.

That's why I handed you the "Unless".  You've given a solid argument
based on the internal consistency of the specification.  I agree it
should be fixed, based on your argument.

> Huh?  I double-checked.  Closely compare the DESCRIPTION clauses of:
> 
>    mteTriggerExistenceEventOwner 
>    mteTriggerBooleanEventOwner
>    mteTriggerThresholdRisingEventOwner
>    mteTriggerThresholdFallingEventOwner
> 
> The DESCRIPTION clause of mteTriggerExistenceEventOwner differs
> from the other three.  I thought the EventOwner objects referred
> to the mteEventTable, not the mteObjectsTable (as written in the
> mteTriggerExistenceEventOwner DESCRIPTION clause.)
...

Right again.  Ram, fix it. :-)

---

From: Ramanathan Kavasseri <[email-masked]>
Date: Thu, 06 Jan 2000 14:01:37 -0800

>word "Note".  "MIB" and "[rfcNotificationLogMIB]." are on different

Ahhhh...
*bing* - I finally figured what you were saying...Done.

>Ok.  You've convinced me.  Ram, fix it.  :-)

By "fix it", did you mean add Alan's text (that would be the easiest thing to
do, and would not change the operation of mteTriggerExistenceTest), or
remove the "or to have its value changed," text, which is a significant
operational deviation from the existing text? I'm assuming
that it's the former...

>Right again.  Ram, fix it. :-)

Done. :-)

BTW, Alan, thanks for the detailed reviews...
:-)

Ram

---

From: Randy Presuhn <[email-masked]>
Date: Thu, 6 Jan 2000 16:41:33 -0800 (PST)

Hi -

> Message-Id: <[email-masked]>
> Date: Thu, 06 Jan 2000 14:01:37 -0800
> To: Randy Presuhn <[email-masked]>, [email-masked]
> From: Ramanathan Kavasseri <[email-masked]>
...
...

Your assumption is correct.