iSCSI: v9 concordance

["Michael Sebastian Smith \(Hotmail\)" <smithm007@hotmail.com>]

iSCSI: v8 concordanceI placed the concordance of the iSCSI v9 Internet draft
at http://www.iready.org/iscsi/iscsi9concordanceV1.doc

Aloha

Mike Smith
CTO
iReady

----- Original Message -----
From: Michael Smith
To: 'ips@ece.cmu.edu'
Cc: Michael Smith
Sent: Monday, October 08, 2001 5:36 PM
Subject: iSCSI: v8 concordance


There have been several comments recently on this reflector about the use of
terms and definitions in the current iSCSI Internet draft.
I have created a concordance for the iSCSI v8 Internet draft. You may
download the concordance at
http://www.iready.org/iscsi/iscsi8concordanceV5.doc
This is a very large file (10MB).
A concordance is like an amplified index. A concordance is an ordered list
of the occurence of every single word, term, and character in the iSCSI v8
spec together with it's context (the context being a certain number of words
around each occurence).
Why is this useful? Let's take an example from the iSCSI Internet draft
concordance file. Take the term "barrier". It often occurs as the term
"barrier list" in the current Internet draft. But how is this term used
exactly? First, look up "barrier (exactly as I have shown it here) in the
concordance and you will see the following:


"BARRIER................................................................5
                                                          layer.  The
"barrier list" described in the following sections is a
7370

"barrier list";
7382
                                                            a) if the
"barrier list" is empty or ExpCmdSN is less than
7392
                                                                    a
"barrier list" including the referenced LUN (or an ALL
7420
                                                            a) if the
"barrier list" is empty or ExpCmdSN is less than
7428
This means the characters "barrier appear five times (lines 7370, 7382,
7392, 7420, 7428 as numbered from the .txt version). Each time the
characters "barrier occur as "barrier list". Continue now to look up just
the characters barrier in the concordance. You will find:
BARRIER.................................................................5
                                               Note: for clarity, the
barrier list contains "items" and the
7387
                                  the CmdSN of the oldest item in the
barrier list then
7393
                                                 b) remove the oldest
barrier list item, and remove and
7395
                                               the oldest item in the
barrier list then skip to step d;
7429
                                                 b) remove the oldest
barrier list item and evaluate all
7430


Thus barrier also occurs five times (lines 7387, 7393, 7395, 7429, 7430).
So what?
The concordance has told us:
1. If the term "barrier list" is defined the first time that it is used. (It
is, sort of.)
2. If the term "barrier list" is used consistently each time.
3. That the use of quotes around barrier list is inconsistent and therefore
perhaps misleading.
I hope that, from this small example, you may easily extrapolate to other
uses of a concordance in reading, understanding, and editing the current
iSCSI Internet draft. I have found this technique useful in the past.
Aloha
Mike Smith
CTO
iReady