updated documentation for message templates

diff --git a/src/spong-message.pl b/src/spong-message.pl
index 1afe86247746a2c5cab1dd0feefb8a0dc02c242f..2fd11ee7b18708447099559da85f58ce9949c792 100755 (executable)
--- a/src/spong-message.pl
+++ b/src/spong-message.pl
@@ -6,11 +6,13 @@ B<spong-message> - send out alerts when there is a problem
 
 =head1 SYNOPSIS
 
-B<spong-message> [B<--debug>] I<color> I<host> I<service> I<time> I<message> 
+B<spong-message> [B<--debug>] [B<--file> I<filename> | B<--message> I<"detailed
+message text"] I<color> I<host> I<service> I<time> I<message> 
 
-B<spong-message> [B<--debug>] B<--color|--status> I<color> B<--host> 
-I<hostname> B<--service> I<service> B<--time> I<time> B<--summary> I<summary>
-[B<--file> I<filename> | B<--message> I<detailed message>
+B<spong-message> [B<--debug>] B<--color|--status> I<color> B<--host>
+I<hostname> B<--service> I<service> B<--time> I<time> B<--summary> I<"<summary
+message text"> [B<--file> I<filename> | B<--message> I<"detailed message
+text">]
 
 =head1 DESCRIPTION
 
@@ -628,7 +630,7 @@ RULE:
 
       push @recipients,$c;
 
-   }  # End foreach $contact (...
+   }  # End foreach $contact (..
 
    if (@recipients) { push @okhistory,"$time + $color $host $service @recipients"; }
 
@@ -713,6 +715,10 @@ sub fill_in {
    $str =~ s/!!SUMMARY!!/$summary/g;
    $str =~ s/!!DETAILED!!/$message/g;
 
+   if ($str =~ /!!SHORTHOST!!/) {
+      ($tmp) = split /\./,$host;
+      $str =~ s/!!SHORTHOST!!/$tmp/g;
+   }
    if ($str =~ /!!CURTIME!!/) {
       $tmp = strftime($DATETIMEFMT,localtime());
       $str =~ s/!!CURTIME!!/$tmp/g;
@@ -858,7 +864,46 @@ __END__
 
 =head2 Options
 
-The following arguments must be given to B<spong-message>:
+=over
+
+=item B<--debug>
+
+Enables the printing of detailed debugging lines. Can be used in conjunction
+with B<--test> to test new messaging rules.
+
+=item B<--color|--status> I<color>
+
+Specified the status color of the event being reported. I<color> can be
+green, yellow or red.
+
+=item B<--host> I<hostname>
+
+The hostname of the server that is being reported on.
+
+=item B<--service> I<service>
+
+The name of the service that is being reported on.
+
+=item B<--time> I<time>
+
+The time of the event being reported in epoch format (i.e. time()).
+
+=item B<--summary> I<"summary text">
+
+This is the summary message field of the event being reported on.
+
+=item B<--file> I<filename>
+
+The name of a file to read the detailed message text from. If the I<filename> is S<'-'>, the text is read from stdin.
+
+=item B<--message> I<"message text">
+
+Detailed message text of the event being reported.
+
+=back
+
+The following parameters can be specifed on the command line with the
+accompanying command line parameters.
 
 =over
 
@@ -914,6 +959,61 @@ generated from all of the message rules that are matched. (See the
 L<spong.message> and L<spong.hosts> documentation for information on the file
 formats.)
 
+=head2 Message Templates
+
+Notification messages formats are determined by the templates in the
+C<%TEMPLATES> variable in the F<spong.message> file. Templates are seached
+according to the following order: 'contact:module', 'module', 'contact',
+'DEFAULT'. 
+
+Any text in a template string is added verbatim to the message. The list of
+substituation variables can be added to the template strings.
+
+=over
+
+=item !!HOST!!
+
+Full domain of the system of the event message.
+
+=item !!SHORTHOST!!
+
+The short host name of the system of the event message.
+
+=item !!COLOR!! and !!STATUS!!
+
+The status color ('green', 'yellow', or 'red') of the status message.
+
+=item !!WWWSPONG!!
+
+The $WWWSPONG url variable from the F<spong.conf> configuration variable.
+
+=item !!SUMMARY!!
+
+The summary message field in the status message.
+
+=item !!DETAILED!!
+
+The detailed message field of the status message. The value of this variable
+can be very large and have multple lines of text.
+
+=item !!CURTIME!!
+
+The current system time formatted according to $DATETIMEFMT
+
+=item !!DATE!!
+
+The date of the event message formatted according to $DATEFMT
+
+=item !!TIME!!
+
+The date of the event message formmated according to $TIMEFMT
+
+=item !!DATETIME!!
+
+The date/time of the event message formateed according to $DATETIMEFMT
+
+=back
+
 =head2 Messaging Modules
 
 B<spong-message> alerts people via the messaging modules that are installed.
@@ -939,8 +1039,9 @@ See L<spong.hosts> for a full description of all of the file formats.
 This file hold the rules that determine who is to be contacted, when and how
 often. There are some of the important configuration variables in the
 F<spong.message> file 1) how the messaging rules are to be scanned 
-(L<$RULES_MATCH|spong.message/"$RULES_MATCH">) and 2) the messaging rules
-(L<$MESSAGING_RULES|spong.message/"$MESSAGING_RULES">)
+(L<$RULES_MATCH|spong.message/"$RULES_MATCH">), 2) the messaging rules
+(L<$MESSAGING_RULES|spong.message/"$MESSAGING_RULES">), 3) how to format the
+messages being sent (L<%TEMPLATES|spong.message">).
 
 =back
 
@@ -990,7 +1091,15 @@ messaging code used in Spong versions 2.0 - 2.1 for compatibility.
 =item $MESSAGING_RULES
 
 L<$MESSAGING_RULES|spong.message/"$MESSAGING_RULES"> contains the rules that
-how, who and how often contacts are notified. See L<$MESSAGING_RULES|spong.message/"$MESSAGING_RULES"> for the full rules syntax.
+how, who and how often contacts are notified. See
+L<$MESSAGING_RULES|spong.message/"$MESSAGING_RULES"> for the full rules syntax.
+
+=item %TEMPLATES
+
+C<%TEMPLATES> determined how notification message are formatted. A template
+format consists a subject and message template strings. Both strings are not
+required as some message module will not require a subject or a body. See
+L<$MESSAGING_RULES|spong.message/"$MESSAGING_RULES"> for the full rules syntax.
 
 =back
 
@@ -1081,6 +1190,29 @@ Here are some examples to show you possible configurations.
 
     ];
 
+    %TEMPLATES = (
+
+      'DEFAULT' => { subject => 'spong - !!COLOR!! !!HOST!! !!SERVICE!!',
+                     body    =>
+    '!!DATETIME!!
+    !!COLOR!! !!HOST!! !!SERVICE!!
+    !!SUMMARY!!',
+                   },
+
+    'email'  => { subject => 'spong - !!COLOR!! !!HOST!! !!SERVICE!!',
+                  body    =>
+    'Host !!HOST!! service has been reported !!COLOR!!.
+    Summary: !!SUMMARY!!
+
+    Spong Web Page:      !!WWWSPONG!!
+    Service Detail Page: !!WWWSPONG!!/service/!!HOST!!/!!SERVICE!!
+
+    Status event details:
+    !!DETAILED!!
+    ',
+              },
+    );
+
 =back
 
 
@@ -1099,7 +1231,7 @@ No know bugs.
 =head1 SEE ALSO
 
 L<spong-server>, L<spong.hosts>, L<spong.conf>, L<spong.message>,
-L<messaging-modules>
+L<messaging-modules>, L<strftime(3)>
 
 =head1 AUTHOR