doc: Describe filter expressions.

* doc/gpg.texi: Remove some superfluous .E.
(FILTER EXPRESSIONS): New.

Signed-off-by: Werner Koch <[email protected]>

2 files changed, 124 insertions, 9 deletions

diff --git a/common/recsel.c b/common/recsel.c
index b35574fb6..5dc685fe9 100644
--- a/common/recsel.c
+++ b/common/recsel.c
@@ -133,7 +133,7 @@ find_next_lc (char *string)
 }
 
 
-/* Parse an expression.  The expression symtax is:
+/* Parse an expression.  The expression syntax is:
  *
  *   [<lc>] {{<flag>} PROPNAME <op> VALUE [<lc>]}
  *
@@ -161,8 +161,8 @@ find_next_lc (char *string)
  *   >=  The numerical value of the field must be GE than the value.
  *   -n  True if value is not empty (no VALUE parameter allowed).
  *   -z  True if value is empty (no VALUE parameter allowed).
- *   -t  Alias for "NAME != 0" (no VALUE parameter allowed).
- *   -f  Alias for "NAME == 0" (no VALUE parameter allowed).
+ *   -t  Alias for "PROPNAME != 0" (no VALUE parameter allowed).
+ *   -f  Alias for "PROPNAME == 0" (no VALUE parameter allowed).
  *
  * Values for <flag> must be space separated and any of:
  *
diff --git a/doc/gpg.texi b/doc/gpg.texi
index 7118e0d1c..7dff333d5 100644
--- a/doc/gpg.texi
+++ b/doc/gpg.texi
@@ -570,7 +570,7 @@ Use the source, Luke :-). The output format is still subject to change.
 
 
 @item --enarmor
-@item --dearmor
+@itemx --dearmor
 @opindex enarmor
 @opindex dearmor
 Pack or unpack an arbitrary input into/from an OpenPGP ASCII armor.
@@ -2239,9 +2239,9 @@ The available filter types are:
 
 @end table
 
-The syntax for the expression is defined in the appendix (FIXME).  The
-property names for the expressions depend on the actual filter type
-and are indicated in the following table.
+For the syntax of the expression see the chapter "FILTER EXPRESSIONS".
+The property names for the expressions depend on the actual filter
+type and are indicated in the following table.
 
 The available properties are:
 
@@ -3238,7 +3238,6 @@ current home directory (@pxref{option --homedir}).
 
 @end table
 
-@c man:.RE
 Note that on larger installations, it is useful to put predefined files
 into the directory @file{@value{SYSCONFSKELDIR}} so that
 newly created users start up with a working configuration.
@@ -3313,7 +3312,6 @@ files; They all live in in the current home directory (@pxref{option
 
 @end table
 
-@c man:.RE
 Operation is further controlled by a few environment variables:
 
 @table @asis
@@ -3406,6 +3404,123 @@ user for the filename.
 @include specify-user-id.texi
 @end ifset
 
+@mansect filter expressions
+@chapheading FILTER EXPRESSIONS
+
+The options @option{--import-filter} and @option{--export-filter} use
+expressions with this syntax (square brackets indicate an optional
+part and curly braces a repetition, white space between the elements
+are allowed):
+
+@c man:.RS
+@example
+  [lc] @{[@{flag@}] PROPNAME op VALUE [lc]@}
+@end example
+@c man:.RE
+
+The name of a property (@var{PROPNAME}) may only consist of letters,
+digits and underscores.  The description for the filter type
+describes which properties are defined.  If an undefined property is
+used it evaluates to the empty string.  Unless otherwise noted, the
+@var{VALUE} must always be given and may not be the empty string.  No
+quoting is defined for the value, thus the value may not contain the
+strings @code{&&} or @code{||}, which are used as logical connection
+operators.  The flag @code{--} can be used to remove this restriction.
+
+Numerical values are computed as long int; standard C notation
+applies.  @var{lc} is the logical connection operator; either
+@code{&&} for a conjunction or @code{||} for a disjunction.  A
+conjunction is assumed at the begin of an expression.  Conjunctions
+have higher precedence than disjunctions.  If @var{VALUE} starts with
+one of the characters used in any @var{op} a space after the
+@var{op} is required.
+
+@noindent
+The supported operators (@var{op}) are:
+
+@table @asis
+
+  @item =~
+  Substring must match.
+
+  @item  !~
+  Substring must not match.
+
+  @item  =
+  The full string must match.
+
+  @item  <>
+  The full string must not match.
+
+  @item  ==
+  The numerical value must match.
+
+  @item  !=
+  The numerical value must not match.
+
+  @item  <=
+  The numerical value of the field must be LE than the value.
+
+  @item  <
+  The numerical value of the field must be LT than the value.
+
+  @item  >=
+  The numerical value of the field must be GT than the value.
+
+  @item  >=
+  The numerical value of the field must be GE than the value.
+
+  @item  -n
+  True if value is not empty (no value allowed).
+
+  @item  -z
+  True if value is empty (no value allowed).
+
+  @item  -t
+  Alias for "PROPNAME != 0" (no value allowed).
+
+  @item  -f
+  Alias for "PROPNAME == 0" (no value allowed).
+
+@end table
+
+@noindent
+Values for @var{flag} must be space separated.  The supported flags
+are:
+
+@table @asis
+  @item --
+  @var{VALUE} spans to the end of the expression.
+  @item -c
+  The string match in this part is done case-sensitive.
+@end table
+
+The filter options concatenate several specifications for a filter of
+the same type.  For example the four options in this example:
+
+@c man:.RS
+@example
+ --import-option keep-uid="uid =~ Alfa"
+ --import-option keep-uid="&& uid !~ Test"
+ --import-option keep-uid="|| uid =~ Alpha"
+ --import-option keep-uid="uid !~ Test"
+@end example
+@c man:.RE
+
+@noindent
+which is equivalent to
+
+@c man:.RS
+@example
+ --import-option \
+  keep-uid="uid =~ Alfa" && uid !~ Test" || uid =~ Alpha" && "uid !~ Test"
+@end example
+@c man:.RE
+
+imports only the user ids of a key containing the strings "Alfa"
+or "Alpha" but not the string "test".
+
+
 @mansect return value
 @chapheading RETURN VALUE