Light documentation dusting from patch provided by John Horne.

Fixes: #922

3 files changed, 88 insertions, 82 deletions

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 02020dc50..7237cc3df 100644
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -1,4 +1,4 @@
-. $Cambridge: exim/doc/doc-docbook/spec.xfpt,v 1.80 2010/06/06 00:25:46 pdp Exp $
+. $Cambridge: exim/doc/doc-docbook/spec.xfpt,v 1.81 2010/06/06 01:35:41 pdp Exp $
 .
 . /////////////////////////////////////////////////////////////////////////////
 . This is the primary source of the Exim Manual. It is an xfpt document that is
@@ -9802,7 +9802,7 @@ All other string values will result in expansion failure.
 
 When combined with ACL variables, this expansion condition will let you
 make decisions in one place and act on those decisions in another place.
-For example,
+For example:
 .code
 ${if bool{$acl_m_privileged_sender} ...
 .endd
@@ -12363,6 +12363,7 @@ listed in more than one group.
 .row &%acl_smtp_auth%&               "ACL for AUTH"
 .row &%acl_smtp_connect%&            "ACL for connection"
 .row &%acl_smtp_data%&               "ACL for DATA"
+.row &%acl_smtp_dkim%&               "ACL for DKIM verification"
 .row &%acl_smtp_etrn%&               "ACL for ETRN"
 .row &%acl_smtp_expn%&               "ACL for EXPN"
 .row &%acl_smtp_helo%&               "ACL for EHLO or HELO"
@@ -12824,7 +12825,7 @@ It specifies which anti-virus scanner to use. The default value is:
 .code
 sophie:/var/run/sophie
 .endd
-If the value of &%av_scanner%& starts with dollar character, it is expanded
+If the value of &%av_scanner%& starts with a dollar character, it is expanded
 before use. See section &<<SECTscanvirus>>& for further details.
 
 
@@ -27911,7 +27912,7 @@ If you do not set &%av_scanner%&, it defaults to
 .code
 av_scanner = sophie:/var/run/sophie
 .endd
-If the value of &%av_scanner%& starts with dollar character, it is expanded
+If the value of &%av_scanner%& starts with a dollar character, it is expanded
 before use. The following scanner types are supported in this release:
 
 .vlist
@@ -28209,9 +28210,8 @@ it always return &"true"& by appending &`:true`& to the username.
 
 .cindex "spam scanning" "returned variables"
 When the &%spam%& condition is run, it sets up a number of expansion
-variables. With the exception of &$spam_score_int$&, these are usable only
-within ACLs; their values are not retained with the message and so cannot be
-used at delivery time.
+variables. These variables are saved with the received message, thus they are
+available for use at delivery time.
 
 .vlist
 .vitem &$spam_score$&
@@ -28222,11 +28222,8 @@ for inclusion in log or reject messages.
 The spam score of the message, multiplied by ten, as an integer value. For
 example &"34"& or &"305"&. It may appear to disagree with &$spam_score$&
 because &$spam_score$& is rounded and &$spam_score_int$& is truncated.
-The integer value is useful for numeric comparisons in
-conditions. This variable is special; its value is saved with the message, and
-written to Exim's spool file. This means that it can be used during the whole
-life of the message on your Exim system, in particular, in routers or
-transports during the later delivery phase.
+The integer value is useful for numeric comparisons in conditions.
+
 
 .vitem &$spam_bar$&
 A string consisting of a number of &"+"& or &"-"& characters, representing the
@@ -34453,7 +34450,7 @@ It can co-exist with all other Exim features, including transport filters.
 .next
 Verify signatures in incoming messages: This is implemented by an additional
 ACL (acl_smtp_dkim), which can be called several times per message, with
-different signature context.
+different signature contexts.
 .endlist
 
 In typical Exim style, the verification implementation does not include any
@@ -34481,19 +34478,19 @@ Signing is implemented by setting private options on the SMTP transport.
 These options take (expandable) strings as arguments.
 
 .option dkim_domain smtp string&!! unset
-MANDATORY
+MANDATORY:
 The domain you want to sign with. The result of this expanded
 option is put into the &%$dkim_domain%& expansion variable.
 
 .option dkim_selector smtp string&!! unset
-MANDATORY
+MANDATORY:
 This sets the key selector string. You can use the &%$dkim_domain%& expansion
 variable to look up a matching selector. The result is put in the expansion
 variable &%$dkim_selector%& which should be used in the &%dkim_private_key%&
 option along with &%$dkim_domain%&.
 
 .option dkim_private_key smtp string&!! unset
-MANDATORY
+MANDATORY:
 This sets the private key to use. You can use the &%$dkim_domain%& and
 &%$dkim_selector%& expansion variables to determine the private key to use.
 The result can either
@@ -34509,14 +34506,14 @@ is set.
 .endlist
 
 .option dkim_canon smtp string&!! unset
-OPTIONAL
+OPTIONAL:
 This option sets the canonicalization method used when signing a message.
 The DKIM RFC currently supports two methods: "simple" and "relaxed".
 The option defaults to "relaxed" when unset. Note: the current implementation
 only supports using the same canonicalization method for both headers and body.
 
 .option dkim_strict smtp string&!! unset
-OPTIONAL
+OPTIONAL:
 This  option  defines  how  Exim  behaves  when  signing a message that
 should be signed fails for some reason.  When the expansion evaluates to
 either "1" or "true", Exim will defer. Otherwise Exim will send the message
@@ -34524,7 +34521,7 @@ unsigned. You can use the &%$dkim_domain%& and &%$dkim_selector%& expansion
 variables here.
 
 .option dkim_sign_headers smtp string&!! unset
-OPTIONAL
+OPTIONAL:
 When set, this option must expand to (or be specified as) a colon-separated
 list of header names. Headers with these names will be included in the message
 signature. When unspecified, the header names recommended in RFC4871 will be
@@ -34550,8 +34547,8 @@ more advanced policies. For that reason, the global option
 The global option &%dkim_verify_signers%& can be set to a colon-separated
 list of DKIM domains or identities for which the ACL &%acl_smtp_dkim%& is
 called. It is expanded when the message has been received. At this point,
-the expansion variable &%$dkim_signers%& already contains a colon-
-separated list of signer domains and identities for the message. When
+the expansion variable &%$dkim_signers%& already contains a colon-separated
+list of signer domains and identities for the message. When
 &%dkim_verify_signers%& is not specified in the main configuration,
 it defaults as:
 .code
@@ -34565,7 +34562,7 @@ dkim_verify_signers = paypal.com:ebay.com:$dkim_signers
 .endd
 This would result in &%acl_smtp_dkim%& always being called for "paypal.com"
 and "ebay.com", plus all domains and identities that have signatures in the message.
-You can also be more creative in constructing your policy. Example:
+You can also be more creative in constructing your policy. For example:
 .code
 dkim_verify_signers = $sender_address_domain:$dkim_signers
 .endd
@@ -34579,7 +34576,7 @@ available (from most to least important):
 
 .vlist
 .vitem &%$dkim_cur_signer%&
-The signer that is being evaluated in this ACL run. This can be domain or
+The signer that is being evaluated in this ACL run. This can be a domain or
 an identity. This is one of the list items from the expanded main option
 &%dkim_verify_signers%& (see above).
 .vitem &%$dkim_verify_status%&
@@ -34624,7 +34621,7 @@ The signing identity, if present. IMPORTANT: This variable is only populated
 if there is an actual signature in the message for the current domain or
 identity (as reflected by &%$dkim_cur_signer%&).
 .vitem &%$dkim_selector%&
-The key record selector string
+The key record selector string.
 .vitem &%$dkim_algo%&
 The algorithm used. One of 'rsa-sha1' or 'rsa-sha256'.
 .vitem &%$dkim_canon_body%&
@@ -34659,7 +34656,7 @@ in the key record.
 Key granularity (tag g=) from the key record. Defaults to "*" if not specified
 in the key record.
 .vitem &%$dkim_key_notes%&
-Notes from the key record (tag n=)
+Notes from the key record (tag n=).
 .endlist
 
 In addition, two ACL conditions are provided:
@@ -34669,7 +34666,7 @@ In addition, two ACL conditions are provided:
 ACL condition that checks a colon-separated list of domains or identities
 for a match against the domain or identity that the ACL is currently verifying
 (reflected by &%$dkim_cur_signer%&). This is typically used to restrict an ACL
-verb to a group of domains or identities, like:
+verb to a group of domains or identities. For example:
 
 .code
 # Warn when message apparently from GMail has no signature at all
diff --git a/doc/doc-txt/ChangeLog b/doc/doc-txt/ChangeLog
index b89d1b44c..248e57523 100644
--- a/doc/doc-txt/ChangeLog
+++ b/doc/doc-txt/ChangeLog
@@ -1,4 +1,4 @@
-$Cambridge: exim/doc/doc-txt/ChangeLog,v 1.623 2010/06/06 00:27:52 pdp Exp $
+$Cambridge: exim/doc/doc-txt/ChangeLog,v 1.624 2010/06/06 01:35:41 pdp Exp $
 
 Change log file for Exim from version 4.21
 -------------------------------------------
@@ -36,6 +36,8 @@ PP/09 Implemented reverse_ip expansion operator.
 
 PP/10 Bugzilla 937: provide a "debug" ACL control.
 
+PP/11 Bugzilla 922: Documentation dusting, patch provided by John Horne.
+
 
 Exim version 4.72
 -----------------
@@ -87,7 +89,7 @@ PP/01 Bugzilla 989: CVE-2010-2024 - work round race condition on
 Exim version 4.71
 -----------------
 
-TK/01 Bugzilla 912: Fix DKIM segfault on empty headers/body
+TK/01 Bugzilla 912: Fix DKIM segfault on empty headers/body.
 
 NM/01 Bugzilla 913: Documentation fix for gnutls_* options.
 
@@ -106,7 +108,7 @@ TK/01 Added patch by Johannes Berg that expands the main option
 
 TK/02 Write list of recipients to X-Envelope-Sender header when building
       the mbox-format spool file for content scanning (suggested by Jakob
-      Hirsch)
+      Hirsch).
 
 TK/03 Added patch by Wolfgang Breyha that adds experimental DCC
       (http://www.dcc-servers.net/) support via dccifd. Activated by
@@ -122,16 +124,16 @@ NM/01 Bugzilla 657: Embedded PCRE removed from the exim source tree.
 
 NM/02 Bugzilla 646: Removed unwanted C/R in Dovecot authenticator
       conversation.  Added nologin parameter to request.
-      Patch contributed by Kirill Miazine
+      Patch contributed by Kirill Miazine.
 
 TF/01 Do not log submission mode rewrites if they do not change the address.
 
 TF/02 Bugzilla 662: Fix stack corruption before exec() in daemon.c.
 
 NM/03 Bugzilla 602: exicyclog now handles panic log, and creates empty
-      log files in place.  Contributed by Roberto Lima
+      log files in place.  Contributed by Roberto Lima.
 
-NM/04 Bugzilla 667: close socket used by dovecot authenticator
+NM/04 Bugzilla 667: Close socket used by dovecot authenticator.
 
 TF/03 Bugzilla 615: When checking the local_parts router precondition
       after a local_part_suffix or local_part_prefix option, Exim now
@@ -139,14 +141,14 @@ TF/03 Bugzilla 615: When checking the local_parts router precondition
       contains cached lookups for the whole local part.
 
 NM/05 Bugzilla 521: Integrated SPF Best Guess support contributed by
-      Robert Millan.  Documentation is in experimental-spec.txt
+      Robert Millan.  Documentation is in experimental-spec.txt.
 
 TF/04 Bugzilla 668: Fix parallel build (make -j).
 
-NM/05.2 Bugzilla 437: Prevent Maildir aux files being created with mode 000
+NM/05.2 Bugzilla 437: Prevent Maildir aux files being created with mode 000.
 
 NM/05.3 Bugzilla 598: Improvement to Dovecot authenticator handling.
-      Patch provided by Jan Srzednicki
+      Patch provided by Jan Srzednicki.
 
 TF/05 Leading white space used to be stripped from $spam_report which
       wrecked the formatting. Now it is preserved.
@@ -163,95 +165,96 @@ TF/09 Produce a more useful error message if an SMTP transport's hosts
       setting expands to an empty string.
 
 NM/06 Bugzilla 744: EXPN did not work under TLS.
-      Patch provided by Phil Pennock
+      Patch provided by Phil Pennock.
 
 NM/07 Bugzilla 769: Extraneous comma in usage fprintf
-      Patch provided by Richard Godbee
+      Patch provided by Richard Godbee.
 
 NM/08 Fixed erroneous documentation references to smtp_notquit_acl to be
       acl_smtp_notquit, added index entry.
 
-NM/09 Bugzilla 787: Potential buffer overflow in string_format
-      Patch provided by Eugene Bujak
+NM/09 Bugzilla 787: Potential buffer overflow in string_format.
+      Patch provided by Eugene Bujak.
 
-NM/10 Bugzilla 770: Problem on some platforms modifying the len parameter to accept()
-      Patch provided by Maxim Dounin
+NM/10 Bugzilla 770: Problem on some platforms modifying the len parameter to
+      accept(). Patch provided by Maxim Dounin.
 
 NM/11 Bugzilla 749: Preserve old behaviour of blanks comparing equal to zero.
-      Patch provided by Phil Pennock
+      Patch provided by Phil Pennock.
 
 NM/12 Bugzilla 497: Correct behaviour of exiwhat when no config exists.
 
 NM/13 Bugzilla 590: Correct handling of Resent-Date headers.
-      Patch provided by Brad "anomie" Jorsch
+      Patch provided by Brad "anomie" Jorsch.
 
 NM/14 Bugzilla 622: Added timeout setting to transport filter.
-      Patch provided by Dean Brooks
+      Patch provided by Dean Brooks.
 
 TK/05 Add native DKIM support (does not depend on external libraries).
 
 NM/15 Bugzilla 854: Removed code that symlinks to pcre as its no longer useful.
-      Patch provided by Graeme Fowler
+      Patch provided by Graeme Fowler.
 
 NM/16 Bugzilla 851: Documentation example syntax fix.
 
 NM/17 Changed NOTICE file to remove references to embedded PCRE.
 
-NM/18 Bugzilla 894: Fix issue with very long lines including comments in lsearch
+NM/18 Bugzilla 894: Fix issue with very long lines including comments in
+      lsearch.
 
-NM/19 Bugzilla 745: TLS version reporting
-      Patch provided by Phil Pennock
+NM/19 Bugzilla 745: TLS version reporting.
+      Patch provided by Phil Pennock.
 
-NM/20 Bugzilla 167: bool: condition support
-      Patch provided by Phil Pennock
+NM/20 Bugzilla 167: bool: condition support.
+      Patch provided by Phil Pennock.
 
-NM/21 Bugzilla 665: gnutls_compat_mode to allow compatibility with broken clients
-      Patch provided by Phil Pennock
+NM/21 Bugzilla 665: gnutls_compat_mode to allow compatibility with broken
+      clients. Patch provided by Phil Pennock.
 
-NM/22 Bugzilla 607: prepend (not append) Resent-Message-ID and Resent-Date
-      Patch provided by Brad "anomie" Jorsch
+NM/22 Bugzilla 607: prepend (not append) Resent-Message-ID and Resent-Date.
+      Patch provided by Brad "anomie" Jorsch.
 
-NM/23 Bugzilla 687: Fix misparses in eximstats
-      Patch provided by Heiko Schlittermann
+NM/23 Bugzilla 687: Fix misparses in eximstats.
+      Patch provided by Heiko Schlittermann.
 
-NM/24 Bugzilla 688: Fix exiwhat to handle log_selector = +pid
-      Patch provided by Heiko Schlittermann
+NM/24 Bugzilla 688: Fix exiwhat to handle log_selector = +pid.
+      Patch provided by Heiko Schlittermann.
 
-NM/25 Bugzilla 727: Use transport mode as default mode for maildirsize file
+NM/25 Bugzilla 727: Use transport mode as default mode for maildirsize file.
       plus update to original patch.
 
-NM/26 Bugzilla 799: Documentation correction for ratelimit
+NM/26 Bugzilla 799: Documentation correction for ratelimit.
 
-NM/27 Bugzilla 802: Improvements to local interface IP addr detection
-      Patch provided by David Brownlee
+NM/27 Bugzilla 802: Improvements to local interface IP addr detection.
+      Patch provided by David Brownlee.
 
-NM/28 Bugzilla 807: Improvements to LMTP delivery logging
+NM/28 Bugzilla 807: Improvements to LMTP delivery logging.
 
-NM/29 Bugzilla 862, 866, 875: Documentation bugfixes
+NM/29 Bugzilla 862, 866, 875: Documentation bugfixes.
 
-NM/30 Bugzilla 888: TLS documentation bugfixes
+NM/30 Bugzilla 888: TLS documentation bugfixes.
 
-NM/31 Bugzilla 896: Dovecot buffer overrun fix
+NM/31 Bugzilla 896: Dovecot buffer overrun fix.
 
 NM/32 Bugzilla 889: Change all instances of "expr" in shell scripts to "expr --"
-      Unlike the original bugzilla I have changed all shell scripts in src tree
+      Unlike the original bugzilla I have changed all shell scripts in src tree.
 
-NM/33 Bugzilla 898: Transport filter timeout fix
-      Patch by Todd Rinaldo
+NM/33 Bugzilla 898: Transport filter timeout fix.
+      Patch by Todd Rinaldo.
 
-NM/34 Bugzilla 901: Fix sign/unsigned and UTF mistmatches
-      Patch by Serge Demonchaux
+NM/34 Bugzilla 901: Fix sign/unsigned and UTF mistmatches.
+      Patch by Serge Demonchaux.
 
-NM/35 Bugzilla 39: Base64 decode bug fixes
-      Patch by Jakob Hirsch
+NM/35 Bugzilla 39: Base64 decode bug fixes.
+      Patch by Jakob Hirsch.
 
-NM/36 Bugzilla 909: Correct connect() call in dcc code
+NM/36 Bugzilla 909: Correct connect() call in dcc code.
 
-NM/37 Bugzilla 910: Correct issue with relaxed/simple handling
+NM/37 Bugzilla 910: Correct issue with relaxed/simple handling.
 
-NM/38 Bugzilla 908: Removed NetBSD3 support as no longer needed
+NM/38 Bugzilla 908: Removed NetBSD3 support as no longer needed.
 
-NM/39 Bugzilla 911: Fixed MakeLinks build script
+NM/39 Bugzilla 911: Fixed MakeLinks build script.
 
 
 Exim version 4.69
@@ -273,11 +276,11 @@ NM/01 Bugzilla 592: --help option is handled incorrectly if exim is invoked
 
 SC/01 Added the -bylocaldomain option to eximstats.
 
-NM/02 Bugzilla 619: Defended against bad data coming back from gethostbyaddr
+NM/02 Bugzilla 619: Defended against bad data coming back from gethostbyaddr.
 
-NM/03 Bugzilla 613: Documentation fix for acl_not_smtp
+NM/03 Bugzilla 613: Documentation fix for acl_not_smtp.
 
-NM/04 Bugzilla 628: PCRE update to 7.4 (work done by John Hall)
+NM/04 Bugzilla 628: PCRE update to 7.4 (work done by John Hall).
 
 
 Exim version 4.68
diff --git a/doc/doc-txt/NewStuff b/doc/doc-txt/NewStuff
index a8606870c..fb7e9528c 100644
--- a/doc/doc-txt/NewStuff
+++ b/doc/doc-txt/NewStuff
@@ -1,4 +1,4 @@
-$Cambridge: exim/doc/doc-txt/NewStuff,v 1.170 2010/06/06 00:27:52 pdp Exp $
+$Cambridge: exim/doc/doc-txt/NewStuff,v 1.171 2010/06/06 01:35:41 pdp Exp $
 
 New Features in Exim
 --------------------
@@ -106,7 +106,7 @@ Version 4.70 / 4.71
  2. Experimental DCC support via dccifd (contributed by Wolfgang Breyha).
 
  3. There is now a bool{} expansion condition which maps certain strings to
-    true/false condition values (most likely of use in conjuction with the
+    true/false condition values (most likely of use in conjunction with the
     and{} expansion operator).
 
  4. The $spam_score, $spam_bar and $spam_report variables are now available
@@ -130,6 +130,12 @@ Version 4.70 / 4.71
  9. The transport_filter_timeout option now applies to SMTP transports too.
 
 
+Version 4.69
+------------
+
+ 1. Preliminary DKIM support in Experimental.
+
+
 Version 4.68
 ------------