Re: iSCSI: A list of all normative sentences

["Michael J. S. Smith \(iReady\)" <msmith@iready.com>]

Julo: I just got your email that you are preparing to post 12-97. I have
a request/suggestion.

I am going through the list of MUSTs, SHOULDs, and so forth to check
they are normative (that each term is defined, and defined before it is
used for example). I use a spreadsheet and the concordance and check
each term. When I went through the list, I found one issue that was
global.

Let me use an example to illustrate this issue. Take, as our example,
the second appearance of MUST after all the MUSTs that appear in the
change material:

[Quote]
For this reason the task management command MUST carry the current CmdSN
as a marker of their position in the stream of commands.
[End quote]

Let's follow the terms and their definitions: The use of the term
command is explained in section 2.1 (we are only interested in this
explanatory section, not the definition of command, for what follows):

[Quote]
In this document "iSCSI request", "iSCSI command", request, or
(unqualified) command have the same meaning. Also, unless otherwise
specified, status, response, or numbered response have the same mean-
ing.
[End quote]

and CmdSN is defined in 2.2.2.1:

[Quote]
Commands in transit from the initiator to the target are numbered by
iSCSI; the number is carried by the iSCSI PDU as CmdSN (Command-
Sequence-Number).
[End quote]

However when we get to "the task management command", there is no
definition of task management command (search on task management
command). By using the equivalence of command and request, the reader
could deduce (carrying section 2.1 in memory) that Task Management
Command is also equivalent to Task Management Request and therefore
guess (but not through logical deduction) that: Task Management Function
Request is equivalent to Task Management Command, which is defined in
2.5.1.3

This issue (the equivalence of request, command" and "status, response")
occurs so often that it's hard to discriminate issues that are clearly
equivalent and gray areas (such as the preceding example).

One more example. Consider the MUST after the preceding example:

[Quote]
An iSCSI target MUST be able to handle at least one immediate task
management command and one immediate non-task-management iSCSI request
per connection at any time.
[End quote]

Here, in this sentence, command and iSCSI request are exactly equivalent
(by 2.1), but the sentence appears difficult to parse and possibly
implying otherwise by focusing the reader's attention on the difference
between "task management command" and "non-task-management iSCSI
request" rather than, for example, "task management command" and
"non-task-management command".

Alone these examples are trivial, but collectively they cause a
compounded problem for a reader. Is it possible to standardize on the
consistent use of request or command (not both), and the consistent use
of status or response (not both), perhaps in 12-97? Normally this type
of editorial change might happen at the final edit stage, but this issue
is holding me up in checking some of the more arcane technical issues
also.

Aloha

Mike Smith
CTO, iReady



----- Original Message -----
From: "Michael J. S. Smith (iReady)" <msmith@iready.com>
To: <hufferd@us.ibm.com>; <Julian_Satran@il.ibm.com>; <ips@ece.cmu.edu>
Cc: <msmith@iready.com>
Sent: Thursday, May 30, 2002 4:13 PM
Subject: iSCSI: A list of all normative sentences


> I wrote a Perl script to extract a list of all sentences from an
> RFC/draft that contain the normative words: MUST, SHOULD, and so on.
> Such a list seems more useful than the concordances that I have been
> sharing so far (it was actually a suggestion John made a while back).
> Parsing the text is not as easy as it sounds and I am still improving
> things. The current tool works pretty well on the text Internet
drafts,
> and is still useful on the PDF from Julo's website
>
(http://www.haifa.il.ibm.com/satran/ips/draft-ietf-ips-iscsi-12-95.pdf).
> Here (below) is the output for12-95. This information is useful (to me
> anyway) in order to focus on the areas where the draft is normative.
> I'll try and include some more useful things like section numbers and
so
> forth, but it seemed like time was of the essence to get the draft
> cleaned up going in to last call - so I included what I currently
have.
> Ignore the HTML markup (we just use that internally).
>
> Mike Smith
> CTO, iReady