tidying

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

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 535e81ee643fdda3c378d877629aebab14d97cdc..d4ebf464d7fc7f593bedd4a00a0dc42536bbcf5e 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -6878,16 +6878,9 @@ is used on its own as the result. If the lookup does not succeed, the
 &`fail`& keyword causes a &'forced expansion failure'& &-- see section
 &<<SECTforexpfai>>& for an explanation of what this means.
 
 &`fail`& keyword causes a &'forced expansion failure'& &-- see section
 &<<SECTforexpfai>>& for an explanation of what this means.
 

-The supported DNS record types are A, CNAME, MX, NS, PTR, SPF, SRV, TLSA and TXT,
-and, when Exim is compiled with IPv6 support, AAAA.
-If no type is given, TXT is assumed. When the type is PTR,
-the data can be an IP address, written as normal; inversion and the addition of
-&%in-addr.arpa%& or &%ip6.arpa%& happens automatically. For example:
-.code
-${lookup dnsdb{ptr=192.168.4.5}{$value}fail}
-.endd
-If the data for a PTR record is not a syntactically valid IP address, it is not
-altered and nothing is added.
+The supported DNS record types are A, CNAME, MX, NS, PTR, SOA, SPF, SRV, TLSA
+and TXT, and, when Exim is compiled with IPv6 support, AAAA.
+If no type is given, TXT is assumed.

 
 For any record type, if multiple records are found, the data is returned as a
 concatenation, with newline as the default separator. The order, of course,
 
 For any record type, if multiple records are found, the data is returned as a
 concatenation, with newline as the default separator. The order, of course,


@@ -6899,21 +6892,33 @@ ${lookup dnsdb{>: a=host1.example}}
 .endd
 It is permitted to specify a space as the separator character. Further
 white space is ignored.
 .endd
 It is permitted to specify a space as the separator character. Further
 white space is ignored.

+For lookup types that return multiple fields per record,
+an alternate field separator can be specified using a comma after the main
+separator character, followed immediately by the field separator.
+
+.cindex "PTR record" "in &(dnsdb)& lookup"
+When the type is PTR,
+the data can be an IP address, written as normal; inversion and the addition of
+&%in-addr.arpa%& or &%ip6.arpa%& happens automatically. For example:
+.code
+${lookup dnsdb{ptr=192.168.4.5}{$value}fail}
+.endd
+If the data for a PTR record is not a syntactically valid IP address, it is not
+altered and nothing is added.

 
 .cindex "MX record" "in &(dnsdb)& lookup"
 .cindex "SRV record" "in &(dnsdb)& lookup"
 For an MX lookup, both the preference value and the host name are returned for
 each record, separated by a space. For an SRV lookup, the priority, weight,
 port, and host name are returned for each record, separated by spaces.
 
 .cindex "MX record" "in &(dnsdb)& lookup"
 .cindex "SRV record" "in &(dnsdb)& lookup"
 For an MX lookup, both the preference value and the host name are returned for
 each record, separated by a space. For an SRV lookup, the priority, weight,
 port, and host name are returned for each record, separated by spaces.

-An alternate field separator can be specified using a comma after the main
-separator character, followed immediately by the field separator.
+The field separator can be modified as above.

 
 .cindex "TXT record" "in &(dnsdb)& lookup"
 .cindex "SPF record" "in &(dnsdb)& lookup"
 For TXT records with multiple items of data, only the first item is returned,
 
 .cindex "TXT record" "in &(dnsdb)& lookup"
 .cindex "SPF record" "in &(dnsdb)& lookup"
 For TXT records with multiple items of data, only the first item is returned,

-unless a separator for them is specified using a comma after the separator
-character followed immediately by the TXT record item separator. To concatenate
-items without a separator, use a semicolon instead. For SPF records the
+unless a field separator is specified.
+To concatenate items without a separator, use a semicolon instead.
+For SPF records the

 default behaviour is to concatenate multiple items without using a separator.
 .code
 ${lookup dnsdb{>\n,: txt=a.b.example}}
 default behaviour is to concatenate multiple items without using a separator.
 .code
 ${lookup dnsdb{>\n,: txt=a.b.example}}


@@ -6923,6 +6928,15 @@ ${lookup dnsdb{spf=example.org}}
 It is permitted to specify a space as the separator character. Further
 white space is ignored.
 
 It is permitted to specify a space as the separator character. Further
 white space is ignored.
 

+.cindex "SOA record" "in &(dnsdb)& lookup"
+For an SOA lookup, while no result is obtained the lookup is redone with
+successively more leading components dropped from the given domain.
+Only the primary-nameserver field is returned unless a field separator is
+specified.
+.code
+${lookup dnsdb{>:,; soa=a.b.example.com}}
+.endd
+

 .section "Dnsdb lookup modifiers" "SECTdnsdb_mod"
 .cindex "dnsdb modifiers"
 .cindex "modifiers" "dnsdb"
 .section "Dnsdb lookup modifiers" "SECTdnsdb_mod"
 .cindex "dnsdb modifiers"
 .cindex "modifiers" "dnsdb"


@@ -8951,7 +8965,7 @@ The field selectors marked as "RFC4514" above
 output a Distinguished Name string which is
 not quite
 parseable by Exim as a comma-separated tagged list
 output a Distinguished Name string which is
 not quite
 parseable by Exim as a comma-separated tagged list

-(the exceptions being elements containin commas).
+(the exceptions being elements containing commas).

 RDN elements of a single type may be selected by
 a modifier of the type label; if so the expansion
 result is a list (newline-separated by default).
 RDN elements of a single type may be selected by
 a modifier of the type label; if so the expansion
 result is a list (newline-separated by default).


@@ -9722,8 +9736,9 @@ the regular expression from string expansion.
 
 
 .vitem &*${sort{*&<&'string'&>&*}{*&<&'comparator'&>&*}{*&<&'extractor'&>&*}}*&
 
 
 .vitem &*${sort{*&<&'string'&>&*}{*&<&'comparator'&>&*}{*&<&'extractor'&>&*}}*&

-.cindex sorting a list
+.cindex sorting "a list"

 .cindex list sorting
 .cindex list sorting

+.cindex expansion "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
 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


@@ -17059,7 +17074,7 @@ This applies to all of the SRV, MX, AAAA, A lookup sequence.
 .cindex "DNS" "DNSSEC"
 DNS lookups for domains matching &%dnssec_request_domains%& will be done with
 the dnssec request bit set.  Any returns not having the Authenticated Data bit
 .cindex "DNS" "DNSSEC"
 DNS lookups for domains matching &%dnssec_request_domains%& will be done with
 the dnssec request bit set.  Any returns not having the Authenticated Data bit

-(AD bit) set wil be ignored and logged as a host-lookup failure.
+(AD bit) set will be ignored and logged as a host-lookup failure.

 This applies to all of the SRV, MX, AAAA, A lookup sequence.
 
 
 This applies to all of the SRV, MX, AAAA, A lookup sequence.