Missing BOOL in function heading in filtertest.c; removed an email
[exim.git] / doc / doc-txt / README.SIEVE
index 0622dc906dd5abf334b75e67fd0fdbced954f985..b9973bc102e374b001f7960e7eeb0fcf95a91bab 100644 (file)
@@ -1,4 +1,4 @@
-$Cambridge: exim/doc/doc-txt/README.SIEVE,v 1.2 2005/03/01 10:21:43 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
 
@@ -20,9 +20,9 @@ then there is no way around it.
 
 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.
@@ -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.
 
 
-Strings Containing Header Names
+Strings Containing Header Names Or Envelope Elements
 
 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
-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
@@ -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.
 
 
-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
@@ -168,30 +158,14 @@ that aspect using the appendfile transport options "create_directory",
 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
-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
@@ -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
-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
-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,
@@ -337,22 +308,23 @@ extension.
 
   vacation-command =  "vacation" { vacation-options } <reason: string>
   vacation-options =  [":days" number]
-                      [":addresses" string-list]
                       [":subject" string]
+                      [":from" string]
+                      [":addresses" string-list]
                       [":mime"]
+                      [":handle" string]
   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"
@@ -365,27 +337,21 @@ the UTF-8 reason is processed to compose the resulting message.
 
 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
 
-This implementation hashes the reason, specified subject, ":mime"
-option and ":addresses" 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,
@@ -402,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.
-
-
-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.