aboutsummaryrefslogtreecommitdiff
path: root/doc/mailfromd.texi
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org.ua>2008-11-02 00:04:55 +0000
committerSergey Poznyakoff <gray@gnu.org.ua>2008-11-02 00:04:55 +0000
commit24fbd12566346861b0b57a329ff9d6a35250baea (patch)
tree7d2d6b2d83ca1ba204755d5d503d86ab707b246f /doc/mailfromd.texi
parentbb0b0e2f5002e2c0e3badc85045daa701f21fe80 (diff)
downloadmailfromd-24fbd12566346861b0b57a329ff9d6a35250baea.tar.gz
mailfromd-24fbd12566346861b0b57a329ff9d6a35250baea.tar.bz2
New functions: replstr, ml_header, sa_format_score, sa_format_report_header
* mflib/sa.mf: New file. * mflib/Makefile.am (inc_DATA): Add sa.mf * mfd/bi_string.m4 (replstr): New function. * doc/mailfromd.texi: Document new functions. * NEWS: Update. git-svn-id: file:///svnroot/mailfromd/trunk@1716 7a8a7f39-df28-0410-adc6-e0d955640f24
Diffstat (limited to 'doc/mailfromd.texi')
-rw-r--r--doc/mailfromd.texi145
1 files changed, 125 insertions, 20 deletions
diff --git a/doc/mailfromd.texi b/doc/mailfromd.texi
index 058e53ef..40995a82 100644
--- a/doc/mailfromd.texi
+++ b/doc/mailfromd.texi
@@ -5681,6 +5681,34 @@ localpart "gray@@gnu.org.ua" @result{} "gray"
@end smallexample
@end deftypefn
+@deftypefn {Built-in Function} string ml_header (string @var{text})
+ If @var{text} is a multi-line string, the function reformats it, by
+inserting a horizontal tabulation character (@acronym{ASCII} 09)
+before each newline (@acronym{ASCII} 10). Use this function to format
+multi-line strings for use in message headers. For example:
+
+@smallexample
+ string text <<EOT
+ A multi-line
+ text
+ EOT
+
+ add "X-String" ml_header(%text)
+@end smallexample
+
+@xref{Actions, Header manipulation actions}, and
+@xref{Header modification functions}.
+@end deftypefn
+
+@deftypefn {Built-in Function} string replstr (string @var{s}, number @var{n})
+ Replicate a string, i.e. return a string, consisting of @var{s}
+repeated @var{n} times:
+
+@smallexample
+replstr("12", 3) @result{} "121212"
+@end smallexample
+@end deftypefn
+
@deftypefn {Built-in Function} string revstr (string @var{s})
Returns the string composed of the characters from @var{s} in
reversed order:
@@ -5776,6 +5804,36 @@ toupper "mail" @result{} "MAIL"
@end deftypefn
+@deftypefn {Library Function} string sa_format_score (number @var{code}, @
+ number @var{prec})
+Format @var{code} as a floating-point number with @var{prec} decimal
+digits:
+
+@smallexample
+sa_format_score(5000, 3) @result{} "5.000"
+@end smallexample
+
+@flindex sa.mf
+This function is convenient for formatting SpamAssassin scores for use
+in message headers and textual reports. It is defined in module
+@file{sa.mf}.
+
+@xref{sa, SpamAssassin}, for examples of its use.
+@end deftypefn
+
+@deftypefn {Library Function} string sa_format_report_header (string @var{text})
+Format a SpamAssassin report text in order to include it in a RFC 822
+header. This function selects the score listing from @var{%text}, and
+prefixes each line with @samp{* }. Its result looks like:
+
+@smallexample
+* 0.2 NO_REAL_NAME From: does not include a real name
+* 0.1 HTML_MESSAGE BODY: HTML included in message
+@end smallexample
+
+@xref{sa, SpamAssassin}, for examples of its use.
+@end deftypefn
+
@anchor{strip_domain_part}
@deftypefn {Library Function} string strip_domain_part (string @var{domain}, @
number @var{n})
@@ -7287,6 +7345,8 @@ socket:///var/run/filter.sock
@cindex SpamAssassin
@cindex spamd
@deftypefn {Built-in Function} boolean sa (string @var{url}, number @var{prec})
+@deftypefnx {Built-in Function} boolean sa (string @var{url}, @
+ number @var{prec}, number @var{report})
Pass the message to the SpamAssassin daemon (@code{spamd}) at
@var{url}. Return @code{true} if SpamAssassin considers it a spam,
@code{false} otherwise. The second arguments, @var{prec}, gives the
@@ -7304,22 +7364,78 @@ where @var{sa-var} stands for the SpamAssassin value and @var{var}
stands for the corresponding @command{mailfromd} one. @code{int()}
means taking the integer part.
+Optional third argument, @var{report}, is used to control what kind of
+data is returned in the @code{sa_keywords} variable. See below for
+its description.
+
The function returns additional information via the following
variables:
@table @code
@cindex sa_score, global variable
@item sa_score
-The spam score, converted to integer as described above.
+The spam score, converted to integer as described above. To convert
+it to a floating-point representation, use @code{sa_format_score}
+function (@pxref{String manipulation, sa_format_score}). See also the
+example below.
@cindex sa_threshold, global variable
@item sa_threshold
-The threshold, converted to integer.
+The threshold, converted to integer form.
@cindex sa_keywords, global variable
@item sa_keywords
-A string of comma-separated SpamAssassin keywords identifying this
-message.
+If @var{report} is not supplied or is null, this variable contains a
+string of comma-separated SpamAssassin keywords identifying this
+message, e.g.:
+
+@smallexample
+ADVANCE_FEE_1,AWL,BAYES_99
+@end smallexample
+
+Otherwise, if @var{report} is not null, the value of this variable is
+a @dfn{spam report} message. It is a multi-line textual message,
+containing detailed description of spam scores in a tabular form.
+It consists of the following parts:
+
+@enumerate
+@item A preamble.
+@item Content preview.
+
+The words @samp{Content preview}, followed by a colon and an excerpt
+of the message body.
+
+@item Content analysis details.
+
+It has the following form:
+
+@smallexample
+Content analysis details: (@var{score} points, @var{max} required)
+@end smallexample
+
+@noindent
+where @var{score} and @var{max} are spam score and threshold in
+floating point.
+
+@item Score table.
+
+The score table is formatted in three columns:
+
+@table @asis
+@item pts
+The score, as a floating point number with one decimal digit.
+
+@item rule name
+SpamAssassin rule name that contributed this score.
+
+@item description
+Textual description of the rule
+@end table
+
+The score table can be extracted from @code{sa_keywords} using
+@code{sa_format_report_header} function (@pxref{String manipulation,
+sa_format_report_header}), as illustrated in the example below.
+@end enumerate
@end table
The @code{sa} function can signal the following exceptions:
@@ -7344,29 +7460,18 @@ done
Here is a more advanced example:
@smallexample
-/* @r{Convert a SpamAssassin @code{code} back to fixed point form
- using the given number of digits (@code{prec})} */
-func to_double_str(string code, number prec) returns string
-do
- if length(%code) > %prec
- return substring(%code, 0, length(%code)-%prec-1) '.'
- substring(%code, length(%code)-%prec, -1)
- else
- return $1
- fi
-done
-
prog eom
do
set prec 3
- if sa("tcp://192.168.10.1:3333", %prec)
+ if sa("tcp://192.168.10.1:3333", %prec, 1)
add "X-Spamd-Status" "SPAM"
else
add "X-Spamd-Status" "OK"
fi
- add "X-Spamd-Score" to_double_str(%sa_score, %prec)
- add "X-Spamd-Threshold" to_double_str(%sa_threshold, %prec)
- add "X-Spamd-Keywords" %sa_keywords
+ add "X-Spamd-Score" sa_format_score(%sa_score, %prec)
+ add "X-Spamd-Threshold" sa_format_score(%sa_threshold, %prec)
+ add "X-Spamd-Keywords"
+ ml_header(sa_format_report_header(%sa_keywords))
done
@end smallexample

Return to:

Send suggestions and report system problems to the System administrator.