Subject: [http-state] wrt definitions of "flags" and algorithms

From: =JeffH <[email-masked]>
Date: Tue, 14 Sep 2010 13:34:58 -0700

What follows is a long-winded justification for this suggested spec fixup. If 
you want to cut to the chase, jump ahead to "Suggested Fix".

Bjoern had mentioned that the "flag"s just sorta appeared out of nowhere (see 
msg below), and yeah they do, and to some folks that makes sense, but to others 
it apparently doesn't, plus one has to (reasonably) assume that upon first 
mention, the flag defaults to "not set" but the spec isn't explicit about that.

In poking thru -httpstate-cookie I note that "flag"s are used in two places -- 
the "Dates" algorithm, and in the "Storage Model". In the latter, the flags are 
introduced (declared) in the intro paragraph, so I don't think there's 
ambiguity with them.

However I think a minor explanation wrt the "flag"s is worthwhile in the intro 
para to the "5.1.1. Dates" section.

Additionally/tangentially, upon reading the spec after not having looked it for 
a bit, the title and intro to section "5.1. Algorithms" had seemed a bit 
misleading to me. It is presently..

5.1. Algorithms

    This section defines a number of algorithms used by user agents to
    process the Cookie and Set-Cookie headers.

..however the algorithms defined in 5.1 don't process the Cookie and Set-Cookie 
headers themselves, rather they are for processing subcomponents of those 
headers. The algs for processing the Cookie and Set-Cookie headers themselves 
are in separate peer sections to 5.1 (i.e. 5.2 and 5.4).

Thus I suggest we fixup both the title to 5.1 and its intro, along with the 
fixup for the Dates' "flag's".

Below is first the present 5.1/5.1.1 sections intro text, then the suggested 
fix in text and xml, and then an email msg from the prior thread where this 
issue was raised.

HTH,

=JeffH
------

Present text..

5.1. Algorithms

    This section defines a number of algorithms used by user agents to
    process the Cookie and Set-Cookie headers.

5.1.1. Dates

    The user agent MUST use an algorithm equivalent to the following
    algorithm to parse a cookie-date:

Suggested Fix (text)..

----8<----
5.1. Subcomponent Algorithms

    This section defines some algorithms used by user agents to
    process specific subcomponents of the Cookie and Set-Cookie headers.

5.1.1. Dates

    The user agent MUST use an algorithm equivalent to the following
    algorithm to parse a cookie-date. Note that various boolean flags
    are defined as a part of the algorithm and that they default to
    "not set" upon first occurrence.
---->8----

Suggested Fix (xml)..

----8<----
       <section anchor="algorithms" title="Algorithms">
         <t>This section defines some algorithms used by user agents to
         process specific subcomponents of the Cookie and
         Set-Cookie headers.</t>

         <section anchor="cookie-date" title="Dates">
           <t>The user agent MUST use an algorithm equivalent to the following
           algorithm to parse a cookie-date. Note that various boolean flags
           are defined as a part of the algorithm and that they default to
           "not set" upon first occurrence.
---->8----

applicable message..

 > Subject: Re: [http-state] Comments on draft-ietf-httpstate-cookie-08.txt
 > 	(4.1.2.2 - 5.2.6)
 > From: Adam Barth <[email-masked]>
 > Date: Fri, 28 May 2010 12:55:20 -0700
 > To: Bjoern Hoehrmann <[email-masked]>
 > Cc: [email-masked]
 >
 >> In section 5.1.1, "If the found-day-of-month flag is not set ..." Up to
 >> this point it has not been explained what this flag is. The same goes
 >> probably for all "flags". Definitions need to be added.
 >
 > They don't mean anything other than what the text says.  There's
 > nothing to define.

---

From: Adam Barth <[email-masked]>
Date: Thu, 16 Sep 2010 01:35:35 -0700

Done:

http://github.com/abarth/http-state/commit/c8def3565325f5c36ba09aea91a915676bdf59f0

Note that your XML didn't match your text.  Also, I tweaked the language a bit.

Adam

On Tue, Sep 14, 2010 at 1:34 PM, =JeffH <[email-masked]> wrote:
> What follows is a long-winded justification for this suggested spec fixup.
> If you want to cut to the chase, jump ahead to "Suggested Fix".
>
>
> Bjoern had mentioned that the "flag"s just sorta appeared out of nowhere
> (see msg below), and yeah they do, and to some folks that makes sense, but
> to others it apparently doesn't, plus one has to (reasonably) assume that
> upon first mention, the flag defaults to "not set" but the spec isn't
> explicit about that.
>
> In poking thru -httpstate-cookie I note that "flag"s are used in two places
> -- the "Dates" algorithm, and in the "Storage Model". In the latter, the
> flags are introduced (declared) in the intro paragraph, so I don't think
> there's ambiguity with them.
>
> However I think a minor explanation wrt the "flag"s is worthwhile in the
> intro para to the "5.1.1. Dates" section.
>
> Additionally/tangentially, upon reading the spec after not having looked it
> for a bit, the title and intro to section "5.1. Algorithms" had seemed a bit
> ..however the algorithms defined in 5.1 don't process the Cookie and
> Set-Cookie headers themselves, rather they are for processing subcomponents
> of those headers. The algs for processing the Cookie and Set-Cookie headers
> themselves are in separate peer sections to 5.1 (i.e. 5.2 and 5.4).
>
> _______________________________________________
> http-state mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/http-state
>