diff options
author | Sergey Poznyakoff <gray@gnu.org.ua> | 2010-07-17 13:14:27 +0300 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org.ua> | 2010-07-17 13:14:27 +0300 |
commit | a0501ff13d8b93ece637cbc102175b2ed70713f2 (patch) | |
tree | 29ea9966598948e4cd852ed0e64ed90e5d40f912 | |
parent | 9180527c4855406faa08a5b8158d26dbf7d7d37b (diff) | |
download | mailfromd-a0501ff13d8b93ece637cbc102175b2ed70713f2.tar.gz mailfromd-a0501ff13d8b93ece637cbc102175b2ed70713f2.tar.bz2 |
Documentation: describe the changes since the last release and the upgrade procedure.
-rw-r--r-- | NEWS | 4 | ||||
-rw-r--r-- | doc/functions.texi | 1 | ||||
-rw-r--r-- | doc/macros.texi | 3 | ||||
-rw-r--r-- | doc/mailfromd.texi | 36 | ||||
-rw-r--r-- | doc/upgrade.texi | 80 | ||||
-rw-r--r-- | doc/values.texi | 6 |
6 files changed, 115 insertions, 15 deletions
@@ -1,4 +1,4 @@ -Mailfromd NEWS -- history of user-visible changes. 2010-07-14 +Mailfromd NEWS -- history of user-visible changes. 2010-07-17 Copyright (C) 2005, 2006, 2007, 2008, 2009, 2010 Sergey Poznyakoff See the end of file for copying conditions. @@ -13,7 +13,7 @@ The following features, that had been marked as deprecated in 6.0, are now removed: - old-style functional notation - - use of functional operators + - the use of functional operators - implicit concatenations - #pragma option - #pragma database diff --git a/doc/functions.texi b/doc/functions.texi index d05c5080..dc95b6d6 100644 --- a/doc/functions.texi +++ b/doc/functions.texi @@ -2017,6 +2017,7 @@ can write or read from it using this descriptor. Finally, when the resource is no longer needed, you can close it with a call to @code{close}. +@anchor{open} @deftypefn {Built-in Function} number open (string @var{name}) The @var{name} argument specifies the name of a resource to open and the access rights you need to have on it. The function returns a diff --git a/doc/macros.texi b/doc/macros.texi index f0aea564..cb68bd2b 100644 --- a/doc/macros.texi +++ b/doc/macros.texi @@ -1,3 +1,6 @@ +@c This file is part of the Mailfromd manual. +@c Copyright (C) 2008, 2009, 2010 Sergey Poznyakoff +@c See file mailfromd.texi for copying conditions. @macro xopindex{option,text} @opindex \option\, --\option\ @r{option, \text\} @end macro diff --git a/doc/mailfromd.texi b/doc/mailfromd.texi index 8c8a25d2..24caf572 100644 --- a/doc/mailfromd.texi +++ b/doc/mailfromd.texi @@ -944,6 +944,7 @@ files. These files are: @table @file @item @var{prefix}/sbin/mailfromd Main daemon. @xref{Invocation,, mailfromd}. + @item @var{prefix}/etc/mailfromd.mf Default main filter script file. It is installed only if it is not already there. Thus, if you are upgrading to a newer version of @@ -1706,6 +1707,7 @@ for a response to its @samp{MAIL} command more than 6 minutes, which is intolerable, because of the same 5 minute limit. Thus, the client will almost certainly break the session. +@anchor{callout server} @cindex callout server @cindex server, callout @cindex soft SMTP timeout @@ -4500,6 +4502,14 @@ Expands to the name of the current lexical context, i.e. the function or handler name. @end deftypevr +@deftypevr {Built-in constant} string __git__ +This built-in constant is defined for alpha versions only. +Its value is the Git tag of the recent commit corresponding to that +version of the package. If the release contains some uncommitted +changes, the value of the @samp{__git__} constant ends with +the suffix @samp{-dirty}. +@end deftypevr + @deftypevr {Built-in constant} number __line__ Expands to the current line number in the input source file. @end deftypevr @@ -7272,11 +7282,11 @@ exception-handling routines. @cindex @code{try} statement @cindex @code{catch} statement -@cindex try-catch construct +@cindex try--catch construct @cindex exception-handling routines @cindex exception handlers @kwindex catch - An exception-handling routine is introduced by a @dfn{try-catch} + An exception-handling routine is introduced by a @dfn{try--catch} statement, which has the following syntax: @smallexample @@ -7306,7 +7316,7 @@ exception is listed in @var{exception-list}, the execution is passed to the @var{handler-body}. If the exception is not listed in @var{exception-list}, it is handled as usual. - The following example shows a @samp{try-catch} construct used for + The following example shows a @samp{try--catch} construct used for handling seventual exceptions, signalled by @code{primitive_hasmx}. @smallexample @@ -7331,9 +7341,9 @@ done @cindex scope of a @code{catch} @cindex @code{catch} scope @cindex exception handler scope - The @samp{try-catch} statement can appear anywhere inside a function or + The @samp{try--catch} statement can appear anywhere inside a function or a handler, but it cannot appear outside of them. It can also be nested -within another @samp{try-catch}, in either of its parts. Upon exit from a +within another @samp{try--catch}, in either of its parts. Upon exit from a function or milter handler, all exceptions are restored to the state they had when it has been entered. @@ -7356,9 +7366,9 @@ following actions: @code{accept}, @code{continue}, @code{discard}, @code{reject}, @code{tempfail}. By default, @code{continue} is used. - It is not recommended to mix @samp{try-catch} constructs and + It is not recommended to mix @samp{try--catch} constructs and standalone catches. If a standalone catch appears within a -@samp{try-catch} statement, its scope of visibility is undefined. +@samp{try--catch} statement, its scope of visibility is undefined. @cindex returning from a catch @cindex returning from an exception handler @@ -7433,7 +7443,7 @@ done All variables remain visible within @code{catch} body, with the exception of positional arguments of the enclosing handler. To access positional arguments of a handler from the @code{catch} body, assign -them to local variables prior to the @samp{try-catch} construct, e.g.: +them to local variables prior to the @samp{try--catch} construct, e.g.: @smallexample @group @@ -8780,6 +8790,14 @@ statement to query a remote callout server: Use a callout server at @var{url} (@pxref{milter port specification}). @end deffn + You can also set a @dfn{global callout server}, which will be used +by all milter servers that do not set the @code{callout} statement: + +@deffn {Mailfromd Conf} callout-url url + Set global callout server. @xref{milter port specification}, for +allowed @var{url} formats. +@end deffn + @node conf-milter @section Milter Connection Configuration @@ -8919,7 +8937,7 @@ Declare @acronym{SMTP} timeouts of the given @var{type}, which may be Callout @acronym{SMTP} sessions initiated by polling functions, are controlled by two sets of timeouts: @samp{soft} and @samp{hard}. @dfn{Soft timeouts} are used by the mailfromd milter servers. @dfn{Hard -timeouts} are used by callout servers (@FIXME-pxref{callout servers}). +timeouts} are used by callout servers (@pxref{callout server}). When a soft timeout is exceeded, the calling procedure is delivered an @samp{e_temp_failure} exception and the session is scheduled for processing by a callout server. The latter re-runs the diff --git a/doc/upgrade.texi b/doc/upgrade.texi index 4d913e8c..3e6d74d3 100644 --- a/doc/upgrade.texi +++ b/doc/upgrade.texi @@ -1,6 +1,6 @@ @c Copyright (C) 2005, 2006, 2009, 2010 Sergey Poznyakoff @c Permission is granted to copy, distribute and/or modify this document -@c under the terms of the GNU Free Documentation License, Version 1.2 or +@c under the terms of the GNU Free Documentation License, Version 1.3 or @c any later version published by the Free Software Foundation; with no @c Invariant Sections, with the Front-Cover texts being ``Mailfromd Manual'', @c and with the Back-Cover Texts at your option. @@ -10,6 +10,7 @@ The following sections describe procedures for upgrading between the consecutive Mailfromd releases. @menu +* 600-700:: Upgrading from 6.0 to 7.0 * 5x0-600:: Upgrading from 5.x to 6.0 * 500-510:: Upgrading from 5.0 to 5.1 * 440-500:: Upgrading from 4.4 to 5.0 @@ -23,6 +24,81 @@ between the consecutive Mailfromd releases. * 1x-2x:: Upgrading from 1.x to 2.x @end menu +@node 600-700 +@appendixsec Upgrading from 6.0 to 7.0 +@cindex Upgrading from 6.0 to 7.0 + + The release 7.0 removes the features which were declared as obsolete +in 6.0 and introduces important new features, both syntactical, at the +@acronym{MFL} level, and operational. + + Unless your filter used any deprecated features, it should work +correctly after upgrade to this version. It will, however, issue +warning messages regarding the deprecated features (e.g. the use +of @samp{%} in front of identifiers, as described below). To +fix these, follow the upgrade procedure described in @ref{upgrade +procedure}. + + The removed features are: + +@itemize @bullet +@item Old-style functional notation +@item The use of functional operators +@item Implicit concatenations +@item #pragma option +@item #pragma database +@end itemize + + The @acronym{MFL} syntax has changed: it is no longer necessary to +use @samp{%} in front of a variable to get its value. To reference a +variable, simply use its name, e.g.: + +@smallexample +set x var + z +@end smallexample + + The old syntax is still supported, so the following statement +will also work: + +@smallexample +set x %var + %z +@end smallexample + + It will, however, generate a warning message. + + Of course, the use of @samp{%} to reference variables within a string +literal remains mandatory. + + Another important changes to @acronym{MFL} are user-defined +exceptions (@pxref{User-defined Exceptions}) and the @dfn{try--catch} +construct (@pxref{Catch and Throw,try--catch}). + + Several existing @acronym{MFL} functions have been improved. In +particular, it is worth noticing that the @code{open} function, when +opening a pipe to or from a command, provides a way to control where +the command's standard error would go (@pxref{open, standard error}). + + The @code{accept} function (or action) issues a warning if it would +cancel any modifications to the message applied by, e.g., +@code{header_add} and similar functions. @xref{Message modification +queue}, for a detailed discussion of this feature. + + The most important change in @command{mailfromd} operation is that +the version 7.0 is able to run several servers (@pxref{conf-server}). +Dedicated @dfn{callout servers} make it possible to run sender +verifications in background, using a set of long timeouts, as +prescribed by RFC 2822 (@pxref{SMTP Timeouts}). This diminishes +the number of false positives, allows for coping with servers showing +large delays and also reduces the number of callouts performed for +such servers. + + This release no longer includes the @command{smap} utility. It was +moved into a self-standing project, which by now provides much more +functionality and is way more flexible than this utility was. If you +are interested in using @command{smap}, visit +@uref{http://www.gnu.org.ua/software/smap}, for a detailed +information, including pointers to file downloads. + @node 5x0-600 @appendixsec Upgrading from 5.x to 6.0 @cindex Upgrading from 5.x to 6.0 @@ -54,6 +130,7 @@ in the @acronym{MFL} language. The support for unquoted literals is discontinued. This feature was marked as deprecated in version 3.0. +@anchor{deprecated-6.0} The following features are deprecated: @samp{#pragma option} (@histref{6,pragma_002doption,pragma-option} and @samp{#pragma database} (@histref{6,pragma_002ddatabase,pragma-database}) directives, the @@ -85,6 +162,7 @@ scripts from @samp{5.x}. When started, it will verbosely warn you about any deprecated constructs that are used in your filter sources and will create a script for upgrading them. +@anchor{upgrade procedure} To upgrade your filter scripts, follow the steps below: @enumerate 1 diff --git a/doc/values.texi b/doc/values.texi index 3991640d..3c139a57 100644 --- a/doc/values.texi +++ b/doc/values.texi @@ -1,6 +1,6 @@ -@set CONNECT-TIMEOUT 10 seconds -@set INITIAL-RESPONSE-TIMEOUT 30 seconds -@set IO-TIMEOUT 3 seconds +@c This file is part of the Mailfromd manual. +@c Copyright (C) 2008, 2009, 2010 Sergey Poznyakoff +@c See file mailfromd.texi for copying conditions. @set MILTER-TIMEOUT 7210 seconds @set DEFAULT-USER mail @set STACK-SIZE 4096 words |