Minor patch to Sieve documentation.

[exim.git] / doc / doc-txt / README.SIEVE

diff --git a/doc/doc-txt/README.SIEVE b/doc/doc-txt/README.SIEVE
index 4d04851e16b9cebc28716ac904be6390b1febedb..b9973bc102e374b001f7960e7eeb0fcf95a91bab 100644 (file)
--- a/doc/doc-txt/README.SIEVE
+++ b/doc/doc-txt/README.SIEVE
@@ -1,4 +1,4 @@
-$Cambridge: exim/doc/doc-txt/README.SIEVE,v 1.1 2004/10/07 15:04:35 ph10 Exp $
+$Cambridge: exim/doc/doc-txt/README.SIEVE,v 1.6 2005/07/01 10:21:45 ph10 Exp $

 
               Notes on the Sieve implementation for Exim
 
 
               Notes on the Sieve implementation for Exim
 


@@ -20,9 +20,9 @@ then there is no way around it.
 
 Exim Implementation
 
 
 Exim Implementation
 

-The Exim Sieve implementation offers the core as defined by RFC 3028, the
-"envelope" (RFC 3028), the "fileinto" (RFC 3028), the "copy" (RFC 3894)
-and the "vacation" (draft-showalter-sieve-vacation-05.txt) extension,
+The Exim Sieve implementation offers the core as defined by RFC 3028bis,
+the "envelope" (RFC 3028), the "fileinto" (RFC 3028), the "copy" (RFC
+3894) and the "vacation" (draft-ietf-sieve-vacation-02.txt) extension,

 the "i;ascii-numeric" comparator, but not the "reject" extension.
 Exim does not support MDMs, so adding it just to the sieve filter makes
 little sense.
 the "i;ascii-numeric" comparator, but not the "reject" extension.
 Exim does not support MDMs, so adding it just to the sieve filter makes
 little sense.


@@ -114,13 +114,14 @@ This may be implemented in future by adding a header line to mails that
 are filed into "inbox" due to an error in the filter.
 
 
 are filed into "inbox" due to an error in the filter.
 
 

-Strings Containing Header Names
+Strings Containing Header Names Or Envelope Elements

 
 RFC 3028 does not specify what happens if a string denoting a header
 
 RFC 3028 does not specify what happens if a string denoting a header

-field does not contain a valid header name, e.g. it contains a colon.
+field or envelope element does not contain a valid name, e.g. it
+contains a colon for a header or it is not "from" or "to" for envelopes.

 This implementation generates an error instead of ignoring the header
 This implementation generates an error instead of ignoring the header

-field in order to ease script debugging, which fits in the common
-picture of Sieve.
+field in order to ease script debugging, which fits in the common picture
+of Sieve.

 
 
 Header Test With Invalid MIME Encoding In Header
 
 
 Header Test With Invalid MIME Encoding In Header


@@ -140,17 +141,6 @@ This implementation treats them literally, as it does if the word is
 correct, but its character set can not be converted to UTF-8.
 
 
 correct, but its character set can not be converted to UTF-8.
 
 

-Address Test For Multiple Addresses Per Header
-
-A header may contain multiple addresses.  RFC 3028 does not explicitly
-specify how to deal with them, but since the "address" test checks if
-anything matches anything else, matching one address suffices to
-satify the condition.  That makes it impossible to test if a header
-contains a certain set of addresses and no more, but it is more logical
-than letting the test fail if the header contains an additional address
-besides the one the test checks for.
-
-

 Semantics Of Keep
 
 The keep command is equivalent to fileinto "inbox": It saves the
 Semantics Of Keep
 
 The keep command is equivalent to fileinto "inbox": It saves the


@@ -168,30 +158,14 @@ that aspect using the appendfile transport options "create_directory",
 the Exim specification for details.
 
 
 the Exim specification for details.
 
 

-Semantics of Redirect
-
-Sieve scripts are supposed to be interoperable between servers, so this
-implementation does not allow redirecting mail to unqualified addresses,
-because the domain would depend on the used system and on systems with
-virtual mail domains it is probably not what the user expects it to be.
-
-

 String Arguments
 
 There has been confusion if the string arguments to "require" are to be
 String Arguments
 
 There has been confusion if the string arguments to "require" are to be

-matched case-sensitive or not.  This implementation matches them with
-the match type ":is" (default, see section 2.7.1) and the comparator
-"i;ascii-casemap" (default, see section 2.7.3).  The RFC defines the
-command defaults clearly, so any different implementations violate RFC
-3028.  The same is valid for comparator names, also specified as strings.
-
-
-Number Units
-
-There is a mistake in RFC 3028: The suffix G denotes gibi-, not tebibyte.
-The mistake os obvious, because RFC 3028 specifies G to denote 2^30
-(which is gibi, not tebi), and that's what this implementation uses as
-scaling factor for the suffix G.
+matched case-sensitive or not.  The comparator default is case-insensitive
+comparison, but "require" does not allow to specify a comparator, so
+this default does not apply.  Lacking a clear specification, matching
+the strings exactly makes most sense.  The same is valid for comparator
+names, also specified as strings.

 
 
 Sieve Syntax and Semantics
 
 
 Sieve Syntax and Semantics


@@ -199,13 +173,10 @@ Sieve Syntax and Semantics
 RFC 3028 confuses syntax and semantics sometimes.  It uses a generic
 grammar as syntax for actions and tests and performs many checks during
 semantic analysis.  Syntax is specified as grammar rule, semantics
 RFC 3028 confuses syntax and semantics sometimes.  It uses a generic
 grammar as syntax for actions and tests and performs many checks during
 semantic analysis.  Syntax is specified as grammar rule, semantics

-with natural language, despire the latter often talking about syntax.
+with natural language, despite the latter often talking about syntax.

 The intention was to provide a framework for the syntax that describes
 current commands as well as future extensions, and describing commands
 The intention was to provide a framework for the syntax that describes
 current commands as well as future extensions, and describing commands

-by semantics.  Since the semantic analysis is not specified by formal
-rules, it is easy to get that phase wrong, as demonstrated by the mistake
-in RFC 3028 to forbid "elsif" being followed by "elsif" (which is allowed
-in Sieve, it's just not specified correctly).
+by semantics.

 
 RFC 3028 does not define if semantic checks are strict (always treat
 unknown extensions as errors) or lazy (treat unknown extensions as error,
 
 RFC 3028 does not define if semantic checks are strict (always treat
 unknown extensions as errors) or lazy (treat unknown extensions as error,


@@ -337,22 +308,23 @@ extension.
 
   vacation-command =  "vacation" { vacation-options } <reason: string>
   vacation-options =  [":days" number]
 
   vacation-command =  "vacation" { vacation-options } <reason: string>
   vacation-options =  [":days" number]

-                      [":addresses" string-list]

                       [":subject" string]
                       [":subject" string]

+                      [":from" string]
+                      [":addresses" string-list]

                       [":mime"]
                       [":mime"]

+                      [":handle" string]

   command          =/ vacation-command
 
 
 Semantics Of ":mime"
 
   command          =/ vacation-command
 
 
 Semantics Of ":mime"
 

-RFC 3028 does not specify how strings using MIME parts are used to compose
-messages.  The vacation draft refers to RFC 3028 and does not specify it
-either.  As a result, different implementations generate different mails.
-The Exim Sieve implementation splits the reason into header and body.
-It adds the header to the mail header and uses the body as mail body.
-Be aware, that other imlementations compose a multipart structure with
-the reason as only part.  Both conform to the specification (or lack
-thereof).
+The draft does not specify how strings using MIME entities are used
+to compose messages.  As a result, different implementations generate
+different mails.  The Exim Sieve implementation splits the reason into
+header and body.  It adds the header to the mail header and uses the body
+as mail body.  Be aware, that other imlementations compose a multipart
+structure with the reason as only part.  Both conform to the specification
+(or lack thereof).

 
 
 Semantics Of Not Using ":mime"
 
 
 Semantics Of Not Using ":mime"


@@ -363,50 +335,23 @@ is not required by the vacation draft, which does not specify how
 the UTF-8 reason is processed to compose the resulting message.
 
 
 the UTF-8 reason is processed to compose the resulting message.
 
 

-Envelope Sender
-
-The vacation draft does not specify the envelope sender.  This
-implementation uses the empty envelope sender to prevent mail loops.
-
-

 Default Subject
 
 Default Subject
 

-The draft specifies that the default message subject is "Re: "
-plus the old subject, stripped by any leading "Re: " strings.
-This string is to be taken literally, unlike some software which
-matches a regular expression like "[rR][eE]: *".  Using this
-subject is dangerous, because many mailing lists verify addresses
-by sending a secret key in the subject of a message, asking to
-reply to the message for confirmation.  Using the default vacation
-subject confirms any subscription request of this kind, allowing
-to subscribe a third party to any mailing list, either to annoy
-the user or to declare spam as legitimate mail by proving to
-use opt-in.  The draft specifies to use "Re: " in front of the
-subject, but this implementation uses "Auto: ", as suggested in
-the current draft concerning automatic mail responses.
+The draft specifies that the default message subject is "Auto: " plus
+the old subject.  Using this subject is dangerous, because many mailing
+lists verify addresses by sending a secret key in the subject of a
+message, asking to reply to the message for confirmation.  Using the
+default vacation subject confirms any subscription request of this kind,
+allowing to subscribe a third party to any mailing list, either to annoy
+the user or to declare spam as legitimate mail by proving to use opt-in.

 
 
 Rate Limiting Responses
 
 
 
 Rate Limiting Responses
 

-The draft says:
-
-     Vacation responses are not just per address, but are per address
-     per vacation command.
-
-This is badly worded, because commands are not enumerated.  It meant
-to say:
-
-     Vacation responses are not just per address, but are per address
-     per reason string and per specified subject and ":mime" option.
-
-Existing implementations work that way and it makes more sense, too.
-Including the ":mime" option is mostly for correctness, as the reason
-strings with and without this option are rarely equal.
-
-This implementation hashes the reason, specified subject and ":mime"
-option and uses the hex string representation as filename within the
-"sieve_vacation_directory" to store the recipient addresses for this
-vacation parameter set.
+In absence of a handle, this implementation hashes the reason,
+":subject" option, ":mime" option and ":from" option and uses the hex
+string representation as filename within the "sieve_vacation_directory"
+to store the recipient addresses for this vacation parameter set.

 
 The draft specifies that sites may define a minimum ":days" value than 1.
 This implementation uses 1.  The maximum value MUST greater than 7,
 
 The draft specifies that sites may define a minimum ":days" value than 1.
 This implementation uses 1.  The maximum value MUST greater than 7,


@@ -423,11 +368,3 @@ Global Reply Address Blacklist
 The draft requires that each implementation offers a global black list
 of addresses that will never be replied to.  Exim offers this as option
 "never_mail" in the autoreply transport.
 The draft requires that each implementation offers a global black list
 of addresses that will never be replied to.  Exim offers this as option
 "never_mail" in the autoreply transport.

-
-
-Interaction With Other Sieve Elements
-
-The draft describes the interaction with vacation, discard, keep,
-fileinto and redirect.  It MUST describe compatibility with other
-actions, but doesn't.  In this implementation, vacation is compatible
-with any other action.