RE: IPS WG Last Call: Structural Improvements

[Brian Forbes <bforbes@Brocade.COM>]

Title: RE: IPS WG Last Call: Structural Improvements

To Luben's point, since semantics is all about meaning, people who dismiss discussions as 'just arguing semantics' can't really mean what they're saying (maybe they mean 'just arguing syntax'?).  :-)

To be fair to ouor esteemed and harried editor, Julian did incorporate certain of my comments from the previous Last Call, probably to the limit of his time & patience.  And I didn't acknowledge the new work done in Section 4, which is a start.

Alas, it seems this discussion will soon be 'overcome by events'.

Brian Forbes
Brocade Communications

-----Original Message-----
From: Luben Tuikov [mailto:luben@splentec.com]
Sent: Monday, August 26, 2002 3:19 PM
To: Brian Forbes
Cc: 'Julian Satran'; ips@ece.cmu.edu
Subject: Re: IPS WG Last Call: Structural Improvements

Brian Forbes wrote:
>
> To be more specific & constructive, and to see whether there is support from
> others for these suggestions, here goes:
>
> - The topic of login needs an overview section that introduces concepts such
> as session phases, connection phases, session types, declarations vs.
> negotiations, and login stages.  Much of the terminology is introduced on
> the fly.
>

Agreed.

While the details are there and explained, presenting the ``big picture''
of the procedure would be invaluable to the uninitiated reader.

Currently a new reader in encumbered with the task of building the ``big
picture'' by just reading about the details (CSG/NSG, etc.).

> -  There are many cases where an English phrase is used as a euphemism for
> well-defined iSCSI term.  One example is the use of a phrase like 'the
> maximum length of unsolicited data negotiated during login' instead of
> 'FirstBurstLength'.  Such euphemisms might be justified early in an
> overview, before the iSCSI term has been introduced, but anywhere else it
> leaves the reader wondering.  At a minimum, euphemisms should be
> supplemented by appending the iSCSI term in parentheses, and in many cases a
> forward section reference is also in order.  It also suggests that more
> iSCSI terms should be introduced (but not necessarily defined in detail)
> earlier in the text; e.g. frequently-mentioned key names.

At this stage we can afford to get rid of euphemisms altogether. I.e.
there'd be no more changes of names at all.

If ``FirstBurstLength'' is intended, then that name should be used,
and if the reader needs to know what it is, they can always look up
its definition elsewhere in the iSCSI document.

This would make the text more robust and more clear (in my opinion).
 
> - There seem to be cases where new terminology/notation would be very
> useful.  There are many phrases of the form 'an X having the Y bit set to
> 1'; when multiples of these appear in the same sentence-and they do- parsing
> becomes difficult.  One could define a flavor of X that implies having the Y
> bit set; e.g. one could define a 'final Data-out PDU' as a PDU having the F
> bit set.

Agreed.

Defining ``final Data-x PDU'' to be equivalent to a PDU whose F bit = 1,
and then defining a sequence to end with a final Data-x PDU,
would clarify text in the sense that instead of saying:
``has to have it's F bit = 1'' one would say
``the PDU sequence'' and that's it.

If one wants to know what is meant, they'd look up ``PDU sequence'',
then ``final Data-x PDU'', etc. Clearly a structurally more sound
document.

--
Luben

P.S. Yes, indeed, semantics _do_ make a difference. And we've seen this
fact shown numerous times in the latter 20th century, contrary to
the mid-20th century fad ``It's only semantics''.