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

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 3b9082031..cd81a2287 100644
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -214,142 +214,63 @@
 
 
 . /////////////////////////////////////////////////////////////////////////////
-. This chunk of literal XML implements index entries of the form "x, see y" and
-. "x, see also y". However, the DocBook DTD doesn't allow <indexterm> entries
+. These implement index entries of the form "x, see y" and "x, see also y".
+. However, the DocBook DTD doesn't allow <indexterm> entries
 . at the top level, so we have to put the .chapter directive first.
-
-. These do not turn up in the HTML output, unfortunately.  The PDF does get them.
 . /////////////////////////////////////////////////////////////////////////////
 
 .chapter "Introduction" "CHID1"
-.literal xml
 
-<indexterm role="variable">
-  <primary>$1, $2, etc.</primary>
-  <see><emphasis>numerical variables</emphasis></see>
-</indexterm>
-<indexterm role="concept">
-  <primary>address</primary>
-  <secondary>rewriting</secondary>
-  <see><emphasis>rewriting</emphasis></see>
-</indexterm>
-<indexterm role="concept">
-  <primary>Bounce Address Tag Validation</primary>
-  <see><emphasis>BATV</emphasis></see>
-</indexterm>
-<indexterm role="concept">
-  <primary>Client SMTP Authorization</primary>
-  <see><emphasis>CSA</emphasis></see>
-</indexterm>
-<indexterm role="concept">
-  <primary>CR character</primary>
-  <see><emphasis>carriage return</emphasis></see>
-</indexterm>
-<indexterm role="concept">
-  <primary>CRL</primary>
-  <see><emphasis>certificate revocation list</emphasis></see>
-</indexterm>
-<indexterm role="concept">
-  <primary>delivery</primary>
-  <secondary>failure report</secondary>
-  <see><emphasis>bounce message</emphasis></see>
-</indexterm>
-<indexterm role="concept">
-  <primary>dialup</primary>
-  <see><emphasis>intermittently connected hosts</emphasis></see>
-</indexterm>
-<indexterm role="concept">
-  <primary>exiscan</primary>
-  <see><emphasis>content scanning</emphasis></see>
-</indexterm>
-<indexterm role="concept">
-  <primary>failover</primary>
-  <see><emphasis>fallback</emphasis></see>
-</indexterm>
-<indexterm role="concept">
-  <primary>fallover</primary>
-  <see><emphasis>fallback</emphasis></see>
-</indexterm>
-<indexterm role="concept">
-  <primary>filter</primary>
-  <secondary>Sieve</secondary>
-  <see><emphasis>Sieve filter</emphasis></see>
-</indexterm>
-<indexterm role="concept">
-  <primary>ident</primary>
-  <see><emphasis>RFC 1413</emphasis></see>
-</indexterm>
-<indexterm role="concept">
-  <primary>LF character</primary>
-  <see><emphasis>linefeed</emphasis></see>
-</indexterm>
-<indexterm role="concept">
-  <primary>maximum</primary>
-  <seealso><emphasis>limit</emphasis></seealso>
-</indexterm>
-<indexterm role="concept">
-  <primary>monitor</primary>
-  <see><emphasis>Exim monitor</emphasis></see>
-</indexterm>
-<indexterm role="concept">
-  <primary>no_<emphasis>xxx</emphasis></primary>
-  <see>entry for xxx</see>
-</indexterm>
-<indexterm role="concept">
-  <primary>NUL</primary>
-  <see><emphasis>binary zero</emphasis></see>
-</indexterm>
-<indexterm role="concept">
-  <primary>passwd file</primary>
-  <see><emphasis>/etc/passwd</emphasis></see>
-</indexterm>
-<indexterm role="concept">
-  <primary>process id</primary>
-  <see><emphasis>pid</emphasis></see>
-</indexterm>
-<indexterm role="concept">
-  <primary>RBL</primary>
-  <see><emphasis>DNS list</emphasis></see>
-</indexterm>
-<indexterm role="concept">
-  <primary>redirection</primary>
-  <see><emphasis>address redirection</emphasis></see>
-</indexterm>
-<indexterm role="concept">
-  <primary>return path</primary>
-  <seealso><emphasis>envelope sender</emphasis></seealso>
-</indexterm>
-<indexterm role="concept">
-  <primary>scanning</primary>
-  <see><emphasis>content scanning</emphasis></see>
-</indexterm>
-<indexterm role="concept">
-  <primary>SSL</primary>
-  <see><emphasis>TLS</emphasis></see>
-</indexterm>
-<indexterm role="concept">
-  <primary>string</primary>
-  <secondary>expansion</secondary>
-  <see><emphasis>expansion</emphasis></see>
-</indexterm>
-<indexterm role="concept">
-  <primary>top bit</primary>
-  <see><emphasis>8-bit characters</emphasis></see>
-</indexterm>
-<indexterm role="concept">
-  <primary>variables</primary>
-  <see><emphasis>expansion, variables</emphasis></see>
-</indexterm>
-<indexterm role="concept">
-  <primary>zero, binary</primary>
-  <see><emphasis>binary zero</emphasis></see>
-</indexterm>
-<indexterm role="concept">
-  <primary>headers</primary>
-  <see><emphasis>header lines</emphasis></see>
+.macro seeother
+.literal xml
+<indexterm role="$2">
+  <primary>$3</primary>
+.arg 5
+  <secondary>$5</secondary>
+.endarg
+  <$1><emphasis>$4</emphasis></$1>
 </indexterm>
-
 .literal off
+.endmacro
+
+. NB: for the 4-arg variant the ordering is awkward
+.macro see
+.seeother see "$1" "$2" "$3" "$4"
+.endmacro
+.macro seealso
+.seeother seealso "$1" "$2" "$3" "$4"
+.endmacro
+
+.see     variable "<emphasis>$1</emphasis>, <emphasis>$2</emphasis>, etc." "numerical variables"
+.see     concept address	rewriting			rewriting
+.see     concept "Bounce Address Tag Validation"	BATV
+.see     concept "Client SMTP Authorization"		CSA
+.see     concept "CR character"	"carriage return"
+.see     concept CRL		"certificate revocation list"
+.seealso concept de-tainting	"tainted data"
+.see     concept delivery	"bounce message"		"failure report"
+.see     concept dialup		"intermittently connected hosts"
+.see     concept exiscan	"content scanning"
+.see     concept fallover	fallback
+.see     concept filter 	"Sieve filter"			Sieve
+.see     concept headers	"header lines"
+.see     concept ident		"RFC 1413"
+.see     concept "LF character"	"linefeed"
+.seealso concept maximum	limit
+.see     concept monitor	"Exim monitor"
+.see     concept "no_<emphasis>xxx</emphasis>"		"entry for xxx"
+.see     concept NUL		"binary zero"
+.see     concept "passwd file"	"/etc/passwd"
+.see     concept "process id"	pid
+.see     concept RBL		"DNS list"
+.see     concept redirection	"address redirection"
+.see     concept "return path"	"envelope sender"
+.see     concept scanning	"content scanning"
+.see     concept SSL		TLS
+.see     concept string		expansion expansion
+.see     concept "top bit"	"8-bit characters"
+.see     concept variables	"expansion, variables"
+.see     concept "zero, binary"	"binary zero"
 
 
 . /////////////////////////////////////////////////////////////////////////////
@@ -2913,6 +2834,12 @@ defined and macros will be expanded.
 Because macros in the config file are often used for secrets, those are only
 available to admin users.
 
+.new
+The word &"set"& at the start of a line, followed by a single space,
+is recognised specially as defining a value for a variable.
+The syntax is otherwise the same as the ACL modifier &"set ="&.
+.wen
+
 .vitem &%-bem%&&~<&'filename'&>
 .oindex "&%-bem%&"
 .cindex "testing" "string expansion"
@@ -32256,7 +32183,7 @@ different variants of this condition to describe briefly here. See sections
 .cindex "domain" "ACL checking"
 .cindex "&ACL;" "testing a recipient domain"
 .vindex "&$domain_data$&"
-This condition is relevant only after a RCPT command. It checks that the domain
+This condition is relevant only in a RCPT ACL. It checks that the domain
 of the recipient address is in the domain list. If percent-hack processing is
 enabled, it is done before this test is done. If the check succeeds with a
 lookup, the result of the lookup is placed in &$domain_data$& until the next
@@ -32324,7 +32251,7 @@ which gives a custom error message for each denied host.
 .cindex "local part" "ACL checking"
 .cindex "&ACL;" "testing a local part"
 .vindex "&$local_part_data$&"
-This condition is relevant only after a RCPT command. It checks that the local
+This condition is relevant only in a RCPT ACL. It checks that the local
 part of the recipient address is in the list. If percent-hack processing is
 enabled, it is done before this test. If the check succeeds with a lookup, the
 result of the lookup is placed in &$local_part_data$&, which remains set until
@@ -32358,7 +32285,7 @@ messages. Details are given in section &<<SECTratelimiting>>&.
 .cindex "&%recipients%& ACL condition"
 .cindex "recipient" "ACL checking"
 .cindex "&ACL;" "testing a recipient"
-This condition is relevant only after a RCPT command. It checks the entire
+This condition is relevant only in a RCPT ACL. It checks the entire
 recipient address against a list of recipients.
 
 .vitem &*regex&~=&~*&<&'list&~of&~regular&~expressions'&>
@@ -32370,7 +32297,7 @@ non-SMTP ACLs. It causes the incoming message to be scanned for a match with
 any of the regular expressions. For details, see chapter &<<CHAPexiscan>>&.
 
 .vitem &*seen&~=&~*&<&'parameters'&>
-.cindex "&%sseen%& ACL condition"
+.cindex "&%seen%& ACL condition"
 This condition can be used to test if a situation has been previously met,
 for example for greylisting.
 Details are given in section &<<SECTseen>>&.
@@ -33099,7 +33026,7 @@ address you should specify alternate list separators for both the outer
 
 
 .section "Previously seen user and hosts" "SECTseen"
-.cindex "&%sseen%& ACL condition"
+.cindex "&%een%& ACL condition"
 .cindex greylisting
 The &%seen%& ACL condition can be used to test whether a
 situation has been previously met.
@@ -33595,7 +33522,7 @@ clients when the SMTP PIPELINING extension is in use. The flushing can be
 disabled by using a &%control%& modifier to set &%no_callout_flush%&.
 
 .cindex "tainted data" "de-tainting"
-.cindex "de-tainting" "using receipient verify"
+.cindex "de-tainting" "using recipient verify"
 A recipient callout which gets a 2&'xx'& code
 will assign untainted values to the
 &$domain_data$& and &$local_part_data$& variables,