Document scripts/lookups-Makefile for new lookups.

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

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index fc125b0c5ebfe6b0a5656b666c54ab9f0f5ead70..e049936a32fd17e46c42fd5f02bf08582c75232e 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -41,16 +41,19 @@
 .book
 
 . /////////////////////////////////////////////////////////////////////////////
-. These definitions set some parameters and save some typing. Remember that
-. the <bookinfo> element must also be updated for each new edition.
+. These definitions set some parameters and save some typing.
+. Update the Copyright year (only) when changing content.
 . /////////////////////////////////////////////////////////////////////////////
 
 .set previousversion "4.80"
-.set version "4.80"
+.include ./local_params
 
 .set ACL "access control lists (ACLs)"
 .set I   "&nbsp;&nbsp;&nbsp;&nbsp;"
 
+.macro copyyear
+2012
+.endmacro
 
 . /////////////////////////////////////////////////////////////////////////////
 . Additional xfpt markup used by this document, over and above the default
@@ -170,15 +173,23 @@
 <bookinfo>
 <title>Specification of the Exim Mail Transfer Agent</title>
 <titleabbrev>The Exim MTA</titleabbrev>
-<date>17 May 2012</date>
+<date>
+.fulldate
+</date>
 <author><firstname>Exim</firstname><surname>Maintainers</surname></author>
 <authorinitials>EM</authorinitials>
 <revhistory><revision>
-  <revnumber>4.80</revnumber>
-  <date>17 May 2012</date>
+  <revnumber>
+.version
+  </revnumber>
+  <date>
+.fulldate
+  </date>
   <authorinitials>EM</authorinitials>
 </revision></revhistory>
-<copyright><year>2012</year><holder>University of Cambridge</holder></copyright>
+<copyright><year>
+.copyyear
+           </year><holder>University of Cambridge</holder></copyright>
 </bookinfo>
 .literal off
 
@@ -367,7 +378,7 @@ contributors.
 
 .new
 .cindex "documentation"
-This edition of the Exim specification applies to version &version; of Exim.
+This edition of the Exim specification applies to version &version() of Exim.
 Substantive changes from the &previousversion; edition are marked in some
 renditions of the document; this paragraph is so marked if the rendition is
 capable of showing a change indicator.
@@ -1618,7 +1629,7 @@ for only a short time (see &%timeout_frozen_after%& and
 .section "Unpacking" "SECID23"
 Exim is distributed as a gzipped or bzipped tar file which, when unpacked,
 creates a directory with the name of the current release (for example,
-&_exim-&version;_&) into which the following files are placed:
+&_exim-&version()_&) into which the following files are placed:
 
 .table2 140pt
 .irow &_ACKNOWLEDGMENTS_& "contains some acknowledgments"
@@ -2314,7 +2325,7 @@ INFO_DIRECTORY, as described in section &<<SECTinsinfdoc>>& below.
 For the utility programs, old versions are renamed by adding the suffix &_.O_&
 to their names. The Exim binary itself, however, is handled differently. It is
 installed under a name that includes the version number and the compile number,
-for example &_exim-&version;-1_&. The script then arranges for a symbolic link
+for example &_exim-&version()-1_&. The script then arranges for a symbolic link
 called &_exim_& to point to the binary. If you are updating a previous version
 of Exim, the script takes care to ensure that the name &_exim_& is never absent
 from the directory (as seen by other processes).
@@ -33767,7 +33778,7 @@ at the end of its processing.
 A summary of the field identifiers that are used in log lines is shown in
 the following table:
 .display
-&`A   `&        authenticator name (and optional id)
+&`A   `&        authenticator name (and optional id and sender)
 &`C   `&        SMTP confirmation on delivery
 &`    `&        command list for &"no mail in SMTP session"&
 &`CV  `&        certificate verification status
@@ -33884,6 +33895,7 @@ selection marked by asterisks:
 &`*smtp_confirmation          `&  SMTP confirmation on => lines
 &` smtp_connection            `&  SMTP connections
 &` smtp_incomplete_transaction`&  incomplete SMTP transactions
+&` smtp_mailauth              `&  AUTH argument to MAIL commands
 &` smtp_no_mail               `&  session with no MAIL commands
 &` smtp_protocol_error        `&  SMTP protocol errors
 &` smtp_syntax_error          `&  SMTP syntax errors
@@ -34152,6 +34164,11 @@ the last 20 are listed, preceded by &"..."&. However, with the default
 setting of 10 for &%smtp_accep_max_nonmail%&, the connection will in any case
 have been aborted before 20 non-mail commands are processed.
 .next
+&%smtp_mailauth%&: A third subfield with the authenticated sender,
+colon-separated, is appended to the A= item for a message arrival or delivery
+log line, if an AUTH argument to the SMTP MAIL command (see &<<SECTauthparamail>>&)
+was accepted or used.
+.next
 .cindex "log" "SMTP protocol error"
 .cindex "SMTP" "logging protocol error"
 &%smtp_protocol_error%&: A log line is written for every SMTP protocol error
@@ -36308,6 +36325,12 @@ Add to &_src/config.h.defaults_& the line:
 Edit &_src/drtables.c_&, adding conditional code to pull in the private header
 and create a table entry as is done for all the other drivers and lookup types.
 .next
+Edit &_scripts/lookups-Makefile_& if this is a new lookup; there is a for-loop
+near the bottom, ranging the &`name_mod`& variable over a list of all lookups.
+Add your &`NEWDRIVER`& to that list.
+As long as the dynamic module would be named &_newdriver.so_&, you can use the
+simple form that most lookups have.
+.next
 Edit &_Makefile_& in the appropriate sub-directory (&_src/routers_&,
 &_src/transports_&, &_src/auths_&, or &_src/lookups_&); add a line for the new
 driver or lookup type and add it to the definition of OBJ.