aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org.ua>2010-07-17 13:14:27 +0300
committerSergey Poznyakoff <gray@gnu.org.ua>2010-07-17 13:14:27 +0300
commita0501ff13d8b93ece637cbc102175b2ed70713f2 (patch)
tree29ea9966598948e4cd852ed0e64ed90e5d40f912
parent9180527c4855406faa08a5b8158d26dbf7d7d37b (diff)
downloadmailfromd-a0501ff13d8b93ece637cbc102175b2ed70713f2.tar.gz
mailfromd-a0501ff13d8b93ece637cbc102175b2ed70713f2.tar.bz2
Documentation: describe the changes since the last release and the upgrade procedure.
-rw-r--r--NEWS4
-rw-r--r--doc/functions.texi1
-rw-r--r--doc/macros.texi3
-rw-r--r--doc/mailfromd.texi36
-rw-r--r--doc/upgrade.texi80
-rw-r--r--doc/values.texi6
6 files changed, 115 insertions, 15 deletions
diff --git a/NEWS b/NEWS
index 97114f01..1161afc3 100644
--- a/NEWS
+++ b/NEWS
@@ -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

Return to:

Send suggestions and report system problems to the System administrator.