Use new version output format. Prepare for 4.0

git-svn-id: file:///svnroot/mailfromd/trunk@1419 7a8a7f39-df28-0410-adc6-e0d955640f24

1 files changed, 231 insertions, 27 deletions

diff --git a/doc/mailfromd.texi b/doc/mailfromd.texi
index 4d632b02..272a3dfe 100644
--- a/doc/mailfromd.texi
+++ b/doc/mailfromd.texi
@@ -85,7 +85,7 @@ senzill.}
 @page
 @contents
 
-@node Top, Intro, (dir), (dir)
+@node Top, Preface, (dir), (dir)
 
 @ifinfo
 @chapter Mailfromd
@@ -94,6 +94,8 @@ documents @command{mailfromd} Version @value{VERSION}.
 @end ifinfo
 
 @menu
+* Preface::                 Short description of this manual; brief
+                            history and acknowledgments.
 * Intro::                   Introduction to Mailfromd.
 * Building::                Building the Package.
 * Tutorial::                Mailfromd Tutorial.
@@ -113,13 +115,22 @@ Appendices
 @detailmenu
  --- The Detailed Node Listing ---
 
+Preface
+
+* History::                 Short @command{mailfromd} history. 
+* Conventions::             Typographical conventions.
+* Acknowledgments::         Acknowledgments.
+
 Introduction to @command{mailfromd}
 
 * Overview::                Mailfromd at a first glance
 * SAV::                     Principles of Sender Address Verification.
-* Limitations::             Limitations of Sender Address Verification.
 * Rate Limit::              Configuring Mail Sending Rate.
 
+Sender Address Verification.
+
+* Limitations::
+
 Building the Package
 
 * 31x-400::  Upgrading from 3.1.x to 4.0
@@ -266,16 +277,215 @@ Command Line Options.
 @end detailmenu
 @end menu
 
-@node Intro, Building, Top, Top
+@node Preface, Intro, Top, Top
+@unnumbered Preface
+
+  Simple Mail Transfer Protocol (@acronym{SMTP}) which is the standard
+for e-mail transmissions across the internet was designed in the
+good old days when nobody could even think of the
+possibility of e-mail being abused to send tons of unsolicited
+messages of dubious contents.  Therefore it lacks mechanisms that
+could have prevented this abuse (@dfn{spamming}), or at least could
+have made it difficult.  Attempts to introduce such mechanisms (such
+as @uref{http://tools.ietf.org/html/rfc2554, @acronym{SMTP-AUTH}
+extension}) are being made, but they are not in wide use yet and,
+probably, their introduction will not be enough to stop the e-mail
+abuse.  Spamming is today's grim reality and developers spend lots of
+time and efforts designing new protection measures against it.
+@command{Mailfromd} is one of such attempts.
+
+  The utility is designed to work with any @acronym{MTA} supporting
+@samp{Milter} protocol, such as @samp{Sendmail} or @samp{Postfix}.  It
+allows you to:
+
+@itemize @bullet
+@item
+Control whether messages come from trustworthy senders, using so
+called @dfn{callout} or @dfn{Sender Address Verification} (@pxref{SAV})
+mechanism.
+
+@item
+Prevent emails coming from forged addresses by use of @acronym{SPF}
+mechanism (@pxref{SPF Functions}).
+
+@item
+Limit connection and/or sending rates (@pxref{Rate Limit}).
+
+@item
+Use @dfn{black-}, @dfn{white-} and @dfn{greylisting} techniques.
+
+@item
+Invoke external programs or other mail filters.
+@end itemize
+
+@menu
+* History::                 Short @command{mailfromd} history. 
+* Conventions::             Typographical conventions.
+* Acknowledgments::         Acknowledgments.
+@end menu
+
+@node History
+@unnumberedsec Short history of @command{mailfromd}. 
+
+  The idea of the utility appeared in 2005, and its first version
+appeared soon afterwards.  Back then it was a simple implementation of
+Sender Address Verification (@pxref{SAV}) for @samp{Sendmail} (hence
+its name -- @command{mailfromd}) with rudimentary tuning
+possibilities.
+
+  After a short run on my mail servers, I discovered that the utility
+was not flexible enough.  It took less than a month to implement a
+configuration file that allowed to control program and data flow
+during the @samp{envfrom} @acronym{SMTP} state.  The new version, 1.0,
+appeared in June, 2005.
+
+  The next major release, 1.2 (1.1 contained mostly bugfixes),
+appeared two months later, which introduced @dfn{mail sending rate}
+control (@pxref{Rate Limit}).
+
+  The program evolved during the next year, which led to the
+release of version 2.0 in September, 2006.  This version was a major
+change in the main idea of the program.  Configuration file become a
+flexible filter script allowing to control almost all @acronym{SMTP}
+states.  The program supplied in the script file
+was compiled into a pseudo-code at startup, this code being subsequently
+evaluated each time the filter was invoked.  This caused a considerable
+speed-up in comparison with the previous versions, where the run-time
+evaluator was traversing the parse tree.  This version also introduced
+(implicitly, at the time), two separate data types for the entities
+declared in the script, which also played its role in the speed
+improvement (in the previous versions all data were considered 
+strings).  Lots of improvements were made in the filter language
+(@acronym{MFL}, @pxref{MFL}) itself, such as user-defined functions,
+@code{switch} statement, @code{catch} statement that allows to handle
+run-time errors, etc.  The set of built-in functions extended
+considerably.  A testsuite (using @i{DejaGNU}) was introduced in this version.
+
+  During this initial development period the limitations
+imposed by @command{libmilter} implementation became obvious.  Finally,
+I felt they were stopping further development, and decided
+that @command{mailfromd} should use its own @samp{Milter}
+implementation.  This new library, @command{libgacopyz} was the main
+new feature of the 3.0 release, that was released in November, 2006.
+Another major feature was the @option{--dump-macros} option and
+@option{macros} to @command{rc.mailfromd} script, that were intended
+to facilitate the configuration on @samp{Sendmail} side.  
+
+  The development of 3.@i{x} (more propery, 3.1.@i{x}) series
+concentrated mainly on bug-fixes, while the main development was done
+on the next branch.
+
+@FIXME{When 4.0 is out, change the data below:}
+  The version 4.0 appeared on @value{UPDATED}.  The full
+list of changes in this release is more than 500 lines long, so it is
+impractical to list them here.  In particular, this version introduced
+lots of new features in @acronym{MFL} syntax and the 
+library of useful @acronym{MFL} functions.  The runtime engine was
+also improved, in particular, stack space become expandable which
+eliminated many run-time errors.  This version also introduced the
+beginnings of the @acronym{MFL} module system.  The code generation
+was re-implemented to facilitate the introduction of object files in
+future versions.  Another new features in this release include 
+@acronym{SPF} support and @command{mtasim} utility, an @acronym{MTA}
+simulator designed for testing @command{mailfromd} scripts
+(@pxref{mtasim}).  The test suite in this version was made portable by
+rewriting it in @i{Autotest}.  
+  
+@node Conventions
+@unnumberedsec Typographical conventions
+
+@cindex Texinfo
+  This manual is written using Texinfo, the GNU documentation
+formatting language.  The same set of Texinfo source files is used to
+produce both the printed and online versions of the documentation.
+@ifnotinfo
+Because of this, the typographical conventions
+may be slightly different than in other books you may have read.
+@end ifnotinfo
+@ifinfo
+This section briefly documents the typographical conventions used in
+this manual.
+@end ifinfo
+
+  Examples you would type at the command line are preceded by the common
+shell primary prompt, @samp{$}.  The command itself is printed @kbd{in
+this font}, and the output it produces @samp{in this font}, for
+example:
+
+@smallexample
+$ @kbd{mailfromd --version}
+mailfromd (mailfromd @value{VERSION})
+@end smallexample
+
+In the text, the command names are printed @command{like this},
+command line options are displayed in @option{this font}.  Some
+notions are emphasized @emph{like this}, and if a point needs to be made
+strongly, it is done @strong{this way}.  The first occurrence of
+a new term is usually its @dfn{definition} and appears in the same
+font as the previous occurrence of ``definition'' in this sentence.
+File names are indicated like this: @file{/path/to/ourfile}.
+
+The variable names are represented @var{like this}, keywords and
+fragments of program text are written in @code{this font}.
+
+@node Acknowledgments
+@unnumberedsec Acknowledgments
+
+  Many people need to be thanked for their assistance in developing
+and debugging @command{mailfromd}.  After S.@: C.@: Johnson, I can say
+that this program ``@i{owes much to a most stimulating collection of
+users, who have goaded me beyond my inclination, and frequently beyond
+my ability in their endless search for "one more feature".  Their
+irritating unwillingness to learn how to do things my way has usually
+led to my doing things their way; most of the time, they have been right.}''
+
+  A real test for a program like @command{mailfromd} cannot be done
+but in conditions of production environment.  A decision to try it
+in these conditions is by no means an easy one, it requires courage
+and good faith in the intentions and abilities of the author.  To
+begin with, I would like to thank my contributors for these virtues.
+
+@cindex Jan Rafaj
+  Jan Rafaj has intrepidly been using @command{mailfromd} since its
+early releases and invested lots of efforts in improving the program
+and its documentation.  He is the author of many of the @acronym{MFL}
+library functions, shipped with the package.  Some of his ideas are
+still waiting in my implementation queue, while new ones are
+consistently arriving.  
+
+@cindex Peter Markeloff
+  Peter Markeloff patiently tested every @command{mailfromd}
+release and helped discover and fix many bugs.
+
+@cindex Zeus Panchenko
+  Zeus Panchenko contributed many ideas and gave lots of helpful
+comments.  He offered invaluable help in debugging and testing
+@command{mailfromd} on @acronym{FreeBSD} platform.  
+
+@cindex Sergey Afonin
+  Sergey Afonin proposed many improvements and new ideas.  He also
+invested a lot of his time in finding bugs and testing bugfixes. 
+
+  The following people (in alphabetical order) provided bug reports
+and helpful comments for various version of the program:
+@cindex Alan Dobkin
+@cindex Brent Spencer
+@cindex Jeff Ballard
+@cindex Nacho Gonz@'alez L@'opez
+@cindex Simon Christian
+Alan Dobkin, Brent Spencer, Jeff Ballard, Nacho Gonz@'alez L@'opez,
+Simon Christian.
+
+@node Intro, Building, Preface, Top
 @chapter Introduction to @command{mailfromd}
 
   @command{Mailfromd} is a general-purpose mail filtering daemon
-for @command{Sendmail}@footnote{See @uref{http://www.sendmail.org}}.
-It is able to filter both incoming and outgoing messages using
-criteria of arbitrary complexity.  Such criteria are supplied by the
-administrator in the form of a script file, written in @dfn{mail
-filtering language} (@acronym{MFL}).  The daemon interfaces with
-@command{Sendmail} using @command{Milter} protocol.
+for @command{Sendmail}@footnote{See @uref{http://www.sendmail.org}}
+and @command{Postfix}@footnote{See @uref{http://www.postfix.org}}.
+It is able to filter both incoming and outgoing messages using a
+filter program, written in @dfn{mail filtering language}
+(@acronym{MFL}).  The daemon interfaces with the @acronym{MTA} using
+@command{Milter} protocol.
 
   The program name -- @command{mailfromd} -- stems from the fact
 that the original implementation was a simple filter implementing the
@@ -305,8 +515,7 @@ said about a specific topic.
 @menu
 * Overview::                Mailfromd at a first glance
 * SAV::                     Principles of Sender Address Verification.
-* Limitations::             Limitations of Sender Address Verification.
-* Rate Limit::              Configuring Mail Sending Rate.
+* Rate Limit::              Controlling Mail Sending Rate.
 @end menu
 
 @node Overview
@@ -422,8 +631,12 @@ for strict method), it will not waste its time trying to reach @acronym{MX}
 servers again.  The records remain in the cache database for a certain
 time, after which they are discarded.
 
+@menu
+* Limitations::
+@end menu
+
 @node Limitations
-@section Limitations of Sender Address Verification
+@subsection Limitations of Sender Address Verification
 
 @cindex sender address verification, limitations
   Before deciding whether and how to use sender address
@@ -471,22 +684,16 @@ address domain will most probably not be the same as that of the @acronym{MTA}
 doing the forwarding. 
 
 @node Rate Limit
-@section Configuring Mail Sending Rate.
+@section Controlling Mail Sending Rate.
 
 @cindex mail sending rate, explained
 @cindex sending rate, explained
-  Another feature offered by @command{mailfromd} is controlling user
-@dfn{mail sending rate}.  A mail sending rate for a given user is
-defined as a number of messages he is allowed to send within the
-predefined interval of time. 
+  @dfn{Mail Sending Rate} for a given identity is defined as number of
+messages with this identity received within a predefined interval of
+time.  
 
-  @command{Mailfromd} filter language offers a special function 
-@code{rate} (@pxref{rate}) that computes the sending rate for the given
-user.  Depending on this value a decision can be made whether to
-accept or to refuse the message. 
-
-  For this feature to work, the package must be configured with
-@acronym{DBM} support (see the next chapter).
+  @acronym{MFL} offers a special function @code{rate} (@pxref{rate})
+that computes the sending rate for the given identity.  
 
 @node Building, Tutorial, Intro, Top
 @chapter Building the Package
@@ -9500,9 +9707,6 @@ Same as @option{--dump-xref}.  @xref{Logging and Debugging}.
 @itemx --help
 Give a short help summary.
 
-@item --license
-Print license and exit.
-
 @item --usage
 Give a short usage message.