summaryrefslogtreecommitdiffabout
path: root/doc/wydawca.texi
authorSergey Poznyakoff <gray@gnu.org.ua>2007-09-06 13:05:56 (GMT)
committer Sergey Poznyakoff <gray@gnu.org.ua>2007-09-06 13:05:56 (GMT)
commit747e41693d7f2a808b3314cf82b3af38f98daf2d (patch) (side-by-side diff)
treea023fea0ac96b2abdc2c98141d90a841544dbbf9 /doc/wydawca.texi
parentafd4995c30c273a02f81e80a972688936907853a (diff)
downloadwydawca-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/wydawca.texi') (more/less context) (ignore whitespace changes)
-rw-r--r--doc/wydawca.texi143
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}

Return to:

Send suggestions and report system problems to the System administrator.