Add ${listextract {n}{list}...}

[exim.git] / doc / doc-docbook / spec.xfpt

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 4b9f53ed14073603c012951509783ef90b0abbae..f29c38722ccb6e90a9461553b28b6e04e11c6ce2 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -7040,6 +7040,18 @@ With sufficiently modern LDAP libraries, Exim supports forcing TLS over regular
 LDAP connections, rather than the SSL-on-connect &`ldaps`&.
 See the &%ldap_start_tls%& option.
 
+.new
+Starting with Exim 4.83, the initialization of LDAP with TLS is more tightly
+controlled. Every part of the TLS configuration can be configured by settings in
+&_exim.conf_&. Depending on the version of the client libraries installed on
+your system, some of the initialization may have required setting options in
+&_/etc/ldap.conf_& or &_~/.ldaprc_& to get TLS working with self-signed
+certificates. This revealed a nuance where the current UID that exim was
+running as could affect which config files it read. With Exim 4.83, these
+methods become optional, only taking effect if not specifically set in
+&_exim.conf_&.
+.wen
+
 
 .section "LDAP quoting" "SECID68"
 .cindex "LDAP" "quoting"
@@ -9169,6 +9181,44 @@ of <&'string2'&>, whichever is the shorter. Do not confuse &%length%& with
 &%strlen%&, which gives the length of a string.
 
 
+.vitem "&*${listextract{*&<&'number'&>&*}&&&
+        {*&<&'string1'&>&*}{*&<&'string2'&>&*}{*&<&'string3'&>&*}}*&"
+.cindex "expansion" "extracting list elements by number"
+.cindex "&%listextract%&" "extract list elements by number"
+.cindex "list" "extracting elements by number"
+The <&'number'&> argument must consist entirely of decimal digits,
+apart from an optional leading minus,
+and leading and trailing white space (which is ignored).
+
+After expansion, <&'string1'&> is interpreted as a list, colon-separated by
+default, but the separator can be changed in the usual way.
+
+The first field of the list is numbered one.
+If the number is negative, the fields are
+counted from the end of the list, with the rightmost one numbered -1.
+The numbered element of the list is extracted and placed in &$value$&,
+then <&'string2'&> is expanded as the result.
+
+If the modulus of the
+number is zero or greater than the number of fields in the string,
+the result is the expansion of <&'string3'&>.
+
+For example:
+.code
+${listextract{2}{x:42:99}}
+.endd
+yields &"42"&, and
+.code
+${listextract{-3}{<, x,42,99,& Mailer,,/bin/bash}{result: $value}}
+.endd
+yields &"result: 99"&.
+
+If {<&'string3'&>} is omitted, an empty string is used for string3.
+If {<&'string2'&>} is also omitted, the value that was
+extracted is used.
+You can use &`fail`& instead of {<&'string3'&>} as in a string extract.
+
+
 .vitem "&*${lookup{*&<&'key'&>&*}&~*&<&'search&~type'&>&*&~&&&
         {*&<&'file'&>&*}&~{*&<&'string1'&>&*}&~{*&<&'string2'&>&*}}*&"
 This is the first of one of two different types of lookup item, which are both
@@ -13640,6 +13690,9 @@ a very large time at the end of the list. For example:
 .code
 delay_warning = 2h:12h:99d
 .endd
+Note that the option is only evaluated at the time a delivery attempt fails,
+which depends on retry and queue-runner configuration.
+Typically retries will be configured more frequently than warning messages.
 
 .option delay_warning_condition main string&!! "see below"
 .vindex "&$domain$&"