Extend filter documentation slightly

Even though the original filter description is correct and does not contain
any factual flaws it might be confusing to people. There changes address two
pain points (from my point of view):

1. People tend to try using parentheses in their filter expressions for obvious
reasons. But it is not possible. I feel like this should be mentioned in the
documentation. In fact, with DNF you never need parentheses to express any
expression and I think this fact also needs to be noted there.

2. Filter supports regular expressions but currently there is a limitation by
design (a limitation that can actually be removed). Use of '|' and '&' in the
regexp is not allowed - it leads to filter error. This should be fixed but until
then it'd better be documented.

Signed-off-by: Ondrej Moris <[email protected]>

fmf/utils.py

@@ -214,15 +214,23 @@ def filter(filter, data, sensitive=True, regexp=False):
     """
     Return true if provided filter matches given dictionary of values
 
-    Filter supports disjunctive normal form with '|' used for OR, '&'
-    for AND and '-' for negation. Individual values are prefixed with
-    'value:', leading/trailing white-space is stripped. For example::
+    Filter supports disjunctive normal (DNF) form with '|' used for OR,
+    '&' for AND and '-' for negation. Individual values are prefixed
+    with 'value:', leading/trailing white-space is stripped. For
+    example:
 
         tag: Tier1 | tag: Tier2 | tag: Tier3
         category: Sanity, Security & tag: -destructive
 
+    Even though parentheses are only allowed in keys or values they are
+    not needed for DNF as the correct order of precedence of operators
+    is respected (negation first, AND next and then OR). For example,
+    to express '(tag: A | tag: B) & tag: C' use the following filter:
+
+        tag: A & tag: C | tag: B & tag: C
+
     Note that multiple comma-separated values can be used as a syntactic
-    sugar to shorten the filter notation::
+    sugar to shorten the filter notation:
 
         tag: A, B, C ---> tag: A | tag: B | tag: C
 
@@ -236,6 +244,8 @@ def filter(filter, data, sensitive=True, regexp=False):
     filter is not found in the data dictionary. Set option 'sensitive'
     to False to enable case-insensitive matching. If 'regexp' option is
     True, regular expressions can be used in the filter values as well.
+    However, using either '|' or '&' in the regular expression is not
+    allowed.
     """
 
     def match_value(pattern, text):