Subject: [sipcore] Style of section 1 in info-events

From: "Elwell, John" <[email-masked]>
Date: Wed, 21 Oct 2009 14:50:02 +0200

Section 1 says what RFC 2976 does, says what its drawbacks are, and then says that this document describes a mechanism that addresses those drawbacks. It does not state that this document defines the INFO method. It even refers back to RFC 2976 for the definition of the INFO method ("The purpose of the INFO message [RFC2976] is.... ").

Yet this document supposedly obsoletes RFC 2976.

I would have expected the introduction to a document that obsoletes an earlier RFC to be self-standing and structured more like the following:
- Introductory text very similar to what is in the obsoleted RFC, but modified to mention anything that is significantly different.
- A reference back to the obsoleted RFC, describing what has changed.

In this particular case, the text of RFC 2976 is a rough starting point. It even says, near the end, that the document does not specify specific uses, so that is an ideal point to continue and talk about usages, Info-Packages, and indicating supported usages.

We could then continue by saying that the document obsoletes RFC 2976, which did not define the Info-Package concept and explicit indications of which usages are supported.

John

---

From: "Christer Holmberg" <[email-masked]>
Date: Wed, 21 Oct 2009 21:26:30 +0200

Hi, 

>Section 1 says what RFC 2976 does, says what its drawbacks are, and
then says that this document describes a mechanism that addresses those
drawbacks. It does not state that this document defines the 
>INFO method. It even refers back to RFC 2976 for the definition of the
INFO method ("The purpose of the INFO message [RFC2976] is.... ").
>I would have expected the introduction to a document that obsoletes an
earlier RFC to be self-standing and structured more like the following:
>- Introductory text very similar to what is in the obsoleted RFC, but
modified to mention anything that is significantly different.
>In this particular case, the text of RFC 2976 is a rough starting
point. It even says, near the end, that the document does not specify
specific uses, so that is an ideal point to continue and talk about 
>usages, Info-Packages, and indicating supported usages.
>
>We could then continue by saying that the document obsoletes RFC 2976,
which did not define the Info-Package concept and explicit indications
of which usages are supported.

I agree that we may refer/depend a little too much on RFC 2976 - and I
think Robert commented on the same issue. It is probably some text which
was useful during the justficiation phase, but should be changes.

Basically we should only refer to 2976 when we talk about legacy INFO
usage, and when we talk about the drawbacks of legacy INFO usage.

Below is a re-write of the introduction, which I think addresses your
issue. 

(We could of course discuss whether 1.2 and 1.3 really should be in the
introduction, or be moved to other places in the spec.)

"1.  Introduction

1.1 General

   This document defines a new method, INFO, for the Session Initiation
Protocol (SIP) [RFC2976]. 
   In addition, it defines an Info Package mechanism. An Info Package
defines the content and semantics of the 
   information carried in an INFO message associated with the Info
Package.
   The Info Package mechanism also provides a way for UAs to indicate
for 
   which types of applications and contexts they are willing to receive
INFO requests. The
   document defines how the INFO method is used, new SIP header fields
for the
   INFO method, and how to transport payload information associated with
an Info Package
   using INFO requests. 
  
   The purpose of the INFO message is to carry application
   level information between endpoints, using the SIP session signaling
   path. Note that the INFO method is not used to update
   characteristics of the SIP session, but to allow the applications
   which use the SIP session to exchange information.

   The Info Package mechanism does not define a separate dialog usage.
   INFO messages are always part of, and share the fate of, an invite
   dialog usage. INFO messages cannot be sent as part of other dialog
   usages.

   If a UA supports the Info Package mechanism, it uses the Recv-Info
   header field, on a per-dialog basis, to indicate for which Info
Packages
   it is willing to receive INFO requests.  A UA can indicate a new set
of Info
   Packages at any time during the lifetime of the invite dialog usage.
   A UA can use a "nil" value to indicate that it is not willing to
   receive any Info Packages at a certain moment, but that the UA still
   supports the Info Package mechanism.

   When a UA sends an INFO request, it uses the Info-Package header
   field to indicate which Info Package is associated with the request.
One particular INFO
   request can only be associated with a single Info Package.

   This document obosoletes [RFC2976]. However, for backward compability
it allows
   to use INFO per [RFC2976], referred to as legacy INFO usage in the
document.

1.2  Problems with leagcy INFO usage

   While legacy INFO usage [RFC2976] has been widely adopted for
specific
   application use cases, such as ISUP and DTMF exchange, [RFC2976] does
not
   not define a mechanisms for SIP UAs to indicate for which types of
applications and contexts they
   support the INFO method.what usages of INFO. In addition, [RFC2976]
does not provide a mechanism to
   explicitly indicate the type of application and context for which a
specific INFO message is associated to.
   In some cases it can be determined by the INFO message body payload
content, but not in a general way.

   Example: If the Content-Type is "image/jpeg", the MIME-attached
   content is a JPEG image.  Still, there are many useful ways a UA can
   render an image.  The image could be a caller-id picture, a contact
   icon, a photo for sharing, and so on.  The sender does not know which
   image to send to the receiver if the receiver supports an image
   content type.  Likewise, the receiver does not know the context of an
   image the client is sending if the receiver supports receiving more
   than one image content type.

   Due to the problems described above, legacy INFO usages often require
   static configuration about for what type of applications and contexts
UAs support the INFO method, 
   and the way they handle application information transported in INFO
messages.
   That has caused interoperability problems in the industry.
Therefore,a need for a well defined and
   documented description of what the information sent in the INFO is
   used for has been identified. This situation is analogous to the
context issue in
   Internet Mail [RFC3458].

1.3  Relationship to subscription-based event

   Event Packages [RFC3265] perform the role of disambiguating the
   context of a message for subscription-based events.  The Info Package
   mechanism provides similar functionality for application information
   exchange using invite dialog usages [RFC5057]. However, there is no
formal
   relationship between the Info Package mechanism and the
subscription-based event
   mechanism."

Regards,

Christer

---

From: "Elwell, John" <[email-masked]>
Date: Wed, 21 Oct 2009 21:47:27 +0200

Christer,

This seems a lot better. A few specific comments embedded. I would keep 1.2 and 1.3 here, unless there is an obvious alternative place for one or both of them.

> -----Original Message-----
> From: Christer Holmberg [mailto:[email-masked]] 
> Sent: 21 October 2009 20:27
> To: Elwell, John; SIPCORE
> Subject: WGLC (draft-ietf-sipcore-info-events) - Style of 
> section 1 in info-events
> 
> 
> Hi, 
> 
[JRE] I think this ought to come earlier, after the very first sentence, before we start talking about Info Packages.

>    The Info Package mechanism does not define a separate dialog usage.
[JRE] I would prefer "Use of the INFO method does not constitute a separate dialog usage".

>    If a UA supports the Info Package mechanism, it uses the Recv-Info
[JRE] Any UA supporting this RFC must support the Info Package mechanism, so we can shorten this to "A UA uses the Recv-Info..."

>    Packages at any time during the lifetime of the invite 
[JRE] Perhaps being rather pedantic, but shouldn't we say "A UA can indicate an initial set of Info Packages during dialog establishment and can indicate a new set..."?

>    support the INFO method.what usages of INFO. In addition, [RFC2976]
[JRE] Change "mechanisms" to "mechanism". Also I think the words "what usages of INFO" should have been deleted.

John

---

From: "Christer Holmberg" <[email-masked]>
Date: Wed, 21 Oct 2009 22:23:10 +0200

Hi,

In general I am ok with your comments, so I will implement them.

One thing, though, regarding your comment saying: 

"[JRE] Perhaps being rather pedantic, but shouldn't we say "A UA can
indicate an initial set of Info Packages during dialog establishment and
can indicate a new set..."?"

I don't think the UA needs to indicate anything during dialog
establishment - it can indicate the initial set also during the dialog.
Well, it does need to include Recv-Info header field during dialog
establishment, but the header value could be 'nil'.

But, it's just editorial, so I'll try to come up with something.

Regarding 1.2, the check-out-other-alternatives-before-you-define-an-I-P
of course already describes subscription-based events, so I am not sure
we need the text at all. But, I am ok with keeping it in the
introduction.

Regarding 1.3, I was thinking that it could be added to the Legacy INFO
usage section later in the document, and the introduction could simply
refer to it. But, I have no strong feelings on that.

Regards,

Christer

-----Original Message-----
From: Elwell, John [mailto:[email-masked]] 
Sent: 21. lokakuuta 2009 22:47
To: Christer Holmberg; SIPCORE
Subject: RE: WGLC (draft-ietf-sipcore-info-events) - Style of section 1
in info-events

Christer,

This seems a lot better. A few specific comments embedded. I would keep
1.2 and 1.3 here, unless there is an obvious alternative place for one
or both of them.

> Subject: WGLC (draft-ietf-sipcore-info-events) - Style of section 1 in

> info-events
> then says that this document describes a mechanism that addresses 
> those drawbacks. It does not state that this document defines the

> think Robert commented on the same issue. It is probably some text 
> which was useful during the justficiation phase, but should be 
> changes.
> 
> (We could of course discuss whether 1.2 and 1.3 really should be in 
> the introduction, or be moved to other places in the spec.)
> 
> "1.  Introduction
> 
> 1.1 General
> 
>    This document defines a new method, INFO, for the Session 
> Initiation Protocol (SIP) [RFC2976].
>    which types of applications and contexts they are willing to 
> receive INFO requests. The

> for the
>    INFO method, and how to transport payload information associated 
> with an Info Package
>    using INFO requests. 
>   
[JRE] I think this ought to come earlier, after the very first sentence,
before we start talking about Info Packages.

>    The Info Package mechanism does not define a separate dialog usage.
[JRE] I would prefer "Use of the INFO method does not constitute a
separate dialog usage".

>    If a UA supports the Info Package mechanism, it uses the Recv-Info
[JRE] Any UA supporting this RFC must support the Info Package
mechanism, so we can shorten this to "A UA uses the Recv-Info..."

>    it is willing to receive INFO requests.  A UA can indicate a new 
> set of Info
[JRE] Perhaps being rather pedantic, but shouldn't we say "A UA can
indicate an initial set of Info Packages during dialog establishment and
can indicate a new set..."?

>    support the INFO method.what usages of INFO. In addition, [RFC2976]
[JRE] Change "mechanisms" to "mechanism". Also I think the words "what
usages of INFO" should have been deleted.

John

---

From: Paul Kyzivat <[email-masked]>
Date: Wed, 21 Oct 2009 20:14:06 -0400

This is good. Some specific suggestions below.

	Thanks,
	Paul

> usage, and when we talk about the drawbacks of legacy INFO usage.

IMO it should only be referenced informatively, not normatively. And as 
such it should not be necessary to reference it *at all* to build an 
implementation that supports legacy behavior.

> Protocol (SIP) [RFC2976]. 

Why the rfc ref there? *THIS* document is the new definition of the INFO 
method.

>    to use INFO per [RFC2976], referred to as legacy INFO usage in the

However, for backward compatibility it specifies a "legacy" mode of 
usage of the INFO method that is compatible with the usage previously 
defined in RFC2976.

> specific INFO message is associated to.

I'm ok with the above, except that I think it should always refer to 
RFC2976 in the past tense, since it is obsoleted by this document. I.e.

   While legacy INFO usage [RFC2976] was widely adopted for specific
   application use cases, such as ISUP and DTMF exchange, [RFC2976] did
   not define a mechanism for SIP UAs to indicate which types of
   applications and contexts support the INFO method. In addition,
   [RFC2976] did not provide a mechanism to explicitly indicate the type
   of application and context for which a specific INFO message is
   associated.

> _______________________________________________
> sipcore mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/sipcore
>

---

From: "Christer Holmberg" <[email-masked]>
Date: Thu, 22 Oct 2009 07:27:19 +0200

Hi, 

>IMO it should only be referenced informatively, not 
>normatively. And as such it should not be necessary to 
>reference it *at all* to build an implementation that 
>supports legacy behavior.

I have removed lots of references to 2976. It is now only used when
talking about legacy INFO usage.

>Why the rfc ref there? *THIS* document is the new definition of the
INFO method.

It should be [RFC3261].

>>field to indicate which Info Package is associated with 
>>the request. One particular INFO request can only be associated with a
single Info Package.
it allows
document.
> 
>However, for backward compatibility it specifies a "legacy" 
>mode of usage of the INFO method that is compatible with the 
>usage previously defined in RFC2976.

Looks ok.

>>specific application use cases, such as ISUP and DTMF exchange,
[RFC2976] 
>>does not not define a mechanisms for SIP UAs to indicate for 
>>which types of applications and contexts they
>>does not provide a mechanism to explicitly indicate the type of
application and context 
>>for which a specific INFO message is associated to.
> 
>RFC2976 in the past tense, since it is obsoleted by this 
>document.

I agree. However, I would still prefer to say "has been widely adopted",
rather than "was adopted".

"was" sounds like it was done at some point, but not anymore :)

--------------------------------------

New try :) I have tried to implement both Paul's and John's comments.

"1.  Introduction
 
1.1 General
 
This document defines a new method, INFO, for the Session 
Initiation Protocol (SIP) [RFC3261].

The purpose of the INFO message is to carry application
level information between endpoints, using the SIP session 
signaling path. Note that the INFO method is not used to update
characteristics of the SIP session, but to allow the applications
which use the SIP session to exchange information (which may
update the state of those applications).

In addition, this document also defines an Info Package mechanism. An 
Info Package defines the content and semantics of the
iformation carried in an INFO message associated with the Info Package.
The Info Package mechanism also provides a way for UAs to indicate 
for which types of applications and contexts they are willing to receive
INFO requests. The
document defines how the INFO method is used, new SIP header fields 
for the INFO method, and how to transport payload information associated

with an Info Package using INFO requests. 
   
Use of the INFO method does not constitute a separate dialog usage.
INFO messages are always part of, and share the fate of, 
an invite dialog usage. INFO messages cannot be sent as part of 
other dialog usages.
 
A UA uses the Recv-Info header field, on a per-dialog basis, to indicate
for which Info 
Packages it is willing to receive INFO requests. A UA can indicate an
initial set of Info Packages during dialog 
establishment and can indicate a new set during the lifetime of the
invite dialog usage. 

A UA can use a "nil" header field value to indicate that it is not
willing to
receive INFO requests associated with any Info Packages at a certain
moment, but that 
the UA still supports the Info Package mechanism.
 
When a UA sends an INFO request, it uses the Info-Package header
field to indicate which Info Package is associated with 
the request. One particular INFO request can only be associated with a
single Info Package.
 
This document obosoletes [RFC2976]. However, for backward compatibility
it specifies a "legacy" 
mode of usage of the INFO method that is compatible with the usage
previously defined in [RFC2976], 
referred to as "legacy INFO Usage" in this document.

While legacy INFO usage [RFC2976] has been widely adopted for specific

Example: If the Content-Type is "image/jpeg", the MIME-attached
content is a JPEG image.  Still, there are many useful 
ways a UA can render an image.  The image could be a caller-id 
picture, a contact icon, a photo for sharing, and so on.  The sender
does not 
know which image to send to the receiver if the receiver supports an
image
content type.  Likewise, the receiver does not know the context of an
image the client is sending if the receiver supports 
receiving more than one image content type.
 
Due to the problems described above, legacy INFO usages often require
static configuration about for what type of applications and contexts
UAs support the INFO method, and the way they handle application
information 
transported in INFO messages.
That has caused interoperability problems in the industry.
Therefore,a need for a well defined and documented description of what
the information sent in 
the INFO is used for has been identified. This situation is analogous to
the
context issue in Internet Mail [RFC3458].

Event Packages [RFC3265] perform the role of disambiguating the
context of a message for subscription-based events.  The 
Info Package mechanism provides similar functionality for application 
information exchange using invite dialog usages [RFC5057]. However, 
there is no formal relationship between the Info Package mechanism and
the
subscription-based event mechanism."

Regards,

Christer

---

From: "Elwell, John" <[email-masked]>
Date: Thu, 22 Oct 2009 08:11:52 +0200

> Sent: 21 October 2009 21:23
> Subject: RE: WGLC (draft-ietf-sipcore-info-events) - Style of 
> section 1 in info-events
> 
> 
> Hi,
> 
[JRE] Agreed my words don't quite capture everything. But what was missing originally was any mention of a possibility of doing it during dialog establishment. Basically we need to say that a UA can indicate an initial set of Info Packages during dialog establishment or mid-dialog, and can also indicate a revised set mid-dialog.

> Regarding 1.2, the 
> check-out-other-alternatives-before-you-define-an-I-P
[JRE] Since I don't particularly like long Intro sections, then if you can remove or find better homes for these sub-sections, go ahead. Of course, if there is no 1.2 or 1.3, we shouldn't have a 1.1.

John

> section 1 in
> > signaling
> an invite
> > the request.
> > ways a UA can
> > Info Package

---

From: "Elwell, John" <[email-masked]>
Date: Thu, 22 Oct 2009 08:30:11 +0200

Christer,

Looking good. Just a couple of nits below. 

> Sent: 22 October 2009 06:27
> To: Paul Kyzivat
> Cc: Elwell, John; SIPCORE
> Subject: RE: [sipcore] WGLC (draft-ietf-sipcore-info-events) 
> - Style of section 1 in info-events
> 
> 
> Hi, 
> 
[JRE] I would change "associated with the INFO package" (which is a little bit circular) to "for a particular usage".

> for the INFO method, and how to transport payload information 
> associated with an Info Package using INFO requests. 
[JRE] Change "The document" to "This document". And since the sentence is not specifically talking about the Info Package mechanism, it should be preceded by a paragraph break.

John

---

From: "Christer Holmberg" <[email-masked]>
Date: Thu, 22 Oct 2009 09:17:45 +0200

Hi, 

>>Info Package defines the content and semantics of the information 
>>carried in an INFO message associated with the Info Package.
>[JRE] I would change "associated with the INFO package" 
>(which is a little bit circular) to "for a particular usage".

I think the "associated with" wording is used elsewhere in the document
also, so I would prefer to keep it.

And, I thought we wanted go get rid of the "usage" wording with INFO,
unless
We talk about legacy INFO usage.

I will implement the rest of you comments.

Regards,

Christer

---

From: "Elwell, John" <[email-masked]>
Date: Thu, 22 Oct 2009 09:28:47 +0200

> Sent: 22 October 2009 08:18
> To: Elwell, John; Paul Kyzivat
> Cc: SIPCORE
[JRE] I still think your text proposal is circular: "Info package defines ....associated with the Info Package". The was the main point of my comment. Perhaps circular is a little unfair. However, I do think it is worth saying that the data is for a particular purpose (i.e., for some usage or application) - the Info Package is only a means to an end. If you want to keep "associated with" and don't want to use the word "usage", I would say "...associated with a given application".

> We talk about legacy INFO usage.
[JRE] That was not the point I was making earlier. I am comfortable with an Info package defining a usage, but there was some text somewhere that used usage in some other context, and that was what I was concerned about.

I think we are getting to the point where we need a new draft, which presumably you intend to do before the cut-off (despite the hard time Paul and I are giving you).

John

---

From: "Christer Holmberg" <[email-masked]>
Date: Thu, 22 Oct 2009 09:33:43 +0200

Hi,

Yes, my intention is to submit a new draft very soon - maybe already
today.

Regards,

Christer

> Sent: 22. lokakuuta 2009 10:29
> To: Christer Holmberg; Paul Kyzivat
> Cc: SIPCORE
> > I think the "associated with" wording is used elsewhere in the 
> > document also, so I would prefer to keep it.
> [JRE] I still think your text proposal is circular: "Info 
> package defines ....associated with the Info Package". The 
> was the main point of my comment. Perhaps circular is a 
> little unfair. However, I do think it is worth saying that 
> the data is for a particular purpose (i.e., for some usage or 
> application) - the Info Package is only a means to an end. If 
> you want to keep "associated with" and don't want to use the 
> word "usage", I would say "...associated with a given application".
> 
> > 
> > unless We talk about legacy INFO usage.
> [JRE] That was not the point I was making earlier. I am 
> comfortable with an Info package defining a usage, but there 
> was some text somewhere that used usage in some other 
> context, and that was what I was concerned about.
> 
> I think we are getting to the point where we need a new 
> draft, which presumably you intend to do before the cut-off 
> (despite the hard time Paul and I are giving you).
> 
> John
> 
> 
> >

---

From: "Christer Holmberg" <[email-masked]>
Date: Thu, 22 Oct 2009 10:07:25 +0200

Hi,

>word "usage", I would say "...associated with a given application".

What about:

"The Info Package SPECIFICAITION defines defines the content blah blah
blah associated with the Info Package".

Regards,

Christer

---

From: Paul Kyzivat <[email-masked]>
Date: Thu, 22 Oct 2009 09:41:20 -0400

I like the new wording. I also support the change John proposes here. I 
didn't pick up on it myself, but since John pointed it out I agree that 
the circularity is problematic, and his wording fixes it.

	Thanks,
	Paul

Regarding "associated with", on other threads we seem to be having 
trouble with that.

---

From: "Christer Holmberg" <[email-masked]>
Date: Thu, 22 Oct 2009 18:20:29 +0200

Hi,

I changed the wording to "An Info Package *specification* defines the
content and semantics of the iformation carried in an INFO message
associated with the Info Package", and John told me he was ok with it.

Also, I've removed 1.2 and 1.3, and moved the text into other places of
the specifcation.

I am preparing a new version of the draft, and I will submit it soon
(today, if I get everything done). We still have an open issue regarding
the C-D stuff, but due to the amount of comments and changes since the
previous version I think it is good to base comments etc on a new
version. It will also be easier for others to follow the discussions.

Regards,

Christer

-----Original Message-----
From: Paul Kyzivat [mailto:[email-masked]] 
Sent: 22. lokakuuta 2009 16:41
To: Elwell, John
Cc: Christer Holmberg; SIPCORE
Subject: Re: [sipcore] WGLC (draft-ietf-sipcore-info-events) - Style of
section 1 in info-events

	Thanks,
	Paul

Elwell, John wrote:
>>> IMO it should only be referenced informatively, not normatively. And

>>> as such it should not be necessary to reference it *at all* to build

>>> an implementation that supports legacy behavior.
>>>> field to indicate which Info Package is associated with the 
>>>> request. One particular INFO request can only be
>> associated with a
>> single Info Package.
>>> previously defined in RFC2976.
>> Looks ok.
>>
>>>> does not not define a mechanisms for SIP UAs to indicate for which 
>>>> types of applications and contexts they support the INFO 
>>>> method.what usages of INFO. In addition, [RFC2976] does not provide

>>>> a mechanism to explicitly indicate the type of
>> application and context
>>> RFC2976 in the past tense, since it is obsoleted by this document.
>> I agree. However, I would still prefer to say "has been widely 
>> adopted", rather than "was adopted".
>>
>> Protocol (SIP) [RFC3261].
>>
>> The purpose of the INFO message is to carry application level 
>> information between endpoints, using the SIP session signaling path. 
>> Note that the INFO method is not used to update characteristics of 
>> the SIP session, but to allow the applications which use the SIP 
>> session to exchange information (which may update the state of those 
>> applications).
>>

>> Info Package defines the content and semantics of the iformation 
> [JRE] I would change "associated with the INFO package" (which is a
little bit circular) to "for a particular usage".
> [JRE] Change "The document" to "This document". And since the sentence
is not specifically talking about the Info Package mechanism, it should
be preceded by a paragraph break.
specific

---

From: Paul Kyzivat <[email-masked]>
Date: Thu, 22 Oct 2009 12:31:02 -0400

sounds good.