Update docs

1 files changed, 55 insertions, 38 deletions

diff --git a/NEWS b/NEWS
index 42004da1..fe58010b 100644
--- a/NEWS
+++ b/NEWS
@@ -1,4 +1,4 @@
-Mailfromd NEWS -- history of user-visible changes. 2009-11-18
+Mailfromd NEWS -- history of user-visible changes. 2009-11-19
 Copyright (C) 2005, 2006, 2007, 2008, 2009 Sergey Poznyakoff
 See the end of file for copying conditions.
 
@@ -9,36 +9,41 @@ Version 5.9.91 (Git)
 
 * Overview
 
-  This release is aimed to fix several logical inconsistencies that
-affected the previous versions.  Some features that have been
-previously declared as deprecated are now removed, whereas some
-obsolete features are marked deprecated now and will be removed in
-the future version.  These changes are described in the chapter
-`Incompatible changes'.
+  This release is aimed to fix the logical inconsistencies that  
+affected the previous versions, in preparation to the new major
+release that will follow.  Some features that have been previously
+declared as deprecated are now removed, whereas some obsolete features
+are marked deprecated now and will be removed in the future version.
+These changes are described in the chapter `Incompatible changes'.
 
-  Special mechanism is provided to facilitate migration to the new
+  A special mechanism is provided to facilitate migration to the new
 syntax.  It is described in chapter `Upgrade procedure'.  Please read
 it carefully before upgrading.
 
 * Incompatible changes
   
-The most important one is that until version 5.2, the filter script
-file contained both the actual filter script, and the run-time
-configuration for mailfromd (in the form of `#pragma option' and
-`#pragma database' statements). The new version fixes it and separates
-run-time configuration from the filter script by introducing a special
-configuration file `mailfromd.conf'. (see the docs, chapter "Mailfromd
-Configuration").
+  Historically, the filter script file contained both the actual filter
+source code, and run-time configuration directives for mailfromd (in
+the form of `#pragma option' and `#pragma database' statements). Such
+a mixture of concerns is counter-productive in the long run.
+
+  Starting from version 6.0 the two concerns are separated.  The filter
+source code is kept in the file `$sysconfdir/mailfromd.mf' (see
+below), and the run-time configuration is provided by the
+configuration file `$sysconfdir/mailfromd.conf'. (see the docs,
+chapter "Mailfromd Configuration"). Thus, changing run-time
+configuration does not imply changing the filter program itself and
+vice-versa. This allows to implement a full-fledged module system.
 
   Consequently, the `#pragma option' and `#pragma database'
 statements are deprecated.
 
-  The second problem was that the default filter script file had
-`.rc' suffix, which usually marks a configuration file, not
-the source.  Starting with this release the script file is renamed to
-`mailfromd.mf'.  In the absence of this file, the legacy file
-`mailfromd.rc' is recognized and parsed.  This ensures backward
-compatibility.
+  In previous versions, the filter script file had the `.rc' suffix.
+This was wrong, because this suffix usually marks a configuration
+file, which `mailfromd.rc' was not.  Starting with this release the
+script file is renamed to `mailfromd.mf'.  For compatibility reasons,
+in the absence of this file, the legacy file `mailfromd.rc' is
+recognized and parsed.
 
 ** Pies withdrawn
 
@@ -81,8 +86,19 @@ supported but issues a deprecation warning.  It will be removed in
 future versions. Use `.' operator instead.  See `Explicit
 concatenation', below.
 
-Notice, however that this change does not affect adjacent
-literals, which are implicitly concatenated as before.
+Notice, however, that this change does not affect adjacent
+literals, which are implicitly concatenated as before.  In other
+words, the following statement is OK:
+
+  set foo "string" "ent test"
+
+but the following is not:
+  
+  set foo %bar %baz
+
+It should be written as
+
+  set foo %bar . %baz
 
 ** #require
 
@@ -100,7 +116,7 @@ In previous version, e_io was signalled in this case.
 for the new configuration system, follow the steps below:
 
 1. Run `mailfromd --lint'.  It will show a list of warnings,
-similar to this:
+similar to this (though, perhaps, much longer):
 
   mailfromd: Warning: using legacy script file
     /usr/local/etc/mailfromd.rc
@@ -114,14 +130,14 @@ similar to this:
   mailfromd: Info: run script /tmp/mailfromd-newconf.sh
     to fix the above warnings
 
-2. At the end of the run mailfromd will create a shell script
+2. At the end of the run mailfromd creates a shell script
 named `/tmp/mailfromd-newconf.sh'.  To fix the above warnings,
 run this script:
 
 $ sh /tmp/mailfromd-newconf.sh
 
-The script will edit all MFL sources that need upgrading.  A backup
-copy of each source file will be created.  The name of the backup
+It will edit and patch all MFL sources that need upgrading.  A backup
+copy of each source file will be created.  The name of each backup
 file is constructed by appending `.bak' to the original file name.
 
 3. Now retry `mailfromd --lint'. It should show no warnings now.
@@ -151,9 +167,9 @@ the corresponding type name, e.g.:
 A module is a logically isolated part of code that implements a
 separate concern or feature.  Each module occupies a separate
 compilation unit (i.e. file).  The functionality provided by
-a module is incorporated into the main program by "requiring"
+the module is incorporated into the main program by "requiring"
 this module or by "importing" the desired components from it.
-To require a module the following syntax is used:
+To require a module, use the following syntax:
 
   require MODNAME
 
@@ -171,11 +187,11 @@ syntax:
 where MODNAME is as described above, and NAMES is a comma-separated
 list of the symbol names to import.  Note that the final dot is
 mandatory.  Each NAME may also be a regular expression, in which case
-only symbols that match it will be imported, or a transform
+only those symbols that match the expression are imported, or a transform
 expression, which allows to rename imported symbols on the fly.  See
 Mailfromd Manual, subsection 4.20.1, "Declaring Modules", for a
 detailed description of the import syntax in general and transform
-expressions in particular. A couple of examples that illustrate the
+expressions in particular. A couple of examples to illustrate the
 concept:
 
 1) from A import foo,bar.
@@ -192,7 +208,7 @@ expression between //.
 
 From module A import all symbols that match the given regular
 expression and rename them, by prefixing each of them with the string
-'my_'. Thus, e.g. function `foo_1' will become `my_foo_1'.
+'my_'. Thus, e.g. function `foo_1' becomes `my_foo_1', etc.
 
 ** Module declaration
 
@@ -227,8 +243,8 @@ For the main script file, its value is "top".
 The qualifiers `static' or `public' may be used in front of the
 declaration to set the scope of visibility of the symbol.  Symbols
 defined as `static' are visible only within the current module,
-whereas the ones declared as `public' are visible outside.  The
-default scope is declared in the module declaration (see below).
+whereas the ones declared as `public' are visible outside as well.
+The default scope is declared in the module declaration (see below).
 Examples:
 
   static const ONE 1
@@ -239,12 +255,13 @@ See also `Precious variables', below.
 ** Global variables and Milter abort
 
 When Milter abort request is received, all global variables,
-except precious ones (see below), are reset to their initial values. In
-particular, this occurs when MTA receives the RSET command.
+excepting precious ones (see below), are reset to their initial
+values. In particular, this occurs when the MTA receives the RSET
+command.
 
 ** Precious variables
 
-New keyword "precious" may be used in front of a variable
+A new keyword "precious" may be used in front of a variable
 declaration to inform Mailfromd that this variable must retain
 its value across Milter abort requests. For example:
 
@@ -259,7 +276,7 @@ In this code, the value of rcpt_counter variable will reflect the
 total number of SMTP "RCPT TO" commands received during this session,
 including those that have been cancelled by RSET commands.
 
-`precious' may be combined with a scope qualifier.  In that case the
+`Precious' may be combined with a scope qualifier.  In that case the
 order of their appearance is irrelevant.  E.g. the two declarations
 below are equivalent: