bump version to 5.0-16

[pmg-docs.git] / pmg-mail-filter.adoc

diff --git a/pmg-mail-filter.adoc b/pmg-mail-filter.adoc
index 6a4d8f81fb36e2264a52cd3011e0b647b29d329c..2f4cc59b6565e4c70f8d645510c98a377eabf114 100644 (file)
--- a/pmg-mail-filter.adoc
+++ b/pmg-mail-filter.adoc
@@ -11,7 +11,7 @@ Every rule has 5 categories ('FROM', 'TO', 'WHEN', 'WHAT' and
 'ACTION'), and each category may contain several objects to match
 certain criteria:
 
 'ACTION'), and each category may contain several objects to match
 certain criteria:
 

-WHO - objects::
+'Who' - objects::

 
 Who is the sender or receiver of the e-mail? Those objects can be used
 for the 'TO' and/or 'FROM' category.
 
 Who is the sender or receiver of the e-mail? Those objects can be used
 for the 'TO' and/or 'FROM' category.


@@ -20,7 +20,7 @@ for the 'TO' and/or 'FROM' category.
 Example: EMail-object - Who is the sender or receiver of the e-mail?
 ====
 
 Example: EMail-object - Who is the sender or receiver of the e-mail?
 ====
 

-WHAT - objects::
+'What' - objects::

 
 What is in the e-mail?
 +
 
 What is in the e-mail?
 +


@@ -28,7 +28,7 @@ What is in the e-mail?
 Example: Does the e-mail contain spam?
 ====
 
 Example: Does the e-mail contain spam?
 ====
 

-WHEN - objects::
+'When' - objects::

 
 When is the e-mail received by {pmg}?
 +
 
 When is the e-mail received by {pmg}?
 +


@@ -36,7 +36,7 @@ When is the e-mail received by {pmg}?
 Example: Office Hours - Mail is received between 8:00 and 16:00.
 ====
 
 Example: Office Hours - Mail is received between 8:00 and 16:00.
 ====
 

-ACTIONS - objects::
+'Action' - objects::

 
 Defines the final actions.
 +
 
 Defines the final actions.
 +


@@ -58,8 +58,8 @@ testing and debugging. The 'Factory Defaults' button alows you to
 reset the filter rules.
 
 
 reset the filter rules.
 
 

-Actions
--------
+'Action' - objects
+------------------

 
 image::images/screenshot/pmg-gui-mail-filter-actions.png[]
 
 
 image::images/screenshot/pmg-gui-mail-filter-actions.png[]
 


@@ -145,7 +145,7 @@ Remove attachments
 ~~~~~~~~~~~~~~~~~~
 
 Remove attachments can either remove all attachments, or only those
 ~~~~~~~~~~~~~~~~~~
 
 Remove attachments can either remove all attachments, or only those

-matched by the rules 'WHAT' object. You can also specify the
+matched by the rules 'What' - object. You can also specify the

 replacement text if you want.
 
 
 replacement text if you want.
 
 


@@ -155,8 +155,8 @@ Disclaimer
 Add a Disclaimer.
 
 
 Add a Disclaimer.
 
 

-WHO - objects
--------------
+'Who' - objects
+---------------

 
 image::images/screenshot/pmg-gui-mail-filter-who-objects.png[]
 
 
 image::images/screenshot/pmg-gui-mail-filter-who-objects.png[]
 


@@ -184,18 +184,18 @@ LDAP User or Group::
 
 Test if the mail address belong to a specific LDAP user or group.
 
 
 Test if the mail address belong to a specific LDAP user or group.
 

-We have two important WHO objects called 'Blacklist' and
+We have two important 'Who' - objects called 'Blacklist' and

 'Whitelist'. Those are used in the default ruleset to globally block
 or allow specific senders.
 
 
 'Whitelist'. Those are used in the default ruleset to globally block
 or allow specific senders.
 
 

-WHAT - objects
---------------
+'What' - objects
+----------------

 
 image::images/screenshot/pmg-gui-mail-filter-what-objects.png[]
 
 
 image::images/screenshot/pmg-gui-mail-filter-what-objects.png[]
 

-WHAT - objects are used to classify the mail content. A single object
-can combine multiple items, and the following item types are
+'What' - objects are used to classify the mail content. A single
+object can combine multiple items, and the following item types are

 available:
 
 Spam Filter::
 available:
 
 Spam Filter::


@@ -206,6 +206,10 @@ Virus Filter::
 
 Matches on infected mails.
 
 
 Matches on infected mails.
 

+Match Field::
+
+Match specified mail header fields (eg. `Subject:`, `From:`, ...)
+

 Content Type Filter::
 
 Can be used to match specific content types.
 Content Type Filter::
 
 Can be used to match specific content types.


@@ -219,13 +223,59 @@ Archive Filter::
 Can be used to match specific content types inside archives.
 
 
 Can be used to match specific content types inside archives.
 
 

-WHEN - objects
---------------
+'When' - objects
+----------------

 
 image::images/screenshot/pmg-gui-mail-filter-when-objects.png[]
 
 
 image::images/screenshot/pmg-gui-mail-filter-when-objects.png[]
 

-WHEN - objects are use to activate rules at specific daytimes. You can compose
-them of one or more time-frame items.
+'When' - objects are use to activate rules at specific daytimes. You
+can compose them of one or more time-frame items.

 
 The default ruleset defines 'Office Hours', but this is not used by
 the default rules.
 
 The default ruleset defines 'Office Hours', but this is not used by
 the default rules.

+
+
+Using regular expressions
+-------------------------
+
+A regular expression is a string of characters which tells us which
+string you are looking for. The following is a short introduction in
+the syntax of regular expressions used by some objects. If you are
+familiar with Perl, you already know the syntax.
+
+Simple regular expressions
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In its simplest form, a regular expression is just a word or phrase to
+search for. `Mail` would match the string "Mail". The search is case
+sensitive so "MAIL", "Mail", "mail" would not be matched.
+
+Metacharacters
+~~~~~~~~~~~~~~
+
+Some characters have a special meaning. These characters are called
+metacharacters.  The Period (`.`) is a commonly used metacharacter. It
+matches exactly one character, regardless of what the character is.
+`e.mail` would match either "e-mail" or "e-mail" or "e2mail" but not
+"e-some-mail".
+
+The question mark (`?`) indicates that the character immediately
+preceding it either zero or one time. `e?mail` would match
+either "email" or "mail" but not "e-mail".
+
+Another metacharacter is the star (`*`). This indicates that the
+character immediately to its left may repeated any number of times,
+including zero. `e*mail` would match either "email" or "mail" or
+"eeemail".
+
+The plus (`+`) metacharacter does the same as the star (*) excluding
+zero. So `e+mail` does not match "mail".
+
+Metacharacters may be combined. A common combination includes the
+period and star metacharacters (`.*`), with the star immediately following
+the period. This is used to match an arbitrary string of any length,
+including the null string. For example: `.*company.*` matches
+"company@domain.com" or "company@domain.co.uk" or
+"department.company@domain.com".
+
+The book xref:Friedl97[] provides a more comprehensive introduction.
\ No newline at end of file