Subject: [sieve] I-D Action: draft-ietf-sieve-include-07.txt

From: [email-masked]
Date: Tue, 05 Jul 2011 09:47:11 -0700

A New Internet-Draft is available from the on-line Internet-Drafts directories. This draft is a work item of the Sieve Mail Filtering Language Working Group of the IETF.

	Title           : Sieve Email Filtering: Include Extension
	Author(s)       : Cyrus Daboo
                          Aaron Stone
	Filename        : draft-ietf-sieve-include-07.txt
	Pages           : 14
	Date            : 2011-07-05

   The Sieve Email Filtering &quot;include&quot; extension permits users to
   include one Sieve script inside another.  This can make managing
   large scripts or multiple sets of scripts much easier, and allows a
   site and its users to build up libraries of scripts.  Users are able
   to include their own personal scripts or site-wide scripts.

A URL for this Internet-Draft is:
http://www.ietf.org/internet-drafts/draft-ietf-sieve-include-07.txt

Internet-Drafts are also available by anonymous FTP at:
ftp://ftp.ietf.org/internet-drafts/

This Internet-Draft can be retrieved at:
ftp://ftp.ietf.org/internet-drafts/draft-ietf-sieve-include-07.txt

---

From: Aaron Stone <[email-masked]>
Date: Tue, 5 Jul 2011 09:59:17 -0700

> ftp://ftp.ietf.org/internet-drafts/draft-ietf-sieve-include-07.txt

At long last, I've updated the Include draft. Thanks to Stephan Bosch,
whose comments from many months ago I incorporated into this revision.

Cheers,
Aaron

---

From: Barry Leiba <[email-masked]>
Date: Tue, 5 Jul 2011 15:11:11 -0400

> whose comments from many months ago I incorporated into this revision.

I only have one issue with this version; the issue has existed since
the -00 version, but I guess it didn't stand out to me before:

In section 3.2, it's not clear where the first example ends, and this
text (which I don't think is part of the example) begins:
   The "include" command may appear anywhere in the script where a
   control structure is legal.

Can you see what you can do with the layout to make this clearer?  The
first example is long and has so many parts that it's hard to sort it
out.

Otherwise, I think this is ready to go.

Barry

---

From: Stephan Bosch <[email-masked]>
Date: Tue, 05 Jul 2011 21:20:38 +0200

Op 5-7-2011 18:59, Aaron Stone schreef:
> On Tue, Jul 5, 2011 at 9:47 AM,<[email-masked]>  wrote:
Ah nice :)

I have three issues still:

## ISSUE 1:

I've fed the examples to my compiler and it still finds a few familiar 
errors:

* First example starting at page 8:

spam_tests: line 6: error: the reject command requires 1 positional 
argument(s), but 0 is/are specified.
default: line 4: error: failed to validate included :global script 
'spam_tests'.

* Third example starting at page 11:

active: line 5: error: missing semicolon ';' after set command.
active: line 8: error: missing semicolon ';' after set command.
active: line 13: error: unknown command 'fileinto' (only reported once 
at first occurence).
active: error: validation failed.

When I fix those, more errors follow:

active: line 3: error: invalid variable identifier 'test-mailbox'.

And, thereafter:

spam_checks: line 2: error: invalid variable identifier 'test-mailbox'.
spam_checks: line 6: error: invalid variable name 'test-mailbox'.
active: line 6: error: failed to validate included script 'spam_checks'.

* Fifth example starting at page 13:

example5: line 9: error: expected end of command ';' or the beginning of 
a compound block '{', but found '}'.
(missing semicolon after vacation command)

## ISSUE 2:

While I was working on this, I thought of something that is not 
explicitly addressed in the document (correct me if I'm wrong). 
Initially I had forgotten to check for the validity of the global 
command's value argument and now I am wondering: what is the exact 
syntax of that argument? Logic dictates that this is simply an 
'identifier' as used in RFC5229 and defined in RFC5228, since only 
simple variables make any sense. I can imagine though that at some point 
more namespaces are defined by new extensions and some people may assume 
that the variable name in the value argument can have a namespace prefix 
as defined in RFC5229. Some may even allow to make match values global. 
This would make the following script legal:

require "include";
require "variables";
require "frop";   # This jolly extension defines a new (writable) 
namespace called 'frop'

global "normal";
global "frop.abnormal";

global "0";
if header :matches "from" "*" {  }

Something similar is true for the global namespace:

set "global.frop.abnormal" "Frop!";
set "global.0" "Friep!";

Although the above is pretty far-fetched and stupid, I think it is 
better when this is excluded explicitly by stating the argument's exact 
syntax instead of calling it only a 'variable name' (much like Section 4 
in RFC5229). Also the syntax of the sub-items of the global namespace 
should be defined explicitly.

## 'ISSUE' 3:

I've had a few request and questions from users about having an optional 
include, i.e. an include directive that is skipped without error if (and 
only if) the to-be-included script does not exist. Do you find this a 
useful feature? If yes, is it possible to add this to the main draft now 
or should there be an 'include-optional' extension that adds an 
':optional' tag to the include command?

Regards,

Stephan.

---

From: Aaron Stone <[email-masked]>
Date: Thu, 7 Jul 2011 23:57:21 -0700

Uploaded -08 with these changes, thank you!

On Tue, Jul 5, 2011 at 12:20 PM, Stephan Bosch <[email-masked]> wrote:
> active: line 13: error: unknown command 'fileinto' (only reported once at
> first occurence).
> example5: line 9: error: expected end of command ';' or the beginning of a
> compound block '{', but found '}'.
> While I was working on this, I thought of something that is not explicitly
> addressed in the document (correct me if I'm wrong). Initially I had
> forgotten to check for the validity of the global command's value argument
> and now I am wondering: what is the exact syntax of that argument? Logic
> dictates that this is simply an 'identifier' as used in RFC5229 and defined
> in RFC5228, since only simple variables make any sense. I can imagine though
> that at some point more namespaces are defined by new extensions and some
> people may assume that the variable name in the value argument can have a
> namespace prefix as defined in RFC5229. Some may even allow to make match
> values global. This would make the following script legal:
>
> require "include";
> require "variables";
> require "frop";   # This jolly extension defines a new (writable) namespace
> called 'frop'
>
> global "normal";
> global "frop.abnormal";
>
> global "0";
> Although the above is pretty far-fetched and stupid, I think it is better
> when this is excluded explicitly by stating the argument's exact syntax
> instead of calling it only a 'variable name' (much like Section 4 in
> RFC5229).

Is this the paragraph that needs work?

   A variable has global scope in all scripts that have declared it with
   the "global" command.  If a script uses that variable name without
   declaring it global, the name specifies a separate, non-global
   variable within that script.

Yeah, that's not terribly concise. I'm struggling a bit to find clear
language for this.

> Also the syntax of the sub-items of the global namespace should be
> defined explicitly.

I'm not sure what you mean here.

> only if) the to-be-included script does not exist. Do you find this a useful
> feature? If yes, is it possible to add this to the main draft now or should
> there be an 'include-optional' extension that adds an ':optional' tag to the
> include command?

Oh, huh. I suppose at least a hack around this would be an empty script?

Aaron

---

From: Aaron Stone <[email-masked]>
Date: Thu, 7 Jul 2011 23:57:52 -0700

Uploaded -08 with this text moved and (hopefully) clarified.

---

From: Barry Leiba <[email-masked]>
Date: Fri, 8 Jul 2011 08:38:23 -0400

> Uploaded -08 with this text moved and (hopefully) clarified.

Looks good.  Cyrus, is it time to do a brief WGLC and send this to the IESG?

Barry

---

From: Cyrus Daboo <[email-masked]>
Date: Fri, 08 Jul 2011 10:52:58 -0400

Hi Barry,

> Looks good.  Cyrus, is it time to do a brief WGLC and send this to the

Yes please.

-- 
Cyrus Daboo

---

From: Stephan Bosch <[email-masked]>
Date: Fri, 08 Jul 2011 17:45:33 +0200

Op 8-7-2011 8:57, Aaron Stone schreef:
> On Tue, Jul 5, 2011 at 12:20 PM, Stephan Bosch<[email-masked]>  wrote:
>> ## ISSUE 2:
>>
>> in RFC5228, since only simple variables make any sense.
[...]
>     variable within that script.

No, I would think the first paragraph of Section 3.4.1. is the best 
place to mention this:

    The "global" command contains a string list argument that defines one
    or more names of variables to be stored in the global variable space.

'Names of variables' is in my opinion a bit too vague.  As an example, 
the "set" command specified in Section 4 of RFC 5229 defines the following:

    The "set" action stores the specified value in the variable
    identified by name.  The name MUST be a constant string and conform
    to the syntax of variable-name.  Match variables cannot be set.  A
    namespace cannot be used unless an extension explicitly allows its
    use in "set".  An invalid name MUST be detected as a syntax error.

I would change the first paragraph as follows:

    The "global" command has a string list argument that defines one
    or more names of variables to be stored in the global variable space.
    Each name MUST be a constant string and conform to the syntax of
    variable-name as defined in [RFC5229], Section 3. Match variables
    cannot be specified and namespace prefixes are not allowed. An invalid
    name MUST be detected as a syntax error.

(I didn't even consider the constant string part until just now)

> I'm not sure what you mean here.

Basically the same restrictions apply in this case. The paragraph 
directly after the example in Section 3.4.2 states:

   Variables declared global and variables accessed via the global
   namespace MUST be one and the same.

Similar to the global command, you can add here that the "global" 
namespace has no sub-namespaces (e.g. set "global.data.from" 
"[email-masked]"; is not allowed ) and that the variable-name part is 
always an identifier (so set "global.12" "whatever"; is not allowed).

> Oh, huh. I suppose at least a hack around this would be an empty script?

Yes, but that will not be adequate in many situations. Do more people 
have thoughts on this?

Regards,

Stephan.

---

From: Barry Leiba <[email-masked]>
Date: Fri, 8 Jul 2011 13:22:53 -0400

>>> useful
> Yes, but that will not be adequate in many situations. Do more people have
> thoughts on this?

I would support an ":optional" tag on "include", which would cause an
error NOT to be generated if the included script doesn't exist.  That
should be an easy change to the text, and an easy thing for
implementors to do.

Barry

---

From: Aaron Stone <[email-masked]>
Date: Fri, 8 Jul 2011 10:51:23 -0700

On Fri, Jul 8, 2011 at 8:45 AM, Stephan Bosch <[email-masked]> wrote:
>>> explicitly
> No, I would think the first paragraph of Section 3.4.1. is the best place to
> mention this:
>
> 'Names of variables' is in my opinion a bit too vague.  As an example, the
> "set" command specified in Section 4 of RFC 5229 defines the following:
>
> Basically the same restrictions apply in this case. The paragraph directly
> after the example in Section 3.4.2 states:
>
> Similar to the global command, you can add here that the "global" namespace
> has no sub-namespaces (e.g. set "global.data.from" "[email-masked]"; is not
> allowed ) and that the variable-name part is always an identifier (so set
> "global.12" "whatever"; is not allowed).

Great language. Posting -09 now.

---

From: Aaron Stone <[email-masked]>
Date: Fri, 8 Jul 2011 10:52:13 -0700

> should be an easy change to the text, and an easy thing for

Any objections?

---

From: Alexey Melnikov <[email-masked]>
Date: Sat, 09 Jul 2011 16:42:46 +0100

>should be an easy change to the text, and an easy thing for
+1. I would like to see this being added as well.

---

From: Aaron Stone <[email-masked]>
Date: Sun, 10 Jul 2011 19:33:04 -0700

On Sat, Jul 9, 2011 at 8:42 AM, Alexey Melnikov
<[email-masked]> wrote:
>>>>> there be an 'include-optional' extension that adds an ':optional' tag
>>>>> to
>>>>> the
>>>>> include command?
>>>>>
>>>>
>>> have

Here's the language I came up with, and updated ABNF. I realized that
the way the ABNF was currently written, the tagged parameters to
include had a specific order. I don't think this was intentional, but
was just an artifact of there having been only one parameter when the
ABNF was first written.

=== OLD ===

3.2.  Control Structure include

         Usage:   include [LOCATION] [ONCE] <value: string>
               LOCATION = ":personal" / ":global"
               ONCE = ":once"

...

   The "location" parameter MUST default to ":personal" if not
   specified.  The "location" has the following meanings:

=== NEW ===

3.2.  Control Structure include

         Usage:   include *[PARAMETERS] <value: string>
                       PARAMETERS = LOCATION / :once / :optional
                       LOCATION = :personal / :global
...

   The "location" parameter MUST default to ":personal" if not
   specified.  The "location" parameter MUST NOT be specified more than
   once.  The "location" has the following meanings:

...

   The ":optional" parameter indicates that the script may be missing.
   Ordinarily, an implementation MUST generate an error at runtime if an
   include command specifies a script that does not exist.  When
   ":optional" is specified, implementations MUST NOT generate an error
   for a missing script, and MUST continue as if the include command had
   not been present.

I realize that the new ABNF allows more than one location parameter to
by syntactically valid, so I added text that it cannot be specified
more than once. I hope that's reasonable; if not, better ABNF is
welcome.

Given that the pre-meeting embargo begins at 17:00 Pacific time on
Monday (tomorrow), I'm going to post the text above now, and we can
discuss the details during the week.

Cheers,
Aaron

---

From: Barry Leiba <[email-masked]>
Date: Sun, 10 Jul 2011 22:39:30 -0400

> more than once. I hope that's reasonable; if not, better ABNF is

WFM.

Barry

---

From: Stephan Bosch <[email-masked]>
Date: Tue, 12 Jul 2011 12:36:22 +0200

Hi Aaron,

> was just an artifact of there having been only one parameter when the 

 From RFC 5228, Section 2.6.2 "Tagged Arguments":

Tagged arguments must appear before positional arguments, but they
may appear in any order with other tagged arguments.  For simplicity
of the specification, this is not expressed in the syntax definitions
with commands, but they still may be reordered arbitrarily provided
they appear before positional arguments.  Tagged arguments may be
mixed with optional arguments.

Since you import the conventions from RFC 5228 in Section 2, this 
applies to this document as well.

> more than once. I hope that's reasonable; if not, better ABNF is

I would just stick to a nice and brief version of what you had earlier:

Usage:   include [LOCATION] [":once"] [":optional"]<value: string>

(I believe the double quotes around the tagged arguments are mandatory. 
These are missing in your last version.).

One other thing:

Just after the new text for :optional there is a paragraph with a notice 
about the recommended application of :once, which now seems to regard 
the :optional tag. I don't think this is intentional and this paragraph 
should be moved above the new paragraph about :optional.

Regards,

Stephan.

---

From: Aaron Stone <[email-masked]>
Date: Tue, 12 Jul 2011 11:46:50 -0700

Thanks! I'll post a rev with these changes right after the meeting embargo.

In the mean time, shall we make a Last Call for this document?

On Tue, Jul 12, 2011 at 3:36 AM, Stephan Bosch <[email-masked]> wrote:
>> Here's the language I came up with, and updated ABNF. I realized that the
>> way the ABNF was currently written, the tagged parameters to include had a
>> specific order. I don't think this was intentional, but was just an artifact
>> of there having been only one parameter when the ABNF was first written.
>
> Since you import the conventions from RFC 5228 in Section 2, this applies to
> this document as well.
>
> about the recommended application of :once, which now seems to regard the
> :optional tag. I don't think this is intentional and this paragraph should
> be moved above the new paragraph about :optional.
>
> Regards,
>
> Stephan.
>
>
>