diff options
author | Sergey Poznyakoff <gray@gnu.org.ua> | 2007-09-06 13:05:56 +0000 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org.ua> | 2007-09-06 13:05:56 +0000 |
commit | 747e41693d7f2a808b3314cf82b3af38f98daf2d (patch) | |
tree | a023fea0ac96b2abdc2c98141d90a841544dbbf9 /doc | |
parent | afd4995c30c273a02f81e80a972688936907853a (diff) | |
download | wydawca-747e41693d7f2a808b3314cf82b3af38f98daf2d.tar.gz wydawca-747e41693d7f2a808b3314cf82b3af38f98daf2d.tar.bz2 |
Redo mail notifications
git-svn-id: file:///svnroot/wydawca/trunk@316 6bb4bd81-ecc2-4fd4-a2d4-9571d19c0d33
Diffstat (limited to 'doc')
-rw-r--r-- | doc/wydawca.texi | 143 |
1 files changed, 95 insertions, 48 deletions
diff --git a/doc/wydawca.texi b/doc/wydawca.texi index cc7b04c..b313e4f 100644 --- a/doc/wydawca.texi +++ b/doc/wydawca.texi @@ -969,6 +969,7 @@ from the name of the user @command{wydawca} runs as (usually @menu * mailer:: +* templates:: * admin notification:: * user notification:: @end menu @@ -977,7 +978,7 @@ from the name of the user @command{wydawca} runs as (usually @subsection Mailer @cindex mailer @kwindex mailer - To send messages @command{wydawca} uses a special logical entity + To send messages, @command{wydawca} uses a special logical entity called @dfn{mailer}. It is set in the configuration file using @code{mailer} keyword: @@ -1038,19 +1039,86 @@ mailer smtp://remote.server.net:24 @end group @end smallexample +@node templates +@subsection Message Templates +@cindex templates, notification messages +@cindex notification message template +@cindex message template + Each notification message is build from a message template, by +expanding any occurrances of @samp{%@{@var{name}@}} within it with the value +of macro-variable @var{name}. The sets of defined macro-variables +depend on the type of the notification and are described below. + +@kwindex define-message + Message templates are defined using @code{define-message} +statement. Its syntax is as follows: + +@smallexample +define-message @var{id} [-]@var{delimiter} +@var{lines} +@var{delimiter} +@end smallexample + + The @var{id} is a symbolic identifier used to refer to this message +in another configuration statements, @var{delimiter} is a delimiter +used to mark the end of the message template, and @var{lines} are any +number of lines that form the message template. If @var{delimiter} is +prefixed by a minus sign, any leading whitespace will be removed from +each template line, thus allowing to indent it in a natural +way. Furthermore, the @var{delimiter} itself is optional. If it is +omitted, the string @samp{end} is used to delimit the message. +The following example illustrates the simplest way to define a message +template: + +@smallexample +define-message my-message +Subject: test + +This is a test message. +end +@end smallexample + + Following is the same message template, but indented in a more +natural way. @samp{EOT} is used as a message delimiter: + +@smallexample +define-message my-message -EOT + Subject: test + + This is a test message. +EOT +@end smallexample + + It is important to notice, that the message template must supply +both @acronym{RFC} 822 headers, and message body, so it must always +consist of two parts, separated by a single empty line. If you do not +wish to supply any headers (which is unlikely, because a mail should +at least have a @code{Subject} header), simply begin the message text +with an empty line, like this: + +@smallexample +define-message my-message -EOT + + This is a test message. +EOT +@end smallexample + @node admin notification @subsection Admin Notification @kwindex mail-admin-stat Sending notifications to the system administrator is enabled by -@code{mail-admin-stat} statement. It takes as its argument a list of -statistics keywords as described in @ref{statistics}. The notification -will be sent only if statistics counters for at least one of the -requested categories are not zero. For example, the following -statement requires sending notifications only if there ocurred any -errors or access violation attempts, or any bad signature was uploaded: +@code{mail-admin-stat} statement. It takes two or more arguments. +The first argument supplies the identifier of a message template, +which should be previously defined by a @code{define-message}. +The rest of arguments is a list of statistics keywords as described in +@ref{statistics}. The notification will be sent only if statistics +counters for at least one of the requested categories are not +zero. For example, the following statement requires sending +notifications only if there ocurred any errors or access violation +attempts, or any bad signature was uploaded: @smallexample -mail-admin-stat errors access-violations bad-signatures +mail-admin-stat stat-msg errors access-violations bad-signatures @end smallexample @kwindex @@ -1063,36 +1131,8 @@ addresses, e.g.: admin-address root@@gnu.org.ua, ftp-adm@@gnu.org.ua @end smallexample -@kwindex admin-stat-message - Finally, the text of the notification is given using -@code{admin-stat-message} statement. As any block statement, -it ends with an @code{end} keyword on a line by itself. The lines -between @code{admin-stat-message} and @code{end} statements compose -the notification text. This text must consist of two parts, separated -by a single empty line. The part before the empty line gives any -@acronym{RFC} 822 headers, and the part after it supplies the email -body. It is important that both parts be always present. If you do not -wish to supply any headers, simply begin the message text with an -empty line. Following is a simple example of the -@code{admin-stat-message} statement: - -@smallexample -admin-stat-message -Subject: Wydawca stats - -On my recent run I have noticed some events that may -need your attention. - -Regards, -Wydawca -end -@end smallexample - -@cindex meta-variables in @code{admin-stat-message} - Any occurrence of @samp{%@{@var{name}@}} in the text is replaced -with the value of the meta-variable @var{name}. If such meta-variable -is not defined, this string is passed unchanged. The meta-variables -available for use in @code{admin-stat-message} text are: +@cindex meta-variables in admin notifications +The meta-variables available for use in admin notifications are: @multitable @columnfractions 0.50 0.50 @headitem Variable @tab Replaced with @@ -1129,11 +1169,10 @@ triplets. @item stat:rmsymlinks @tab Number of symbolic links removed. @end multitable - These macro-variables can make the notification text be more -informative, as shown in the following example: + An example definition of the admin notification template follows: @smallexample -admin-stat-message +define-message stat-msg Subject: Wydawca stats This is to notify you that my run on %@{date@} @@ -1496,21 +1535,29 @@ Sets the sender address for mail notifications. @xref{notification}, for more information on this statement. @end deffn -@deffn {Wydawca Statement} mail-admin-stat @var{condition-list} +@deffn {Wydawca Statement} mail-admin-stat @var{msg-id} @var{condition-list} Defines statistics categories that trigger administrator notifications. @xref{admin notification}. @end deffn -@deffn {Wydawca Statement} admin-stat-message -Defines the text of administrator notification message. +@deffn {Wydawca Statement} define-message +Define a message template. The full syntax is: -@xref{admin notification}. -@end deffn +@smallexample +define-message @var{id} [[-]@var{delimiter}] +@var{lines} +@var{delimiter} +@end smallexample + + The @var{id} supplies the template identifier, @var{lines} gives +message headers and body, separated by a newline. If @var{delimiter} +is prefixed by @samp{-}, any leading whitespace is removed from the +template lines. If @var{delimiter} is not given, @samp{end} is +assumed. -@deffn {Wydawca Statement} user-message @var{condition} -@FIXME{Description} +@xref{templates}, for more information on message templates. @end deffn @deffn {Wydawca Statement} mailer @var{url} |