X-Git-Url: https://git.exim.org/exim.git/blobdiff_plain/be36e5721725253b7529899884d7fe8ecd5120b9..9acf6b941e1356590e94e8e4a0bcf5dd3318087c:/doc/doc-docbook/spec.xfpt

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 69009e92d..9cfc06ca5 100644
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -9698,6 +9698,37 @@ the regular expression from string expansion.
 
 
 
+.new
+.vitem &*${sort{*&<&'string'&>&*}{*&<&'comparator'&>&*}{*&<&'extractor'&>&*}}*&
+.cindex sorting a list
+.cindex list sorting
+After expansion, <&'string'&> is interpreted as a list, colon-separated by
+default, but the separator can be changed in the usual way.
+The <&'comparator'&> argument is interpreted as the operator
+of a two-argument expansion condition.
+The numeric operators plus ge, gt, le, lt (and ~i variants) are supported.
+The comparison should return true when applied to two values
+if the first value should sort before the second value.
+The <&'extractor'&> expansion is applied repeatedly to elements of the list,
+the element being placed in &$item$&,
+to give values for comparison.
+
+The item result is a sorted list,
+with the original list separator,
+of the list elements (in full) of the original.
+
+Examples:
+.code
+${sort{3:2:1:4}{<}{$item}}
+.endd
+sorts a list of numbers, and
+.code
+${sort {$lookup dnsdb{>:,,mx=example.com}} {<} {${listextract{1}{<,$item}}}}
+.endd
+will sort an MX lookup into priority order.
+.wen
+
+
 .vitem &*${substr{*&<&'string1'&>&*}{*&<&'string2'&>&*}{*&<&'string3'&>&*}}*&
 .cindex "&%substr%& expansion item"
 .cindex "substring extraction"
@@ -16835,7 +16866,7 @@ be specified using &%condition%&.
 Historical note: We have &%condition%& on ACLs and on Routers.  Routers
 are far older, and use one set of semantics.  ACLs are newer and when
 they were created, the ACL &%condition%& process was given far stricter
-parse semantics.  The &%bool{}&% expansion condition uses the same rules as
+parse semantics.  The &%bool{}%& expansion condition uses the same rules as
 ACLs.  The &%bool_lax{}%& expansion condition uses the same rules as
 Routers.  More pointedly, the &%bool_lax{}%& was written to match the existing
 Router rules processing behavior.
@@ -26278,7 +26309,7 @@ an identically named option for the &(smtp)& transport. In each case, the value
 of the option is expanded and must then be the name of a file that contains a
 CRL in PEM format.
 The downside is that clients have to periodically re-download a potentially huge
-file from every certificate authority the know of.
+file from every certificate authority they know of.
 
 The way with most moving parts at query time is Online Certificate
 Status Protocol (OCSP), where the client verifies the certificate
@@ -28276,6 +28307,8 @@ can be appended; they appear within the called ACL in $acl_arg1 to $acl_arg9,
 and $acl_narg is set to the count of values.
 Previous values of these variables are restored after the call returns.
 The name and values are expanded separately.
+Note that spaces in complex expansions which are used as arguments
+will act as argument separators.
 
 If the nested &%acl%& returns &"drop"& and the outer condition denies access,
 the connection is dropped. If it returns &"discard"&, the verb must be
@@ -32489,6 +32522,9 @@ headers_remove = return-receipt-to:acknowledge-to
 Multiple &%headers_remove%& options for a single router or transport can be
 specified; the arguments will append to a single header-names list.
 Each item is separately expanded.
+Note that colons in complex expansions which are used to
+form all or part of a &%headers_remove%& list
+will act as list separators.
 
 When &%headers_add%& or &%headers_remove%& is specified on a router,
 items are expanded at routing time,
@@ -35242,9 +35278,11 @@ given message, or all mail for a given user, or for a given host, for example.
 The input files can be in Exim log format or syslog format.
 If a matching log line is not associated with a specific message, it is
 included in &'exigrep'&'s output without any additional lines. The usage is:
+.new
 .display
-&`exigrep [-t<`&&'n'&&`>] [-I] [-l] [-v] <`&&'pattern'&&`> [<`&&'log file'&&`>] ...`&
+&`exigrep [-t<`&&'n'&&`>] [-I] [-l] [-M] [-v] <`&&'pattern'&&`> [<`&&'log file'&&`>] ...`&
 .endd
+.wen
 If no log file names are given on the command line, the standard input is read.
 
 The &%-t%& argument specifies a number of seconds. It adds an additional
@@ -35264,6 +35302,21 @@ regular expression.
 The &%-v%& option inverts the matching condition. That is, a line is selected
 if it does &'not'& match the pattern.
 
+.new
+The &%-M%& options means &"related messages"&. &'exigrep'& will show messages
+that are generated as a result/response to a message that &'exigrep'& matched
+normally.
+
+Example of &%-M%&:
+user_a sends a message to user_b, which generates a bounce back to user_b. If
+&'exigrep'& is used to search for &"user_a"&, only the first message will be
+displayed.  But if &'exigrep'& is used to search for &"user_b"&, the first and
+the second (bounce) message will be displayed. Using &%-M%& with &'exigrep'&
+when searching for &"user_a"& will show both messages since the bounce is
+&"related"& to or a &"result"& of the first message that was found by the
+search term.
+.wen
+
 If the location of a &'zcat'& command is known from the definition of
 ZCAT_COMMAND in &_Local/Makefile_&, &'exigrep'& automatically passes any file
 whose name ends in COMPRESS_SUFFIX through &'zcat'& as it searches it.