Coex draft spelling check

Hi,

Thank you, Tom, for the thorough review. 

My biggest concern as co-chair, and the biggest concern for this WG to focus on, is that the document be clear and unambiguous for implementers. There are a number of proposed changes that do neither, such the consideration of the case of the "s" on the end of reserved words, or whether commas need to precede "and" or "or" in clauses. 

As co-chair, I would like to have the document editors review your comments and apply those they agree make sense, and provide a single email response explaining which changes were made, and which were not and why. The editors understand the edits.

As co-chair, I would like to constrain mailing list discussion of grammar and spelling issues to those that have an impact on clarity and ambiguity, or changes that would impact on-the-wire behavior. Please do NOT send separate messages to debate minor grammatical changes that do not impact clarity, ambiguity, or on-the-wire behavior. 

Thanks,
dbh
---
David Harrington            
[email protected]           
co-chair, IETF SNMPv3 WG




> -----Original Message-----
> From: Tom Petch [mailto:[email protected]]
> Sent: Sunday, December 29, 2002 8:08 AM
> To: Harrington, David; [email protected] (E-mail)
> Subject: Re: WG last call: Coex draft spelling check
> 
> 
> This e-mail details 57 items of spelling, grammar, punctuation or
> comprehension most of which I believe SHOULD be changed (although I
> will argue more strongly for some than for others).  I have give each
> a reference. I sugggest that any you wish to debate are posted as
> separate e-mails with the reference in the title.  For straightforward
> changes, I have used the convention **/'old text'/'new text'/; thus
> (OBJECT IDENTIFIER**/S/s/) changes the letter s at the end from upper
> case to lower case (because the capitalised part is a proper word and
> there is no such proper word with a capital S at the end).
> 
> Apart from the first three, the items appear in the order in which
> they appear in the co-existence draft.
> 
> Items s11, s23, s31, s38, s40, s50 and s53 are matters of
> comprehension and so worth closer study.
> 
> s1) There should not be a comma before the words "and", "or" in a list
> of items (I was taught).  Thus the style of this document is to say
> "The choice is between SNMPv1, SNMPv2, or SNMPv3 coupled with SMIv1,
> SMIv2, and SMIng".
> which I would change to
> "The choice is between SNMPv1, SNMPv2 or SNMPv3 coupled with SMIv1,
> SMIv2 and SMIng".
> ", and" occurs 89 times and ", or" 15. I have not flagged these
> separately except where I believe the comma is appropriate (which it
> is when it follows a subordinate clause).
> 
> s2) There are three "e-mail" (which I regard as correct) and seven
> "email" (which I do not) in 5.4 and 10.  I suggest the latter be
> brought in line with the former.  I have not flagged these separately.
> 
> s3) J Case's organisation is given four times in Section 9 as
> " SNMP Research,Inc."
> which I suggest should be
> " SNMP Research, Inc."
> (but I would defer to his judgement:-).
> 
> S4) Copyright Notice
>    **/(2001)/(2002)/
> 
> S5) In the running title, I suggest **/versions/Versions/
> 
> s6) Table Of Contents
>  I assume the errors here will be corrected automatically when the
> titles of the sections are themselves corrected (corrections below)
> 
> s7) 1.  Overview
>    "The purpose of this document ...
>     termed the SNMP version 2 framework (SNMPv2), **(comma ok here)
> and ..."
> 
> s8)  "-  Approaches to coexistence ...
>          as well as **//the/ behaviour of proxy implementations.
> 
> s9)  "-  The SNMPv1 Message Processing Model and Community-Based
>          Security Model, which **/provides/provide/ mechanisms ..."
> for adapting SNMPv1
>          into the View-Based Access Control Model (VACM) [20],
> **/is/are/
>          documented in section 5 ... "
>      (models plural)
> 
> s10) 1.1.  SNMPv1
>       "-  STD 16, RFC 1212 [3] which defines a more concise
> description
>           mechanism, which is **/wholly/wholy/ consistent with..."
> 
> s11)   " .. 'SMIv1' is used.  This term **/generally refers/refers
> generically/ to the ..."
> 
> s12) 1.2.  SNMPv2
>    " ...(RFCs 2578, 2579, and 2580)"
>    (I would prefer /RFC 2578, RFC 2579 and RFC 2580/; the reference is
> more to a document which has the title RFC 2580 as opposed to the
> 2580th item in a list called RFC).
> 
> s13) 1.3.  SNMPv3
>    (Not checked, section needs replacing)
> 
> s14) 2.1.1.  Object Definitions
>    This contains three numbered lists (of MUSTS, SHOULDs/MAYs then
> MUSTs again) all enumerated from one.  This makes any references to
> items in the lists (eg from a working group debating the changes they
> need to make) clumsy.  I suggest that either the three lists have a
> single enumeration or, which I would prefer, the section is split into
> two with the MUSTs in one, the rest in the other, each with an
> enumeration starting from one.
> 
> s15) (2)  "The MODULE-IDENTITY macro ... any **/IMPORTs/IMPORTS/
> statement"
> 
> s16) (12) "For any object containing a DEFVAL ... (OBJECT
> IDENTIFIER**/S/s/) ..."
> 
> s17) (13) "One or more **/OBJECT-GROUPS/OBJECT-GROUPs/ MUST be
> defined"
> 
> s18) 2.1.2.  Trap and Notification Definitions
>      (5)  "The value of an invocation  ... not an INTEGER, **(comma ok
> here) and MUST ..."
> 
> s19) 2.3.  Capabilities Statements
>      "all leaf objects which are subordinate to the subtree and have a
> STATUS clause value of mandatory are deemed to be INCLUDEd."
> What is the past tense of INCLUDES?  INCLUDESed? ugly.
> Perhaps change to /are implicitly deemed to be the subject of an
> INCLUDES clause/ (but I do not know the INCLUDES clause well enough to
> be sure 'subject' is the right noun).
> 
> s20) 3.  "Translating **/Notifications Parameters/Notification
> Parameters/"
>    (since that is the phrase defined in the next paragraph)
> 
> s21) "This section describes how parameters ...
>      **/refered/referred/ to in this document ...
>      is **/refered/referred/ to in this document ...."
> 
> s22) 3.1. Should the OIDs listed under 'snmpTrapOID.0' start .1.3.6 as
> opposed to 1.3.6?
> 
> s23) 5)  "The SNMPv2 variable-bindings ... bindings will be appended
> ..."
>    (Given that appended means add at the end, whereas prepended means
> add at the beginning and added means add somewhere, is appended the
> right term?  I think I see prepends not appends).
> 
> s24) 3.2. "(1) The SNMPv1 enterprise parameter SHALL be determined as
> follows:
>        the SNMPv2 snmpTrapOID value with the last **/2/two/
> sub-identifiers..."
>      (usual to spell out small numbers)
> 
> s25) (2) "... and the notification is to be sent over IP  .."
>        (Should this specify IPv4 or is IPv6 too remote to consider
> here?)
> 
> s26) (3)  Same comment as s22)
> 
> s27) 4.  "There are two basic approaches ...
>      with any **/mono-lingual/monolingual/ implementation, regardless
> of the SNMP version
>      supported by the **/mono-lingual/monolingual/ implementation"
>      (multi-lingual but monolingual)
> 
> s28) "Proxy implementations provide a mechanism ...
>       This allows network elements which support only a single, but
> **/different/not the same/,
>       SNMP version to communicate with each other"
>  (different needs 'SNMP versions' plural whereas 'not the same' takes
> the singular)
> 
> s29) 4.1.2.3.  Processing An SNMPv1 GetRequest
>      "...or an **/SNMP/SMI/v2 syntax that is unknown to **/SNMP/SMI/v1
> ..."
>      (From the earlier sections eg section 2, syntax is part of the
> SMI not SNMP)
> 
> s30) 4.1.2.4.  Processing An SNMPv1 GetNextRequest
>      (Two number lists again; I suggest splitting this into 4.1.2.4.1
> for errors and 4.1.2.4.2 for noError)
> 
> s31) 4.1.2.4.  Processing An SNMPv1 GetNextRequest
>    "When processing an SNMPv1 GetNextRequest ... the following
> procedures MUST be followed when **/an// SNMPv2 access to MIB data is
> called as part of processing the request.
>    (reads oddly since it is not at first apparent that access is a
> program procedure call; I had suggested that it should be 'called for'
> and only realised what was meant after the next paragraph.  Rather,
> drop the 'an' to give /MUST be followed when SNMPv2 access to MIB data
> is called/ -  not perfect but better.  Or, perhaps better still, **/an
> SNMPv2 access to MIB data is called/an SNMPv2 access routine is
> called/ access routine is the phrase used in the next section)
> 
> s32) 4.1.2.4 1) **/not in view/not-in-view/
>      (for consistency with 4.2.2)
> 
> s33) "Otherwise, if the access to MIB data ...
>      (2)  "... (**/there may be more than one,/ if there is more than
> one,/ it is an implementation decision ..."
> 
> s34) (3) "-  The variable binding list of the response SHALL be
> **/composed/generated/
>           from the data as it is returned by the access to MIB data"
>       (composed of, generated from)
> 
> s35) 4.1.4.  Notification Receiver
>      "There are no special requirements **/of/for/ a notification
> receiver"
> 
> s36) 4.1.4.  Notification Receiver
>       "However, an implementation may find it useful ... to
> **/request/establish/ whether ..."
>       (I do not 'request whether').
> 
> s37) 4.2.  Proxy Implementations
>      "A proxy implementation ... subject to size
> **/contraints/constraints/ as defined"
> 
> s38) 4.2.1.  Upstream Version Greater Than Downstream Version
>      "-  If a GetBulkRequest-PDU is received and must be forwarded
>           using the SNMPv1 message version, the proxy forwarder SHALL
>           set the non-repeaters and max-repetitions fields to 0"
>      (the proxy forwarder is setting fields in an SNMPv1 PDU where the
> non-repeaters and max-repetitions fields do not exist - I suggest
> error-index and error-status instead)
> 
> s39) "-  If a GetResponse-PDU is received whose error-status field has
>           a value of **/'tooBig,'/'tooBig',/  .... contains an
> error-status field
>           with a value of **/'tooBig,'/'tooBig',/
>           and change the error-status to /'noError.'/'noError'./
>        (move punctuation outside the quotes)
> 
> s40) 4.2.2.  Upstream Version Less Than Downstream Version
>      "-  If a GetResponse-PDU is received ... the proxy MUST generate
> an alternate response
>          PDU.."
>      (I am not clear if alternate means a replacement PDU or an
> additional PDU; alternate is famously a word whose American sense is
> not its English sense but I find neither sense clear here)
> 
> s41) "-  If a GetResponse-PDU is received in response to a
> GetNextRequest-PDU ..."
>      "-  If a GetResponse-PDU is received which contains an SNMPv2
>      (in both cases you should add
>         /and the message would be forwarded using the SNMPv1 message
> version/
> as in other paragraphs since the heading of 4.2.2 includes the case of
> SNMPv2c upstream and SNMPv3 downstream in which case this translation
> is not needed.
> 
> s42) 5.2.  The SNMPv1 MP Model and SNMPv1 Community-based Security
> Model
>      (this is the first use of the acronym MP and so it should be
> expanded)
> 
> s43) 5.2.1.  Processing An Incoming Request
>      "In RFC1157 [2], section 4.1, item (3) for an entity which
> receives a
>      message, states ..."
>      (RCFC1157 section 4.1 has two numbered lists both containing an
> item 3) which is why this reference is a little clumsy!  I suggest
>   /In section 4.1 of RFC1157 [2], item (3) of the list of actions (for
> an entity which receives a message) states /
> 
> s44) "... parameters are passed to the 'desired authentication
> **/scheme.'/scheme'./
> 
> s45) "The desired authentication scheme .. using the
> processIncomingMsg ASI)
>      (First use of ASI - needs expanding)
> 
> s46) "-  If the snmpCommunityTransportTag is an empty string ... when
> checking whether
>      **//or not/ the transportDomain ..."
>      ('whether' needs an alternative)
> 
> s47) "-  The pduVersion, which should indicate an SNMPv1 version PDU
>      (if the message version was SNMPv2c, this would be an SNMPv2
> version PDU)"
>      (seems clumsy - either it should or it should not be an SNMPv1
> version PDU; how about
>     /which will indicate an SNMPv1 version PDU (or an SNMPv2c version
> PDU where appropriate)/
> 
> s48) 5.3.  The SNMP Community MIB Module
>      "When checking whether **//or not/ a transport address matches
> ..."
>      ('whether' needs an alternative)
> 
> s49) snmpCommunityTransportTag OBJECT-TYPE
>      "This object specifies a set of transport endpoints which
> **/are/is/ used"
>      (a set is singular)
> 
> s50) "In either case, if the value of this object has zero-length,
> transport endpoints are not checked when authenticating messages
> containing this community string, nor when generating notifications."
>      (does the qualification 'containing this community string' apply
> to generating notifications? I think it does in which case I would
> reword to
>       /transport endpoints are not checked either when authenticating
> messages or when generating notifications, each of which contain this
> community string./
> 
> s51) "If a management request containing a community string ...
>          the request is deemed **/unauthentic/inauthentic/"
> 
> s52) snmpTargetAddrExtTable OBJECT-TYPE
>      "The table of mask and mms values ...
>      (the first use of 'mms' - should be expanded)
> 
> s53) snmpTrapAddress
>               "The value of the agent-addr field of a Trap PDU which
>                is forwarded by a proxy forwarder application using
>                an SNMP version other than SNMPv1.  The value of this
>                object SHOULD contain the value of the agent-addr field
>                from the original Trap PDU as generated by an SNMPv1
>                agent."
>       snmpTrapCommunity
>               "The value of the community string field of an SNMPv1
>                message containing a Trap PDU which is forwarded by a
>                a proxy forwarder application using an SNMP version
>                other than SNMPv1.  The value of this object SHOULD
>                contain the value of the community string field from
>                the original SNMPv1 message containing a Trap PDU as
>                generated by an SNMPv1 agent."
>      (These two descriptions are saying the same thing so why the
> different wording?  And I am not sure I understand either.  Presumably
> the proxy forwarder has SNMPv1 agent downstream and another version
> upstream and is taking the values from an SNMPv1 Trap PDU.  But where
> is it then putting them?  The first sentence refers to 'Trap' and
> 'agent-addr' which elsewhere are used to distinguish v1 from other
> versions which makes the first sentence sound as if it is forwarding
> v1 to v1 which it then says it is not!)
> 
> s54) snmpCommunityTableGroup OBJECT-GROUP
>      "A collection of objects providing for configuration ..."
>      (suggest /objects which allow configuration/; 'provide for'
> sounds like a parent with  impecunious children)
> 
> s55) 7.  **/Acknowledgments/Acknowledgements/
> 
> s56) A.  Full Copyright Statement
> (I think the copyright notice line should appear here as well as on
> the first page).
> 
> s57) B.  Changes From RFC1908
>      "-  Added snmpCommunityMIB  ... **/paramaters/parameters/ which
> can then be used..."
> 
> Tom Petch
> [email protected]
> 
> -----Original Message-----
> From: Harrington, David <[email protected]>
> To: [email protected] (E-mail) <[email protected]>
> Date: 23 December 2002 20:24
> Subject: WG last call: Coex draft
> 
> 
> >Hi,
> >
> >I am looking for two volunteers to review the coex draft for
> non-technical stuff.
> >A URL for this Internet-Draft is:
> >http://www.ietf.org/internet-drafts/draft-ietf-snmpv3-coex-v2-02.txt
> >
> >One volunteer should check it thoroughly against RFC2223, and
> http://www.rfc-editor.org/policy.html, and
> ftp://ftp.ietf.org/ietf/1id-guidelines.txt, and
> http://www.ietf.org/ID-nits.html. There should be lots of overlap in
> these documents (and hopefully little contradiction) so it not as
> large a job as it might appear. Doing this review would be good for
> any current ot future document editors, giving you good training in
> how to write IETF documents in the preferred formats and organization.
> I am willing to have multiple volunteers check the document against a
> subset of these documents.
> >
> >One volunteer should check the language for good grammar and
> spelling. This will require more than running it through "spell" or
> MS-Word's spelling and grammar checkers.
> >
> >We so far have had one person review the document for smilint
> cleanliness. Mike, did you review the document against "Guidelines for
> MIB Authors and Reviewers" in the process?
> >
> >We need more technical review of this document. If you review the
> document (reasonably thoroughly) and find nothing to object to, please
> post a comment to the mailing list stating that you have done such a
> review.
> >
> >Any volunteers?
> >
> >Thanks,
> >dbh
> >---
> >David Harrington
> >[email protected]
> >co-chair, IETF SNMPv3 WG
> 
> 
>