1 files changed, 474 insertions, 0 deletions

diff --git a/doc/upgrade.texi b/doc/upgrade.texi
new file mode 100644
index 00000000..43663499
--- /dev/null
+++ b/doc/upgrade.texi
@@ -0,0 +1,474 @@
+@c Copyright (C) 2005, 2006, 2009 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 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. 
+
+
+The following sections describe procedures for upgrading
+between the consequtive Mailfromd releases. 
+
+@menu
+* 500-510::  Upgrading from 5.0 to 5.1
+* 440-500::  Upgrading from 4.4 to 5.0
+* 43x-440::  Upgrading from 4.3.x to 4.4
+* 420-43x::  Upgrading from 4.2 to 4.3.x
+* 410-420::  Upgrading from 4.1 to 4.2
+* 400-410::  Upgrading from 4.0 to 4.1
+* 31x-400::  Upgrading from 3.1.x to 4.0
+* 30x-31x::  Upgrading from 3.0.x to 3.1
+* 2x-30x::   Upgrading from 2.x to 3.0.x
+* 1x-2x::    Upgrading from 1.x to 2.x
+@end menu
+
+@node 500-510
+@appendixsec Upgrading from 5.0 to 5.1
+@cindex Upgrading from 5.0 to 5.1
+
+  Upgrading from 5.0 to 5.1 does not require any changes in your
+filter scripts.  Notice, however, the following important points:
+
+@itemize @bullet
+@item The semantics of @code{__preproc__} and @code{__statedir__}
+built-in constant is slightly different from what it used to be in
+5.0.  These constants now refer to the @emph{current} values of the
+preprocessor command line and program state directory,
+correspondingly.  This should not affect your script, unless you
+redefine the default values on run time.  If your script needs to
+access default values, use @code{__defpreproc__} and
+@code{__defstatedir__}, correspondingly (@pxref{Built-in constants}).
+The following example explains the difference between these:
+
+@smallexample
+$ cat pval.mf
+prog envfrom
+do
+  echo "Default value: " __defstatedir__
+  echo "Current value: " __statedir__
+done
+$ mailfromd --state-directory=/var/mfd --test pval.mf
+Default value: /usr/local/var/mailfromd
+Current value: /var/mfd
+@end smallexample
+
+@item If your filter uses the @code{rate} function,
+you might consider using the new function @code{rateok} or
+@code{tbf_rate} instead.  For a detailed discussion of these functions,
+see @ref{Sending Rate}.  
+
+@item If your script extensively uses database access functions, you
+might be interested in the new @code{#pragma dbprop} (@pxref{dbprop}).
+@end itemize
+
+@node 440-500
+@appendixsec Upgrading from 4.4 to 5.0
+@cindex Upgrading from 4.4 to 5.0
+
+  This version of Mailfromd requires
+@uref{http://www.gnu.org/software/mailutils, GNU mailutils} version
+2.0 or later. 
+
+  Upgrading from version 4.4 to 5.0 requires no additional
+changes. The major differences between these two versions are
+summarized below:
+  
+@enumerate 1
+@item Support for @samp{MeTA1}.
+
+@item New @samp{Mailutils} configuration file.
+
+@item New @acronym{MFL} functions.
+
+@enumerate a
+@item Message functions.  @xref{Message functions}.
+@item Mailbox functions.  @xref{Mailbox functions}.
+@item Mail body functions.  @xref{Mail body functions}.
+@item Header modification functions.  @xref{Header modification functions}.
+@item Envelope modification functions.  @xref{Envelope modification functions}.
+@item Quarantine functions.  @xref{Quarantine functions}.
+@item @code{getopt} and @code{varptr}.  @xref{getopt}.
+@item Macro access functions.  @xref{Macro access}.
+@item Character type functions.  @xref{Character Type}.
+@item New string functions (@pxref{String manipulation}):
+@code{verp_extract_user}, @code{sa_format_report_header},
+@code{sa_format_score}.
+@item Sequential access to DBM files. @xref{dbm-seq}.
+@end enumerate
+
+@item Changes in @acronym{MFL}
+
+@enumerate 1
+@item @xref{variadic functions}.
+@item @xref{function alias}.
+@end enumerate
+
+@item New operation mode: @xref{Run Mode}.
+
+@item Improved stack growth technique.
+
+The stack can be grown either by fixed size blocks, or
+exponentially. Upper limit can be specified. @xref{stacksize}.
+
+@item Milter ports can be specified using @acronym{URL} notation.
+
+@item Removed deprecated features.
+
+Support for some deprecated features has been withdrawn.  These are:
+
+@enumerate a
+@item Command line options @option{--ehlo},
+@option{--postmaster-email}, and @option{--mailfrom}.
+These became deprecated in version 4.0.  @xref{31x-400}.
+@end enumerate
+
+@end enumerate
+
+@node 43x-440
+@appendixsec Upgrading from 4.3.x to 4.4
+@cindex Upgrading from 4.3.x to 4.4
+
+  The deprecated @option{--domain} command line option has been
+withdrawn.  The short option @option{-D} now defines a preprocessor
+symbol (@pxref{Preprocessor Options}).
+
+  This version correctly handles name clashes between constants and
+variables, which remained unnoticed in previous releases.
+@xref{variable--constant shadowing}, for a detailed description of it.
+
+  To minimize chances of name clashes, all symbolic exception codes has
+been renamed by prefixing them with the @samp{e_}, thus, e.g. @code{divzero}
+became @code{e_divzero}, etc.  The @code{ioerr} exception code is renamed to
+@code{e_io}.  @xref{status.mfh}, for a full list of the new exception codes.
+
+@cindex @code{OLD_EXCEPTION_CODES}, preprocessor symbol
+  For consistency, the following most often used codes are available without
+the @samp{e_} prefix: success, not_found, failure, temp_failure.  This
+makes most existing user scripts suitable for use with version 4.4
+without any modification.  If your script refers to any exception
+codes other than these four, you can still use it by defining a
+preprocessor symbol @code{OLD_EXCEPTION_CODES}, for example:
+
+@smallexample
+$ mailfromd -DOLD_EXCEPTION_CODES
+@end smallexample
+
+@node 420-43x
+@appendixsec Upgrading from 4.2 to 4.3.x
+@cindex Upgrading from 4.2 to 4.3.x
+@cindex @code{DEFAULT_SYSLOG_ASYNC}, @command{configure} variable
+
+  Upgrading from 4.2 to 4.3 or 4.3.1 does not require any changes to
+your configuration and scripts. The only notable change in these
+versions is the following:
+
+  The asynchronous syslog implementation was reported to malfunction
+on some systems (notably on Solaris), so this release does not enable
+it by default.  The previous meaning of the @option{--enable-syslog-async}
+configuration option is also restored.  Use this option in order to
+enable asynchronous syslog feature.  To set default syslog
+implementation, use @code{DEFAULT_SYSLOG_ASYNC} configuration variable
+(@pxref{syslog-async}).
+
+The following deprecated features are removed:
+
+@enumerate
+@item @code{#pragma option ehlo} statement.
+
+It became deprecated in version 4.0.  @xref{pragma-option-ehlo}.
+
+@item @code{#pragma option mailfrom} statement.
+
+It became deprecated in version 4.0.  @xref{pragma-option-ehlo}.
+
+@item The @option{--config-file} command line option.
+
+It became deprecated in version 3.1.  @xref{30x-31x}.
+
+@item Built-in exception codes in catch statements.
+
+They are deprecated since version 4.0.  @xref{31x-400}.
+@end enumerate
+
+@node 410-420
+@appendixsec Upgrading from 4.1 to 4.2
+@cindex Upgrading from 4.1 to 4.2
+  Upgrading to this version does not require any special efforts.  You
+can use your configuration files and filter scripts without any
+changes. The only difference worth noticing is that starting from this
+version @command{mailfromd} is always compiled with asynchronous
+syslog implementation. The @option{--enable-syslog-async}
+configuration file option is still available, but its meaning has
+changed: it sets the @emph{default} syslog implementation to use
+(@pxref{syslog-async}). Thus, it can be used the same way it was in
+previous versions. You can also select the syslog implementation at
+run time, see @ref{Logging and Debugging, --syslog-async option}, for
+more detailed information.
+
+@node 400-410
+@appendixsec Upgrading from 4.0 to 4.1
+@cindex Upgrading from 4.0 to 4.1
+
+  Upgrading to this version does not require any special efforts.  You
+can use your configuration files and filter scripts without any changes.
+Notice only the following major differences between 4.1 and 4.0:
+
+@itemize @bullet
+@item Input files are preprocessed before compilation.
+@xref{Preprocessor}, for more information.
+
+@item There is a way to discern between a not-supplied optional
+parameter, and a supplied one, having null value (@pxref{defined}).
+
+@item The version 4.1 implements @code{sprintf} function
+(@pxref{String formatting}) and @code{printf} macro
+(@pxref{Preprocessor, printf}).
+
+@item Support for some obsolete features is withdrawn.  These include:
+
+@enumerate 1
+@item