Subject: Purely editorial changes to the notification draft

From: David Partain <[email-masked]>
Date: Wed, 25 Jul 2007 22:03:21 +0200

Hi,

The attached diff includes suggested textual changes to the notification draft 
(version dated July 8, 2007).  I hope these improve readability.

netconf -> NETCONF throughout the text...

Should the "must" in 3.2.2 be "MUST"?  I believe so but didn't change it.

I have only rudimentarily touched Section 1.4 (Requirements) since it is 
getting a rewrite anyway.

I think it would be better to use startTime and stopTime (and other 
similar "keywords") throughout rather than using "start time" sometimes 
and "startTime" in others.  I have, however, not made this change.  I would be 
happy to make changes to startTime and stopTime if others think this is a 
good idea.

Cheers,

David

--- draft-ietf-netconf-notification-08.txt.orig	2007-07-23 14:38:49.000000000 +0200
+++ draft-ietf-netconf-notification-08.txt	2007-07-25 21:58:19.000000000 +0200
@@ -209,11 +209,11 @@
 
    Subscription:  An agreement and method to receive event notifications
       over a NETCONF session.  A concept related to the delivery of
-      notifications (if any to send) involving destination and selection
+      notifications (if there are any to send) involving destination and selection
       of notifications.  It is bound to the lifetime of a session.
 
    Operation:  This term is used to refer to NETCONF protocol operations
-      [NETCONF].  Specifically within this document, operation refers to
+      [NETCONF].  Within this document, operation refers to
       NETCONF protocol operations defined in support of NETCONF
       notifications.
 
@@ -264,9 +264,9 @@
    to specify which events are of interest.  These are specified when
    the subscription is created.
 
-   A NETCONF server is will not read RPC requests, by default, on the
+   A NETCONF server will, by default, not read RPC requests on the
    session associated with the subscription until the notification
-   subscription is done.  A capability may be advertised to announce
+   subscription is completed.  A capability may be advertised to announce
    that a server is able to process RPCs while a notification stream is
    active on a session.  The behaviour of such a capability is outside
    the scope of this document.
@@ -284,18 +284,18 @@
 
    The following requirements have been addressed by the solution:
 
-   o  Initial release should ensure it supports notification in support
+   o  Initial release should ensure it supports notifications in support
       of configuration operations
 
    o  Data content must not preclude the use of the same data model as
       used in configuration
 
-   o  Solution should support a reasonable message size limit (ie, not
+   o  Solution should support a reasonable message size limit (i.e., not
       too short)
 
    o  Solution should provide reliable delivery of notifications
 
-   o  Solution should provide a subscription mechanism (A NETCONF server
+   o  Solution should provide a subscription mechanism (a NETCONF server
       does not send notifications before being asked to do so and the
       NETCONF client initiates the flow of notifications)
 
@@ -361,13 +361,13 @@
       Stream:
 
          An optional parameter that indicates which stream of events is
-         of interest.  If not present, then events in the default
+         of interest.  If not present, events in the default
          NETCONF stream will be sent.
 
       Filter:
 
          An optional parameter that indicates which subset of all
-         possible events are of interest.  The format of this parameter
+         possible events is of interest.  The format of this parameter
          is the same as that of the filter parameter in the NETCONF
          protocol operations.  If not present, all events not precluded
          by other parameters will be sent.  See section 3.6 for more
@@ -410,12 +410,12 @@
    Negative Response:
 
       An <rpc-error> element is included within the <rpc-reply> if the
-      request cannot be completed for any reason.  Subscription requests
+      request cannot be completed for some reason.  Subscription requests
       will fail if a filter with invalid syntax is provided or if the
       name of a non-existent profile or stream is provided.
 
       If a stopTime is specified in a request without having specified a
-      startTime the following error is returned:
+      startTime, the following error is returned:
 
          Tag: missing-element
 
@@ -473,12 +473,12 @@
 
    Description:
 
-      An event notification is sent to the client who initiated a
-      <create-subscription> command asynchronously when an event of
-      interest (i.e., meeting the specified filtering criteria) to them
-      has occurred.  An event notification is a complete and well-formed
+      When an event of interest occurs (i.e., matches the specified
+      filtering criteria), an event notification is sent asynchronously 
+      to client(s) that initiated a <create-subscription> command
+      for the event.  An event notification is a complete and well-formed
       XML document.  Note that <notification> is not an RPC method but
-      rather the top level element identifying the one way message as a
+      rather the top level element identifying the one-way message as a
       notification.
 
    Parameters:
@@ -490,7 +490,7 @@
 
    Response:
 
-      No response.  Not applicable.
+      This is not applicable as there is no response.

@@ -509,7 +509,7 @@
    Closing of the event notification subscription can be done by
    terminating the NETCONF session ( <kill-session> ) or the underlying
    transport session.  If a stop time is provided when the subscription
-   is created, then the subscription will terminate after the stop time
+   is created, the subscription will terminate after the stop time
    is reached.  In this case, the NETCONF session will still be an
    active session.
 
@@ -597,7 +597,7 @@
    An event stream is defined as a set of event notifications matching
    some forwarding criteria.
 
-   The diagram depicted in Figure 2 illustrates the notification flow
+   Figure 2 illustrates the notification flow
    and concepts identified in this document.  The following is observed
    from the diagram below: System components (c1..cn) generate event
    notifications which are passed to a central component for
@@ -633,7 +633,7 @@
    +----+    |    +---------+
    +----+    |    |central  |-> stream 1
    | c2 |    +--->|event    |-> stream 2     filter  +-------+
-   +----+    |    |processor|-> NETCONF stream ----->|netconf|
+   +----+    |    |processor|-> NETCONF stream ----->|NETCONF|
     ...      |    |         |-> stream n             |server |
    System    |    +---------+                        +-------+
    Components|        |                                 /\
@@ -647,7 +647,7 @@
                                                         ||
                                                         \/
                                                     +-------+
-                                                    |netconf|
+                                                    |NETCONF|
                                                     |client |
                                                     +-------+
 
@@ -690,7 +690,7 @@
 3.2.4.  Event Stream Sources
 
    With the exception of the default event stream (NETCONF
-   notifications) specification of additional event stream sources
+   notifications), specification of additional event stream sources
    (e.g., SNMP, syslog, etc.) is outside the scope of this document.
    NETCONF server implementations may leverage any desired event stream
    source in the creation of supported event streams.
@@ -706,7 +706,7 @@
    <eventStreams> subtree via a <get> operation.  Available event
    streams for the requesting session are returned in the reply
    containing the <name> and <description> elements, where the <name>
-   element is mandatory and its value is unique within the scope of a
+   element is mandatory, and its value is unique within the scope of a
    NETCONF server.  The returned list must only include the names of
    those event streams for which the NETCONF session has sufficient
    privileges.  The NETCONF session privileges are determined via access
@@ -728,7 +728,7 @@
 Internet-Draft         NETCONF Event Notifications             July 2007

-   Example: Retrieving available event stream list using <get>
+   Example: Retrieving the list of available event streams using the <get>
    operation:

@@ -755,7 +755,7 @@
      <eventStreams xmlns="urn:ietf:params:xml:ns:netmod:notification">
         <stream>
            <name>NETCONF</name>
-           <description>Default netconf event stream
+           <description>Default NETCONF event stream
            </description>
            <replaySupport>true</replaySupport>
            <replayLogStartTime>2007-07-08T00:00:00Z</replayLogStartTime>
@@ -788,9 +788,9 @@
 
 3.2.5.2.  Event Stream Subscription
 
-   A NETCONF client may request from the NETCONF server the list of
-   event streams available to this session and then issue a <create-
-   subscription> request with the desired event stream name.  Omitting
+   A NETCONF client may request the list of event streams available to
+   this session from the NETCONF server and issue a <create-subscription>
+   request with the desired event stream name.  Omitting
    the event stream name from the <create-subscription> request results
    in subscription to the default NETCONF event stream.
 
@@ -802,10 +802,10 @@
    associated with the event notification subscription and does not
    modify the event stream configuration.
 
-   XPATH support for the Notification capability is advertised as part
+   XPATH support for the notification capability is advertised as part
    of the normal XPATH capability advertisement.  If XPATH support is
-   advertised via the XPATH capability then XPATH is supported for
-   notification filtering and if this capability is not advertised, then
+   advertised via the XPATH capability, XPATH is supported for
+   notification filtering.  If XPATH support is not advertised,
    XPATH is not supported for notification filtering.
 
 3.3.   Notification Replay
@@ -818,7 +818,7 @@
    notifications are sent the same way as normal notifications.
 
    A replay of notifications is specified by including an optional
-   parameter to the subscription command that indicates the start time
+   parameter (startTime) in the subscription command that indicates the start time
    of the replay.  The end time is specified using the optional stopTime
    parameter.  If not present, notifications will continue to be sent
    until the subscription is terminated.
@@ -842,7 +842,7 @@
 
    Replay is dependent on a notification stream supporting some form of
    notification logging, although it puts no restrictions on the size or
-   form of the log, nor where it resides within the device.  Whether or
+   form of the log, or where it resides within the device.  Whether or
    not a stream supports replay can be discovered by doing a <get>
    operation on the eventStreams element of the Notification Management
    Schema.  This schema also provides the replayLogStartTime element to
@@ -865,12 +865,11 @@
 
    A replayComplete notification is sent to indicate that all of the
    replay notifications have been sent.  If this subscription has a stop
-   time, then this session becomes a normal NETCONF session again.  In
-   the case of a subscription without a stop time, after the
-   replayComplete notification has been sent, it can be expected that
-   any notifications generated since the start of the subscription
-   creation will be sent followed by notifications as they arise
-   naturally within the system.
+   time, then this session becomes a normal NETCONF session again.  If
+   the subscription has no stop time, it can be expected that any
+   notifications generated since the start of the subscription creation
+   will be sent after the replayComplete notification has been sent,
+   followed by notifications as they arise naturally within the system.
 
 3.3.3.  Replay Complete Notification
 
@@ -880,14 +879,14 @@
    session becomes normal command-response NETCONF session.
 
    The replayComplete can not be filtered out.  It will always be sent
-   on a relay subscription that specified a stop time.
+   on a replay subscription that specified a stop time.
 
 3.4.  Notification Management Schema
 
-   This Schema is used to learn about the event streams supported on the
-   system.  It also contains the definition of the replayComplete, which
+   This schema is used to learn about the event streams supported on the
+   system.  It also contains the definition of replayComplete, which
    is sent to indicate that an event replay has sent all applicable
-   notifications."
+   notifications.

@@ -1012,7 +1011,7 @@
 
    While it may be possible to retrieve information about subscriptions
    via a get operation, subscriptions are not stored configuration.
-   They are non-persistent state information and their lifetime is
+   They are non-persistent state information, and their lifetime is
    defined by their session.
 
 3.6.  Filter Mechanics
@@ -1065,7 +1064,7 @@

    The following figure depicts message flow between a NETCONF client
-   (C) and NETCONF server (S) in order create a subscription and begin
+   (C) and NETCONF server (S) in order to create a subscription and begin
    the flow of notifications.  It is possible that many rpc/rpc-reply
    sequences occur before the subscription is created or after a
    stopTime in a replay subscription, but this is not depicted in the
@@ -1189,7 +1188,7 @@
                                 <xs:documentation>
                                     An optional parameter that indicates
                                     which subset of all possible events
-                                    are of interest. The format of this
+                                    is of interest. The format of this
                                     parameter is the same as that of the
                                     filter parameter in the NETCONF
                                     protocol operations. If not present,
@@ -1255,7 +1254,7 @@
             <xs:documentation>
                 The command to create a notification subscription. It
                 takes as argument the name of the notification stream
-                and  filter or profile information. All of those options
+                and filter or profile information. All of those options
                 limit the content of the subscription. In addition,
                 there are two time-related parameters startTime and
                 stopTime which can be used to select the time interval
@@ -1351,14 +1350,14 @@
 
 5.1.  Subtree Filtering
 
-   XML subtree filtering is not well suited for creating elaborate
+   XML subtree filtering is not well-suited for creating elaborate
    filter definitions given that it only supports equality comparisons
    and logical OR operations (e.g., in an event subtree give me all
    event notifications which have severity=critical or severity=major or
    severity=minor).  Nevertheless, it may be used for defining simple
    event notification forwarding filters as shown below.
 
-   In order to illustrate the use of filter expressions it is necessary
+   In order to illustrate the use of filter expressions, it is necessary
    to assume some of the event notification content.  The examples
    herein assume that the event notification schema definition has an
    <events> element at the top level that contains one or more child
@@ -1438,7 +1437,7 @@
 
                                  Figure 10
 
-   The following example illustrates selecting events which have
+   The following example illustrates how to select events which have
    severities of critical, major, or minor (presumably fault events).
    The filtering criteria evaluation is as follows:
 
@@ -1481,7 +1480,7 @@
 
                                  Figure 11
 
-   The following example illustrates selecting state or config
+   The following example illustrates how to select state or config
    EventClasses or fault events that are related to card Ethernet0.  The
    filtering criteria evaluation is as follows:
 
@@ -1539,7 +1538,7 @@
 
 5.2.  XPATH filters
 
-   The following [XPATH] example illustrates selecting fault EventClass
+   The following [XPATH] example illustrates how to select fault EventClass
    notifications that have severities of critical, major, or minor.  The
    filtering criteria evaluation is as follows:
 
@@ -1570,7 +1569,7 @@
 
                                  Figure 13
 
-   The following example illustrates selecting state and config
+   The following example illustrates how to select state and config
    EventClasses or fault events that have severities of critical, major,
    or minor or come from card Ethernet0.  The filtering criteria
    evaluation is as follows:
@@ -1626,14 +1625,14 @@
 
 6.  Security Considerations
 
-   The security considerations from the base [NETCONF] document apply
-   also to the Notification capability.
+   The security considerations from the base [NETCONF] document also
+   apply to the Notification capability.
 
    The access control framework and the choice of transport will have a
    major impact on the security of the solution.
 
    The <notification> elements are never sent before the transport layer
-   and the netconf layer (capabilities exchange) have been established,
+   and the NETCONF layer (capabilities exchange) have been established,
    and the manager has been identified and authenticated.
 
    It is recommended that care be taken to ensure the secure operation
@@ -1647,24 +1646,24 @@
 
    o  notification content
 
-   One issue related to the notifications draft is the transport of data
-   from non-netconf streams, such as syslog and SNMP.  This data may be
+   One issue related to NETCONF event notifications is the transport of data
+   from non-NETCONF streams, such as syslog and SNMP.  This data may be
    more vulnerable (or is not more vulnerable) when being transported
-   over netconf than when being transported using the protocol normally
+   over NETCONF than when being transported using the protocol normally
    used for transporting it, depending on the security credentials of
    the two subsystems.  The NETCONF server is responsible for providing
    access control to stream content.
 
    If a user does not have permission to view content via other NETCONF
-   operations it does not have permission to access that content via
-   Notifications.  If a user is not permitted to view one element in the
+   operations, the user does not have permission to access that content via
+   notifications.  If a user is not permitted to view one element in the
    content of the notification, the notification is not sent to that
    user.
 
    If a subscription is created with a stopTime, the NETCONF session
    will return to being a normal command-response NETCONF session when
    the replay is completed.  It is the responsibility of the NETCONF
-   client to close off this session when it is no longer of use.
+   client to close this session when it is no longer of use.

@@ -1743,7 +1742,7 @@
    editors would like to acknowledge input at the Vancouver editing
    session from the following people: Orly Nicklass, James Balestriere,
    Yoshifumi Atarashi, Glenn Waters, Alexander Clemm, Dave Harrington,
-   Dave Partain, Ray Atarashi and Dave Perkins and the following
+   David Partain, Ray Atarashi and Dave Perkins and the following
    additional people from the Montreal editing session: Balazs Lengyel,
    Phil Shafer, Rob Enns, Andy Bierman, Dan Romascanu, Bert Wijnen,
    Simon Leinen, Juergen Schoenwaelder, Hideki Okita, Vincent Cridlig,

---

From: David Partain <[email-masked]>
Date: Wed, 25 Jul 2007 22:37:47 +0200

Hello again,

On Wednesday 25 July 2007 22:03:21 David Partain wrote:
> and "startTime" in others.  I have, however, not made this change.  I would
> be happy to make changes to startTime and stopTime if others think this is
> a good idea.

The attached diff shows what I mean...

David
--- draft-ietf-netconf-notification-08.txt.orig2	2007-07-25 22:25:23.000000000 +0200
+++ draft-ietf-netconf-notification-08.txt	2007-07-25 22:34:07.000000000 +0200
@@ -373,12 +373,12 @@
          by other parameters will be sent.  See section 3.6 for more
          information on filters.
 
-      Start Time:
+      startTime:
 
          A parameter used to trigger the replay feature and indicate
          that the replay should start at the time specified.  If
          startTime is not present, this is not a replay subscription.
-         It is valid to specify start times that are later than the
+         It is valid to specify a startTime that is later than the
          current time.  If the startTime specified is earlier than the
          log can support, the replay will begin with the earliest
          available notification.  This parameter is of type dateTime.
@@ -392,13 +392,13 @@
 Internet-Draft         NETCONF Event Notifications             July 2007

-      Stop Time:
+      stopTime:
 
          An optional parameter used with the optional replay feature to
-         indicate the newest notifications of interest.  If stop time is
+         indicate the newest notifications of interest.  If stopTime is
          not present, the notifications will continue until the
          subscription is terminated.  Must be used with and be later
-         than 'startTime'.  It is valid to specify stop times that are
+         than startTime.  It is valid to specify a stopTime that is
          later than the current time.  This parameter is of type
          dateTime.
 
@@ -508,8 +508,8 @@
 
    Closing of the event notification subscription can be done by
    terminating the NETCONF session ( <kill-session> ) or the underlying
-   transport session.  If a stop time is provided when the subscription
-   is created, the subscription will terminate after the stop time
+   transport session.  If stopTime is provided when the subscription
+   is created, the subscription will terminate after stopTime
    is reached.  In this case, the NETCONF session will still be an
    active session.
 
@@ -851,11 +851,11 @@
 3.3.2.  Creating a Subscription with Replay
 
    This feature uses optional parameters to the <create-subscription>
-   command called 'startTime' and 'stopTime'. 'startTime' identifies the
+   command called startTime and stopTime. The startTime identifies the
    earliest date and time of interest for event notifications being
    replayed and also indicates that a subscription will be providing
    replay of notifications.  Events generated before this time are not
-   matched. 'stopTime' specifies the latest date and time of interest
+   matched. The stopTime specifies the latest date and time of interest
    for event notifications being replayed.  If it is not present, then
    notifications will continue to be sent until the subscription is
    terminated.
@@ -864,9 +864,9 @@
    event was generated by the system.
 
    A replayComplete notification is sent to indicate that all of the
-   replay notifications have been sent.  If this subscription has a stop
-   time, then this session becomes a normal NETCONF session again.  If
-   the subscription has no stop time, it can be expected that any
+   replay notifications have been sent.  If this subscription has a stopTime,
+   then this session becomes a normal NETCONF session again.  If
+   the subscription has no stopTime, it can be expected that any
    notifications generated since the start of the subscription creation
    will be sent after the replayComplete notification has been sent,
    followed by notifications as they arise naturally within the system.
@@ -879,7 +879,7 @@
    session becomes normal command-response NETCONF session.
 
    The replayComplete can not be filtered out.  It will always be sent
-   on a replay subscription that specified a stop time.
+   on a replay subscription that specified a stopTime.

@@ -1204,7 +1204,7 @@
                                 A parameter used to trigger the replay
                                 feature and indicates that the replay
                                 should start at the time specified. If
-                                start time is not present, this is not a
+                                startTime is not present, this is not a
                                 replay subscription.
                             </xs:documentation>
                         </xs:annotation>
@@ -1216,10 +1216,10 @@
                                 An optional parameter used with the
                                 optional replay feature to indicate the
                                 newest notifications of interest. If
-                                stop time is not present, the
+                                stopTime is not present, the
                                 notifications will continue until the
                                 subscription is terminated. Must be used
-                                with 'startTime'.
+                                with startTime.
                             </xs:documentation>
                         </xs:annotation>
                     </xs:element>