data/TWiki/MailerContrib.txt,v
changeset 0 414e01d06fd5
child 1 e2915a7cbdfa
equal deleted inserted replaced
-1:000000000000 0:414e01d06fd5
       
     1 head	1.5;
       
     2 access;
       
     3 symbols;
       
     4 locks; strict;
       
     5 comment	@# @;
       
     6 
       
     7 
       
     8 1.5
       
     9 date	2008.01.22.03.21.28;	author TWikiContributor;	state Exp;
       
    10 branches;
       
    11 next	1.4;
       
    12 
       
    13 1.4
       
    14 date	2007.01.16.04.11.59;	author TWikiContributor;	state Exp;
       
    15 branches;
       
    16 next	1.3;
       
    17 
       
    18 1.3
       
    19 date	2006.06.25.16.26.31;	author TWikiContributor;	state Exp;
       
    20 branches;
       
    21 next	1.2;
       
    22 
       
    23 1.2
       
    24 date	2006.04.01.05.55.29;	author TWikiContributor;	state Exp;
       
    25 branches;
       
    26 next	1.1;
       
    27 
       
    28 1.1
       
    29 date	2006.02.01.12.01.22;	author TWikiContributor;	state Exp;
       
    30 branches;
       
    31 next	;
       
    32 
       
    33 
       
    34 desc
       
    35 @new-topic
       
    36 @
       
    37 
       
    38 
       
    39 1.5
       
    40 log
       
    41 @buildrelease
       
    42 @
       
    43 text
       
    44 @---+!! Mailer Contrib
       
    45 <a href="http://wikiring.com"><img src="%ATTACHURL%/logo.gif" style="float:right" /></a>
       
    46 
       
    47 Allows users to "subscribe" to regularly scheduled e-mails containing either:
       
    48    * A report on changes to all topics that have changed within a particular TWiki web.
       
    49    * A report on changes to a specific topic or set of topics the user can define flexibly.
       
    50    * The entire content of a specific topic or set of topics. This is referred to as "news mode."
       
    51    * The companion plugin (TWiki:Plugins.SubscribePlugin) lets you trivially add a "Subscribe to changes" button to topics
       
    52 
       
    53 <!--
       
    54 
       
    55    PLEASE DO NOT EDIT THIS TOPIC
       
    56 
       
    57    It is automatically generated from the subversion repository, and any changes
       
    58    you make will simply be overwritten the next time a release is generated.
       
    59 
       
    60    Instead, you could check your fix in, raise a bug in the Bugs web, or mail the author.
       
    61 -->
       
    62 
       
    63 
       
    64 <div class="twikiBroadcastMessage">WARNING: TWiki-4 only. If you want to use this extension with an earlier version of TWiki, please use [[http://twiki.org/cgi-bin/attach/Plugins/%TOPIC%?filename=%TOPIC%.zip&revInfo=1][revision 17 of the zip]].</div>
       
    65 
       
    66 %TOC%
       
    67 
       
    68 ---++ tools/mailnotify
       
    69 The central component of !MailerContrib is a script, =tools/mailnotify=, that generates and sends out the emails based on analysis of
       
    70    1 users' subcriptions listed in the <nop>%NOTIFYTOPIC%  topic in each web, and
       
    71    1  changes within the respective webs.
       
    72 This script is designed to be run from =cron= (or an equivalent off-line job scheduler), or from the command-line. 
       
    73 
       
    74 The script collates the changes emails so that each subscriber only receives one changes notification for all changes in all webs in the TWiki. Furthermore, users can elect to receive just summaries of changes, or the entire content of topics that have changed.
       
    75 
       
    76 Each web can optionally contain a topic called <nop>%NOTIFYTOPIC%.
       
    77 <!-- Included by %TWIKIWEB%.WebChangesAlert -->
       
    78 %STARTINCLUDE%
       
    79 Users subscribe to email notifications using their %TWIKIWEB%.WikiName or an alternative email address, and can specify the webs/topics they wish to track, WWhole groups of users can also be subscribed for notification.
       
    80 
       
    81 The general format of a subscription is:
       
    82 
       
    83 _three spaces_ =*= _subscriber_ [ =:= _topics_ ]
       
    84 
       
    85 Where _subscriber_ can be a %TWIKIWEB%.WikiName, an E-mail address, or a
       
    86 group name. If _subscriber_ contains any characters that are not legal in
       
    87 an email address, then it must be enclosed in 'single' or "double" quotes.
       
    88 
       
    89 _topics_ is an optional space-separated list of topics:
       
    90    * ... *without* a _Web._ prefix
       
    91    * ...that exist in this web.
       
    92 Users may further customize the specific content they will receive using the following controls:
       
    93    * You can use =*= in a topic name, where it is treated as a [[http://en.wikipedia.org/wiki/Wildcard_character][wildcard character]]. A =*= will match zero or more other characters - so, for example, =Fred*= will match all topic names starting with =Fred=, =*Fred= will match all topic names _ending_ with =Fred=, and =*= will match _all_ topic names.
       
    94    * Each topic may optionally be preceded by a '+' or '-' sign. The '+' sign means "subscribe to this topic". The '-' sign means "unsubscribe" or "don't send notifications regarding this particular topic". This allows users to elect to filter out certain topics. Topic filters ('-') take precedence over topic includes ('+') i.e. if you unsubscribe from a topic it will cancel out any subscriptions to that topic.
       
    95    * Each topic may optionally be followed by an integer in parentheses, indicating the depth of the tree of children below that topic. Changes in all these children will be detected and reported along with changes to the topic itself. _Note_ This uses the TWiki "Topic parent" feature.
       
    96    * Each topic may optionally be immediately followed by an exclamation mark ! or a question mark ? with no intervening spaces, indicating that the topic (and children if there is a tree depth specifier as well) should be mailed out as *complete topics* instead of change summaries. ! causes the topic to be mailed every time _even if there have been no changes_, and ? will mail the topic only if there have been changes to it. This only makes sense for subscriptions, and is intended for mailshotting regular newletters.
       
    97 
       
    98 For example:
       
    99 Subscribe Daisy to all changes to topics in this web.
       
   100 <verbatim>
       
   101    * daisy.cutter@@flowers.com
       
   102 </verbatim>
       
   103 Subscribe Daisy to all changes to topics that start with =Web=.
       
   104 <verbatim>
       
   105    * daisy.cutter@@flowers.com : Web*
       
   106 </verbatim>
       
   107 Subscribe Daisy to changes to topics starting with =Petal=, and their immediate children, !WeedKillers and children to a depth of 3, and all topics that match start with =Pretty= and end with =Flowers= e.g. =PrettyPinkFlowers=
       
   108 <verbatim>
       
   109    * DaisyCutter: Petal* (1) WeedKillers (3) Pretty*Flowers
       
   110 </verbatim>
       
   111 Subscribe !StarTrekFan to changes to all topics that start with =Star= *except* those that end in =Wars=, =sInTheirEyes= or =shipTroopers=.
       
   112 <verbatim>
       
   113    * StarTrekFan: Star* - *Wars - *sInTheirEyes - *shipTroopers
       
   114 </verbatim>
       
   115 Subscribe Daisy to the full content of !NewsLetter whenever it has changed
       
   116 <verbatim>
       
   117    * daisy@@flowers.com: NewsLetter?
       
   118 </verbatim>
       
   119 Subscribe buttercup to !NewsLetter and its immediate children, even if it hasn't changed.
       
   120 <verbatim>
       
   121    * buttercup@@flowers.com: NewsLetter! (1)
       
   122 </verbatim>
       
   123 Subscribe !GardenGroup (which includes Petunia) to all changed topics under !AllnewsLetters to a depth of 3. Then unsubscribe Petunia from the !ManureNewsLetter, which she would normally get as a member of GardenGroup:
       
   124 <verbatim>
       
   125    * GardenGroup: AllNewsLetters? (3)
       
   126    * petunia@@flowers.com: - ManureNewsLetter
       
   127 </verbatim>
       
   128 Subscribe =IT:admins= (a non-TWiki group defined by an alternate user mapping) to all changes to Web* topics.
       
   129 <verbatim>
       
   130    * 'IT:admins' : Web*
       
   131 </verbatim>
       
   132 
       
   133 A user may be listed many times in the <nop>%NOTIFYTOPIC% topic. Where a user has several lines in <nop>%NOTIFYTOPIC% that all match the same topic, they will only be notified about _changes_ that topic _once_ (though they will still receive individual mails for news topics).
       
   134 
       
   135 If a _group_ is listed for notification, the group will be recursively expanded to the e-mail addresses of all members.
       
   136 
       
   137 __%X% Warning: Because an email address is not linked to a user name, there is no way for TWiki to check access controls for email addresses. A user identified by an email address will only be sent change notifications if the topic they are asubscribed to is readable by guest users. You can limit what email addresses can be used in <nop>%NOTIFYTOPIC%, or even block use of emails altogther, using the ={MailerContrib}{EmailFilterIn} setting in =configure=.
       
   138 
       
   139 __%T% Tip:__ List names in alphabetical order to make it easier to find the names.
       
   140 %STOPINCLUDE%
       
   141 
       
   142 In the future it is intended that individual users will be able to control the frequency with which they are notified of topic changes, by changing a schedule specification in their home topic. However at present, the notification schedule is controlled by the frequency of activation of the =cron= job that runs the =mailnotify= script.
       
   143 
       
   144 Note that when using the "news mode" =!= or =?= specifiers the entire topic text is mailed out as HTML. The =newsletter= template is used to generate the content in this mail, using whatever skin is selected in the topic being mailed.
       
   145 
       
   146 In addition, the %<nop>STARTPUBLISH% and %<nop>STOPPUBLISH% markers used by TWiki:Plugins.PublishContrib to delimit the text to be published are respected in news mode.
       
   147 
       
   148 ---++ TWiki/Contrib/MailerContrib code library
       
   149 The second part of the module is a code library that provides the services for other applications to modify the subscription topics through a clean, well documented API. This allows (for example) plugin developers to add (for example) a "Register me for this newsletter" button to their pages. Developers should refer to the POD documentation for the !WebNotify class as their starting point.
       
   150 
       
   151 ---++ Installation Instructions
       
   152 You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server where TWiki is running.
       
   153 
       
   154 Like many other TWiki extensions, this module is shipped with a fully
       
   155 automatic installer script written using the Build<nop>Contrib.
       
   156    * If you have TWiki 4.2 or later, you can install from the =configure= interface (Go to Plugins->Find More Extensions)
       
   157       * See the [[http://twiki.org/cgi-bin/view/Plugins/BuildContribInstallationSupplement][installation supplement]] on TWiki.org for more information.
       
   158    * If you have any problems, then you can still install manually from the command-line:
       
   159       1 Download one of the =.zip= or =.tgz= archives
       
   160       1 Unpack the archive in the root directory of your TWiki installation.
       
   161       1 Run the installer script ( =perl &lt;module&gt;_installer= )
       
   162       1 Run =configure= and enable the module, if it is a plugin.
       
   163       1 Repeat for any missing dependencies.
       
   164    * If you are *still* having problems, then instead of running the installer script:
       
   165       1 Make sure that the file permissions allow the webserver user to access all files.
       
   166       1 Check in any installed files that have existing =,v= files in your existing install (take care *not* to lock the files when you check in)
       
   167       1 Manually edit !LocalSite.cfg to set any configuration variables.
       
   168 
       
   169 %IF{"defined 'SYSTEMWEB'" else="<div class='twikiAlert'>%X% WARNING: SYSTEMWEB is not defined in this TWiki. Please add these definitions to your %MAINWEB%.TWikiPreferences, if they are not already there:<br><pre>   * <nop>Set SYSTEMWEB = %<nop>TWIKIWEB%<br>   * <nop>Set USERSWEB = %<nop>MAINWEB%</pre></div>"}%
       
   170 
       
   171    * To make sure the installation was successful, run the =mailnotify= script from the command line, with no parameters. In this case it will print out what it would have done to =STDOUT=.
       
   172 *Additional settings*
       
   173    * You can change the regular expression that matches email addresses in <nop>%NOTIFYTOPIC% using the ={MailerContrib}{EmailFilterIn} setting in =configure=. This allows you to limit the domains to which emails can be sent, or even block email addresses altogether.
       
   174 
       
   175 ---+++ Setting up your cron job(s)
       
   176 You need to set up a =cron= (or equivalent) job to run the =tools/mailnotify= perl script.
       
   177 
       
   178 The script is used as follows: <code>perl -I _bin_ mailnotify [-q] [-news] [ <i>web1 web2 ... webN</i> ]</code>
       
   179 | _bin_ | path to the TWiki bin directory, so that the script can find the rest of TWiki. |
       
   180 | =-q= | Don't print progress information |
       
   181 | =-news= | Run in news mode (process !NewsNotify instead of <nop>%NOTIFYTOPIC%) |
       
   182 | <code><i>web1 web2 ... webN</i></code> | List of webs to process, separated by spaces or commas. The default is to process all webs. Wildcards (*) are supported. |
       
   183 For example, assuming TWiki was installed at =/usr/local/twiki=, this cron entry:
       
   184 <verbatim>
       
   185 0 0 * * * cd /usr/local/twiki && perl -I bin tools/mailnotify -q Public Private
       
   186 </verbatim>
       
   187 will generate change notifications for the =Public= and =Private= webs every night at midnight. (Google for =crontab= for more information on what all the =0 0 * * *= fields mean)
       
   188 <verbatim>
       
   189 0 0 * * * cd /usr/local/twiki && perl -I bin tools/mailnotify -q -Sandbox
       
   190 </verbatim>
       
   191 will generate change notifications for all webs, except the =Sandbox= web.
       
   192 <verbatim>
       
   193 0 0 * * 0 cd /usr/local/twiki && perl -I bin tools/mailnotify -news
       
   194 </verbatim>
       
   195 will generate newsletters from *all* webs every week on midnight Saturday.
       
   196 
       
   197 <!--
       
   198 	* Set STUB = TWiki::Contrib::Mailer
       
   199 	* Set SHORTDESCRIPTION = Supports e-mail notification of changes.
       
   200 -->
       
   201 ---++ Developer Notes
       
   202 The changes mails sent to users are based on a TWiki template called =mailnotify=. This template must contain the following definitions. 
       
   203 | =HTML:before= | Section of a HTML mail before the changes |
       
   204 | =HTML:middle= | Repeated in a HTML mail for each change |
       
   205 | =HTML:after= | Section of a HTML mail after the changes |
       
   206 | =PLAIN:before= | Section of a plain text mail before the changes |
       
   207 | =PLAIN:middle= | Repeated in a plain text mail for each changes |
       
   208 | =PLAIN:after= | Section of a plain text mail after the changes |
       
   209 | =MailNotifyBody= | All the above are embedded in this. %<nop>HTML_TEXT% expands to the HTML obtained by expanding the =HTML:*= templates, and %<nop>PLAIN_TEXT% from the =PLAIN:*= templates. |
       
   210 The default template sends multipart mails containing both HTML and plaintext versions. You can easily provide a custom version of this template using a local skin.
       
   211 
       
   212 Newsletters are sent after formatting using the standard =view= template, using whatever skin is selected in the topic being mailed.
       
   213 
       
   214 ---+++ Contrib Info
       
   215 
       
   216 Another great TWiki extension from the <a style="text-decoration:none" href="http://wikiring.com"><img src="%ATTACHURLPATH%/wikiring.png" alt="" /> *WikiRing* </a> - working together to improve your wiki experience!
       
   217 
       
   218 Many thanks to the following sponsors for supporting this work:
       
   219    * [[http://www.windriver.com][Wind River]]
       
   220    * [[http://wikigardens.com][WikiGardens]]
       
   221 
       
   222 |  Author: | TWiki:Main/CrawfordCurrie (http://c-dot.co.uk) |
       
   223 |  Copyright &copy;: | 2004, Wind River Systems; 2006, http://WikiRing.com |
       
   224 |  License: | GPL |
       
   225 |  Version: | 16078 (22 Jan 2008) |
       
   226 |  Change History: | |
       
   227 |  2 Nov 2007 | Bugs:Item4818: added quotes to support non-alphabetic and other wierd group names Bugs:Item4887: corrected minor rendering error Bugs:Item4917: removed dependence on symbolic web names |
       
   228 |  9 Sep 2007 | Bugs:Item4326 workaround for possible error in !WebNotify API in old releases, Should not affect most users. |
       
   229 |  6 Sep 2007 | Bugs:Item4488 doc tweaks |
       
   230 |  14550 | Bugs:Item4461 - 'Changed' link now points to most recent changes, not the entire history |
       
   231 |  22 Jun 2007 | Bugs:Item4284 - added access control checks and email filter |
       
   232 |  21 May 2007 | Bugs:Item3969 - 8bit email fix (TWiki:Main.WillNorris) |
       
   233 |  13623 | Bugs:Item4014 no changes was resetting the notify time to 0. Thanks to TWiki:Main.JeffCrawford for nailing this down. |
       
   234 |  12496 | <a rel='nofollow' href='http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item3415'>Item3415</a> mailnotify did not send notifications to intranet users because of wrong call to findUser. |
       
   235 |  11672 | Added newsletter support, after much harassment from TWiki:Main.LynnwoodBrown |
       
   236 |  11534 | <a rel='nofollow' href='http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item2153'>Item2153</a> Clarified docs.  <a rel='nofollow' href='http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item2698'>Item2698</a> Improved error reporting. |
       
   237 |  8808 | <a rel='nofollow' href='http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item1654'>Item1654</a>  mailnotify must enter the command_line context |
       
   238 |  8625 | <a rel='nofollow' href='http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item1508'>Item1508</a>  Making the dashes in the separatator clearer |
       
   239 |  8606 | <a rel='nofollow' href='http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item1508'>Item1508</a>  MailerContrib: Brushing up HTML mailnotify template |
       
   240 |  8602 | <a rel='nofollow' href='http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item1508'>Item1508</a>  MailerContrib: Cleaning up plaintext e-mail template, removing TEXTAREA |
       
   241 |  8522 | <a rel='nofollow' href='http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item1511'>Item1511</a>  arguments to getScriptUrl in wrong order :-( |
       
   242 |  8434 | <a rel='nofollow' href='http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item1465'>Item1465</a>  Fix 'TWiki.' to '%TWIKIEB%.' |
       
   243 |  8398 | <a rel='nofollow' href='http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item1460'>Item1460</a>  polished up the comment a bit |
       
   244 |  8308 | <a rel='nofollow' href='http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item1362'>Item1362</a>  moving mailnotify cron script |
       
   245 |  7848 | <a rel='nofollow' href='http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item1167'>Item1167</a>  forced all mail operations to generate absolute URLs |
       
   246 |  7568 | <a rel='nofollow' href='http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item910'>Item910</a>  use SCRIPTURL{view} instead of complex url expr |
       
   247 |  6864 | <a rel='nofollow' href='http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item624'>Item624</a>  mailer templates moved the the right places |
       
   248 |  6861 | <a rel='nofollow' href='http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item624'>Item624</a>  Added proper templates support for plain text mails |
       
   249 |  6809 | <a rel='nofollow' href='http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item623'>Item623</a>  don't print anything if verbosity is switched off. |
       
   250 |  6659 | <a rel='nofollow' href='http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item528'>Item528</a>  Updated MailerContrib. it's working and the sendmail parameter is used. |
       
   251 |  6474 | <a rel='nofollow' href='http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item420'>Item420</a>  removed spurious remove_obsolete_locks from MailerContrib |
       
   252 |  5924 | <a rel='nofollow' href='http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item153'>Item153</a>  fix mail URL-fixing scheme |
       
   253 |  5269 | Minor doc fixes |
       
   254 |  5266 | Doc tidy-ups, added filtering of _ webs, added obsolete lock script |
       
   255 |  5264 | Changed default to add web name to user name (I hope) |
       
   256 |  5263 | Minor doc tidyups |
       
   257 |  5261 | Documentation changes, and fixed to scan all webs. |
       
   258 |  5253 | runnable as CGI script, minor bugfixes, removed dependency on DBCacheContrib |
       
   259 |  5234 | Minor doc changes |
       
   260 |  5231 | Made a change an object, added unit tests to CVS, lots of testing. |
       
   261 |  4 March 2005 | 1.010 Dakar release ready. |
       
   262 |  12 Oct 2004 | 1.004 Added support for anti-subscriptions. Doc fixes from TWiki:Main.PeterThoeny. Bug fixes to permissions code. Back-off and retry if the mailer can't be reached (should really be in Net::sendEmail) |
       
   263 |  6 Oct 2004 | 1.003 Excluded _ webs from processing, added =bin/remove_obsolete_locks= for full reverse-compatibility |
       
   264 |  1 Oct 2004 | 1.002 Peter<nop>Thoeny provided additional documentation |
       
   265 |  27 Sep 2004 | 1.001 runnable as CGI script, minor bugfixes, removed dependency on DB<nop>CacheContrib |
       
   266 |  8 Sep 2004 | 1.000 Initial version |
       
   267 |  Home: | TWiki:Plugins/%TOPIC% |
       
   268 |  Feedback: | TWiki:Plugins/%TOPIC%Dev |
       
   269 |  Appraisal: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Appraisal |
       
   270 
       
   271 %META:FILEATTACHMENT{name="wikiringlogo20x20.png" attr="h" comment="" version="1"}%
       
   272 %META:FILEATTACHMENT{name="logo.gif" attr="h" comment="" version="1"}%
       
   273 @
       
   274 
       
   275 
       
   276 1.4
       
   277 log
       
   278 @buildrelease
       
   279 @
       
   280 text
       
   281 @d1 2
       
   282 a2 2
       
   283 %META:TOPICINFO{author="TWikiAdminGroup" date="1168425636" format="1.1" version="4"}%
       
   284 ---+!! %TOPIC%
       
   285 d4 1
       
   286 a4 1
       
   287 Add-on to the TWiki kernel that allows users to "subscribe" to regularly scheduled e-mails containing either:
       
   288 d8 1
       
   289 d21 1
       
   290 a21 1
       
   291 *WARNING: TWiki-4 only. If you want to use this extension with an earlier version of TWiki, please see [[http://twiki.org/cgi-bin/view/Plugins/%TOPIC%?rev=1.17][here]]*
       
   292 d25 2
       
   293 a26 2
       
   294 ---+ <code>tools/mailnotify</code>
       
   295 The central component of MailerContrib is a script, =tools/mailnotify=, that generates and sends out the emails based on analysis of
       
   296 d36 1
       
   297 a36 1
       
   298 Users subscribe to email notifications using their %TWIKIWEB%.WikiName or an alternative email address, and can specify the webs/topics they wish to track using one of these bullet list formats:
       
   299 d38 14
       
   300 a51 11
       
   301 _three spaces_ * [ _webname_ . ] _wikiName_ - _SMTP mail address_ <br />
       
   302 _three spaces_ * [ _webName_ . ] _wikiName_ <br />
       
   303 _three spaces_ * _SMTP mail address_ <br />
       
   304 _three spaces_ * _SMTP mail address_ : _topics_ <br />
       
   305 _three spaces_ * [ _webname_ . ] _wikiName_ : _topics_
       
   306 
       
   307 In the above examples, _topics_ is a space-separated list of topic names. The user may further customize the specific content they will receive using the following formats:
       
   308    * Specify topics without a _Web._ prefix
       
   309    * Topics must exist in this web.
       
   310    * Topics may be specified using * wildcards
       
   311    * Each topic may optionally be preceded by a '+' or '-' sign. The '+' sign means "subscribe to this topic" (the same as not putting anything). The '-' sign means "unsubscribe" or "don't send notifications regarding this topic". This allows users to elect to filter out certain topics (and their children, to an arbitrary depth). Topic filters ('-') take precedence over topic includes ('+').
       
   312 d53 1
       
   313 a53 1
       
   314    * Each topic may optionally be immediately followed by an exclamation mark ! or a question mark ? with no intervening spaces, indicating that the topic (and children if there is a tree depth specifier as well) should be mailed out as *complete topics* instead of change summaries. ! causes the topic to be mailed every time even if there have been no changes, ? will mail the topic only if there have been changes to it. This only makes sense for subscriptions.
       
   315 d60 1
       
   316 a60 1
       
   317 Subscribe Daisy to all changes in all webs that start with =Web=.
       
   318 d62 1
       
   319 a62 1
       
   320    * daisy.cutter@@flowers.com: Web*
       
   321 d85 5
       
   322 d92 3
       
   323 a94 1
       
   324 If a _TWiki group_ is listed for notification, the group will be recursively expanded to the e-mail addresses of all members.
       
   325 d101 1
       
   326 a101 130
       
   327 %RED% __Note__ =mailnotify= ignores permissions in webs. It is entirely possible for a user to get added to one of the subscription topics in a web, when they are not authorised to view the topics in that web. This could result in them having access to sensitive information, particularly with news mode. %ENDCOLOR%
       
   328 
       
   329 Note that when using the "news mode" ! or ? specifiers are used the entire topic text is mailed out as HTML. The =newsletter= template is used to generate the content in this mail, using whatever skin is selected in the topic being mailed.
       
   330 
       
   331 In addition, the %<nop>STARTPUBLISH% and %<nop>STOPPUBLISH% markers used by TWiki:Plugins.PublishContrib to delimit the text to be published are respected.
       
   332 
       
   333 ---+ <code>TWiki/Contrib/MailerContrib</code> code library
       
   334 The second part of the module is a code library that provides the services for other applications to modify the subscription topics through a clean, well documented API. This allows (for example) plugin developers to add (for example) a "Register me for this newsletter" button to their pages. The main interface is the =Web<nop>Notify= package described below.
       
   335 
       
   336 ---+ package TWiki::Contrib::MailerContrib::WebNotify
       
   337 Object that represents the contents of a %NOTIFYTOPIC% topic in a TWiki web
       
   338 
       
   339 
       
   340 ---++ ClassMethod new($web, $topic)
       
   341 Create a new object by parsing the content of the given topic in the
       
   342 given web. This is the normal way to load a %NOTIFYTOPIC% topic. If the
       
   343 topic does not exist, it will create an empty object.
       
   344 
       
   345 
       
   346 ---++ ObjectMethod writeWebNotify()
       
   347 Write the object to the %NOTIFYTOPIC% topic it was read from.
       
   348 If there is a problem writing the topic (e.g. it is locked),
       
   349 the method will return an error message. If everything is ok
       
   350 it will return undef.
       
   351 
       
   352 
       
   353 ---++ ObjectMethod getSubscriber($name, $noAdd)
       
   354    * =$name= - Name of subscriber (wikiname with no web or email address)
       
   355    * =$noAdd= - If false or undef, a new subscriber will be created for this name
       
   356 Get a subscriber from the list of subscribers, and return a reference
       
   357 to the Subscriber object. If $noAdd is true, and the subscriber is not
       
   358 found, undef will be returned. Otherwise a new Subscriber object will
       
   359 be added if necessary.
       
   360 
       
   361 
       
   362 ---++ ObjectMethod getSubscribers()
       
   363 Get a list of all subscriber names (unsorted)
       
   364 
       
   365 
       
   366 ---++ ObjectMethod subscribe($name, $topics, $depth)
       
   367    * =$name= - Name of subscriber (wikiname with no web or email address)
       
   368    * =$topics= - wildcard expression giving topics to subscribe to
       
   369    * =$depth= - Child depth to scan (default 0)
       
   370    * =$mode= - ! if this is a non-changes subscription and the topics should
       
   371    be mailed evebn if there are no changes. ? to mail the full topic only
       
   372    if there are changes. undef to mail changes only.
       
   373 Add a subscription, adding the subscriber if necessary.
       
   374 
       
   375 
       
   376 ---++ ObjectMethod unsubscribe($name, $topics, $depth)
       
   377    * =$name= - Name of subscriber (wikiname with no web or email address)
       
   378    * =$topics= - wildcard expression giving topics to subscribe to
       
   379    * =$depth= - Child depth to scan (default 0)
       
   380 Add an unsubscription, adding the subscriber if necessary. An unsubscription
       
   381 is a specific request to ignore notifications for a topic for this
       
   382 particular subscriber.
       
   383 
       
   384 
       
   385 ---++ ObjectMethod stringify() -> string
       
   386 Return a string representation of this object, in %NOTIFYTOPIC% format.
       
   387 
       
   388 
       
   389 ---++ ObjectMethod processChange($change, $db, $changeSet, $seenSet, $allSet)
       
   390    * =$change= - ref of a TWiki::Contrib::Mailer::Change
       
   391    * =$db= - TWiki::Contrib::MailerContrib::UpData database of parent references
       
   392    * =$changeSet= - ref of a hash mapping emails to sets of changes
       
   393    * =$seenSet= - ref of a hash recording indices of topics already seen
       
   394    * =$allSet= - ref of a hash that maps topics to email addresses for news subscriptions
       
   395 Find all subscribers that are interested in the given change. Only the most
       
   396 recent change to each topic listed in the .changes file is retained. This
       
   397 method does _not_ change this object.
       
   398 
       
   399 
       
   400 ---++ ObjectMethod processCompulsory($topic, $db, \%allSet)
       
   401    * =$topic= - topic name
       
   402    * =$db= - TWiki::Contrib::MailerContrib::UpData database of parent references
       
   403    * =\%allSet= - ref of a hash that maps topics to email addresses for news subscriptions
       
   404 
       
   405 
       
   406 ---++ ObjectMethod isEmpty() -> boolean
       
   407 Return true if there are no subscribers
       
   408 
       
   409 
       
   410 ---+ package TWiki::Contrib::MailerContrib::Subscriber
       
   411 Object that represents a subscriber to notification. A subscriber is
       
   412 a name (which may be a wikiName or an email address) and a list of
       
   413 subscriptions which describe the topis subscribed to, and
       
   414 unsubscriptions representing topics they are specifically not
       
   415 interested in. The subscriber
       
   416 name may also be a group, so it may expand to many email addresses.
       
   417 
       
   418 
       
   419 ---++ ClassMethod new($name)
       
   420    * =$name= - Wikiname, with no web, or email address, of user targeted for notification
       
   421 Create a new user.
       
   422 
       
   423 
       
   424 ---++ ObjectMethod getEmailAddresses() -> list
       
   425 Get a list of email addresses for the user(s) represented by this
       
   426 subscription
       
   427 
       
   428 
       
   429 ---++ ObjectMethod subscribe($subs)
       
   430    * =$subs= - Subscription object
       
   431 Add a new subscription to this subscriber object.
       
   432 The subscription will always be added, even if there is
       
   433 a wildcard overlap with an existing subscription.
       
   434 
       
   435 
       
   436 ---++ ObjectMethod unsubscribe($subs)
       
   437    * =$subs= - Subscription object
       
   438 Add a new unsubscription to this subscriber object.
       
   439 The unsubscription will always be added, even if there is
       
   440 a wildcard overlap with an existing subscription or unsubscription.
       
   441 
       
   442 An unsubscription is a statement of the subscribers desire _not_
       
   443 to be notified of changes to this topic.
       
   444 
       
   445 
       
   446 ---++ ObjectMethod isSubscribedTo($topic) -> $subscription
       
   447    * =$topic= - Topic object we are checking
       
   448    * =$db= - TWiki::Contrib::MailerContrib::UpData database of parents
       
   449 Check if we have a subscription to the given topic. Return the subscription
       
   450 that matches if we do, undef otherwise.
       
   451 
       
   452 
       
   453 ---++ ObjectMethod isUnsubscribedFrom($topic) -> $subscription
       
   454    * =$topic= - Topic object we are checking
       
   455    * =$db= - TWiki::Contrib::MailerContrib::UpData database of parents
       
   456 Check if we have an unsubscription from the given topic. Return the subscription that matches if we do, undef otherwise.
       
   457 d103 1
       
   458 d105 2
       
   459 a106 2
       
   460 ---++ ObjectMethod stringify() -> string
       
   461 Return a string representation of this object, in Web<nop>Notify format.
       
   462 d108 1
       
   463 a108 104
       
   464 
       
   465 ---+ package TWiki::Contrib::MailerContrib::Subscription
       
   466 Object that represents a single subscription of a user to
       
   467 notification on a page. A subscription is expressed as a page
       
   468 spec (which may contain wildcards) and a depth of children of
       
   469 matching pages that the user is subscribed to.
       
   470 
       
   471 
       
   472 ---++ ClassMethod new($pages, $childDepth, $news)
       
   473    * =$pages= - Wildcarded expression matching subscribed pages
       
   474    * =$childDepth= - Depth of children of $topic to notify changes for. Defaults to 0
       
   475    * =$mode= - ! if this is a non-changes subscription and the topics should
       
   476    be mailed evebn if there are no changes. ? to mail the full topic only
       
   477    if there are changes. undef to mail changes only.
       
   478 Create a new subscription.
       
   479 
       
   480 
       
   481 ---++ ObjectMethod stringify() -> string
       
   482 Return a string representation of this object, in Web<nop>Notify format.
       
   483 
       
   484 
       
   485 ---++ ObjectMethod matches($topic, $db, $depth) -> boolean
       
   486    * =$topic= - Topic object we are checking
       
   487    * =$db= - TWiki::Contrib::MailerContrib::UpData database of parent names
       
   488    * =$depth= - If non-zero, check if the parent of the given topic matches as well. undef = 0.
       
   489 Check if we match this topic. Recurses up the parenthood tree seeing if
       
   490 this is a child of a parent that matches within the depth range.
       
   491 
       
   492 
       
   493 ---++ ObjectMethod getMode() -> $mode
       
   494 Return ! if this is a non-changes subscription and the topics should
       
   495 be mailed even if there are no changes. ? to mail the full topic only
       
   496 if there are changes. undef to mail changes only.
       
   497 
       
   498 
       
   499 ---
       
   500 ---+ package TWiki::Contrib::MailerContrib::Change
       
   501 Object that represents a change to a topic.
       
   502 
       
   503 
       
   504 ---++ ClassMethod new($web)
       
   505    * =$web= - Web name
       
   506    * =$topic= - Topic name
       
   507    * =$author= - String author of change
       
   508    * =$time= - String time of change
       
   509    * =$rev= - Revision identifier
       
   510 Construct a new change object.
       
   511 
       
   512 
       
   513 ---++ ObjectMethod merge($change)
       
   514    * =$change= - Change record to merge
       
   515 Merge another change record with this one, so that the combined
       
   516 record is a reflection of both changes.
       
   517 
       
   518 
       
   519 ---++ ObjectMethod expandHTML($html) -> string
       
   520    * =$html= - Template to expand keys within
       
   521 Expand an HTML template using the values in this change. The following
       
   522 keys are expanded: %<nop>TOPICNAME%, %<nop>AUTHOR%, %<nop>TIME%,
       
   523 %<nop>REVISION%, %<nop>TEXTHEAD%.
       
   524 
       
   525 Returns the expanded template.
       
   526 
       
   527 
       
   528 ---++ ObjectMethod expandPlain() -> string
       
   529 Generate a plaintext version of this change.
       
   530 
       
   531 
       
   532 ---+ package TWiki::Contrib::MailerContrib::UpData
       
   533 Object that lazy-scans topics to extract
       
   534 parent relationships.
       
   535 
       
   536 
       
   537 ---++ ClassMethod new($web)
       
   538    * =$web= - Web we are building parent relationships for
       
   539 Constructor for a web; initially empty, will lazy-load as topics
       
   540 are referenced.
       
   541 
       
   542 
       
   543 ---++ ObjectMethod getParent($topic) -> string
       
   544 Get the name of the parent topic of the given topic
       
   545 
       
   546 
       
   547 ---+ package TWiki::Contrib::Mailer
       
   548 
       
   549 Package of support for extended Web<nop>Notify notification, supporting per-topic notification and notification of changes to children.
       
   550 
       
   551 Also supported is a simple API that can be used to change the Web<nop>Notify topic from other code.
       
   552 
       
   553 
       
   554 ---++ StaticMethod mailNotify($webs, $session, $verbose)
       
   555    * =$webs= - filter list of names webs to process. Wildcards (*) may be used.
       
   556    * =$session= - optional session object. If not given, will use a local object.
       
   557    * =$verbose= - true to get verbose (debug) output
       
   558 
       
   559 Main entry point.
       
   560 
       
   561 Process the Web<nop>Notify topics in each web and generate and issue
       
   562 notification mails. Designed to be invoked from the command line; should
       
   563 only be called by =mailnotify= scripts.
       
   564 
       
   565 
       
   566 
       
   567 ---+ Installation Instructions
       
   568 d111 12
       
   569 a122 19
       
   570 Like many other TWiki extensions, this module is shipped with a fully automatic installer script written using the Build<nop>Contrib.
       
   571    * If you have TWiki 4.1 or later, and Perl 5.8, you can install from the =configure= interface (Go to Plugins->Find More Extensions)
       
   572       * The webserver user has to have permission to write to all areas of your installation for this to work.
       
   573    * If you have a permanent connection to the internet (and Perl 5.8), you are recommended to use the automatic installer script
       
   574       * Just download the =MailerContrib_installer= perl script and run it.
       
   575    * *Notes:*
       
   576       * The installer script will:
       
   577          * Automatically resolve dependencies,
       
   578          * Copy files into the right places in your local install (even if you have renamed data directories),
       
   579          * check in new versions of any installed files that have existing RCS histories files in your existing install (such as topics).
       
   580          * If the $TWIKI_PACKAGES environment variable is set to point to a directory, the installer will try to get archives from there. Otherwise it will try to download from twiki.org or cpan.org, as appropriate.
       
   581          * (Developers only: the script will look for twikiplugins/MailerContrib/MailerContrib.tgz before downloading from TWiki.org)
       
   582       * If you don't have a permanent connection, you can still use the automatic installer, by downloading all required TWiki archives to a local directory.
       
   583          * Point the environment variable =$TWIKI_PACKAGES= to this directory, and the installer script will look there first for required TWiki packages.
       
   584             * =$TWIKI_PACKAGES= is actually a path; you can list several directories separated by :
       
   585          * If you are behind a firewall that blocks access to CPAN, you can build a local CPAN mini-mirror, as described at http://twiki.org/cgi-bin/view/Codev/BuildingDakar#CPAN_local_minimirror
       
   586    * If you don't want to use the installer script, or have problems on your platform (e.g. you don't have Perl 5.8), then you can still install manually:
       
   587       1 Download and unpack one of the =.zip= or =.tgz= archives to a temporary directory.
       
   588       1 Manually copy the contents across to the relevant places in your TWiki installation.
       
   589 a124 2
       
   590       1 Run =configure= and enable the module, if it is a plugin.
       
   591       1 Repeat from step 1 for any missing dependencies.
       
   592 d126 5
       
   593 a130 1
       
   594    * To make sure the installation was successful, run the =mailnotify= script from the command line, with no parameters. In this case it will print out what it would have done to STDOUT.
       
   595 d132 2
       
   596 a133 2
       
   597 ---++ Setting up your cron job(s)
       
   598 You need to set up a =cron= (or equivalent) job to run =tools/mailnotify=.
       
   599 d135 2
       
   600 a136 2
       
   601 Usage: <code>perl -I &lt;bin&gt; mailnotify [-q] [-news] [ <i>web1 web2 ... webN</i> ]</code>
       
   602 &lt;bin&gt; is the path to the TWiki bin directory, so that the script can find the rest of TWiki.
       
   603 d139 1
       
   604 a139 1
       
   605 | <code><i>web1 web2 ... webN</i></code> | List of webs to process, separated by spaces or commas. Default is to process all legal TWiki webs. Wildcards (*) are supported. |
       
   606 d144 5
       
   607 a148 1
       
   608 will generate change notifications for the =Public= and =Private= webs every night at midnight.
       
   609 d158 1
       
   610 a158 1
       
   611 ---+ Developer Notes
       
   612 d171 7
       
   613 a177 1
       
   614 ---++ Contrib Info
       
   615 d182 1
       
   616 d184 7
       
   617 d228 2
       
   618 a229 1
       
   619 
       
   620 @
       
   621 
       
   622 
       
   623 1.3
       
   624 log
       
   625 @buildrelease
       
   626 @
       
   627 text
       
   628 @d1 1
       
   629 d4 4
       
   630 a7 1
       
   631 Add-on to the TWiki kernel that supports e-mail notification of changes.
       
   632 d24 5
       
   633 a28 3
       
   634 ---++ Summary of Contents
       
   635 ---+++ <code>tools/mailnotify</code>
       
   636 The main part of the mailer module is a script, =tools/mailnotify=. This script is designed to be run from 'cron' (or an equivalent offline job scheduler), and processes the contents of the standard <nop>%NOTIFYTOPIC% topic. As well as providing the usual notification service, it also provides per-topic notification services. The script may be run from the command line or a cron job.
       
   637 d30 3
       
   638 d35 1
       
   639 a35 1
       
   640 Subscribers are listed in <nop>%NOTIFYTOPIC% following one of these bullet list formats:
       
   641 d43 1
       
   642 a43 1
       
   643 where _topics_ is a space-separated list of topic names.
       
   644 d47 1
       
   645 d49 1
       
   646 a49 1
       
   647    * Each topic may optionally be preceded by a '+' or '-' sign. The '+' sign means "subscribe to this topic" (the same as not putting anything). The '-' sign means "don't send notifications regarding this topic". This allows users to elect to filter out changes to certain topics (and their children, to an arbitrary depth). Topic filters ('-') take precedence over topic includes ('+').
       
   648 d52 25
       
   649 d78 2
       
   650 a79 4
       
   651    * daisy@@flowers.com
       
   652    * daisy@@flowers.com: Web*
       
   653    * DaisyCutter: Petal* (1) WeedKillers (3) Red*Phlox
       
   654    * StarTrekFan: * - *Wars - *sInTheirEyes - *shipTroopers
       
   655 d81 1
       
   656 a81 1
       
   657 A user may be listed many times in the <nop>%NOTIFYTOPIC% topic. Where a user has several lines in <nop>%NOTIFYTOPIC% that all match the same topic, they will only be notified of changes to that topic _once_.
       
   658 d90 124
       
   659 a213 1
       
   660 %RED% __Note__ =mailnotify= ignores permissions in webs. It is entirely possible for a user to get added to a <nop>%NOTIFYTOPIC% topic in a web, when they are not authorised to view the topics in that web. This could result in them having limited access to sensitive information (the topic summaries). %ENDCOLOR%
       
   661 a214 2
       
   662 ---+++ <code>TWiki/Contrib/MailerContrib</code> code library
       
   663 The second part of the module is a code library that provides the services for other applications to modify <nop>%NOTIFYTOPIC% through a clean, well documented interface. This allows (for example) plugin developers to add a "Register me for notification" button to their pages. The main interface is the =Web<nop>Notify= package described below.
       
   664 d216 139
       
   665 a354 5
       
   666 ---++ Installation Instructions
       
   667 This Contrib is pre-installed as part of the TWiki release package, and should only have to be re-installed if an upgrade is required.
       
   668    * Download the ZIP file from the Plugin web (see below)
       
   669    * Unzip ==%TOPIC%.zip== in your twiki installation directory.
       
   670    * Run the installer script =MailContrib_intaller.pl= or alternatively resolve all dependencies manually.
       
   671 d357 2
       
   672 a358 2
       
   673 ---++ Setting up your cron job
       
   674 You need to set up a =cron= (or equivalent) job to run =mailnotify=.
       
   675 d360 2
       
   676 a361 2
       
   677 <code>Usage: perl -I &lt;bin&gt; mailnotify [-q] [ <i>web1 web2 ... webN</i> ]</code>
       
   678 &lt;bin&gt; is the path to the TWiki bin directory (usually =../bin=), so that the script can find the rest of TWiki.
       
   679 d363 1
       
   680 d365 9
       
   681 a373 1
       
   682 For example, =perl -I /usr/local/twiki/bin mailnotify -q Public Private= will generate notifications for the Public and Private webs.
       
   683 d375 1
       
   684 a375 1
       
   685 ---++ Settings
       
   686 d378 13
       
   687 d395 1
       
   688 a395 1
       
   689 |  Copyright &copy;: | 2004, Wind River Systems |
       
   690 d397 28
       
   691 a424 25
       
   692 | Change History: | |
       
   693 | 8808 | <a rel='nofollow' href='http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1654'>Item1654</a>  mailnotify must enter the command_line context |
       
   694 | 8625 | <a rel='nofollow' href='http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1508'>Item1508</a>  Making the dashes in the separatator clearer |
       
   695 | 8606 | <a rel='nofollow' href='http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1508'>Item1508</a>  MailerContrib: Brushing up HTML mailnotify template |
       
   696 | 8602 | <a rel='nofollow' href='http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1508'>Item1508</a>  MailerContrib: Cleaning up plaintext e-mail template, removing TEXTAREA |
       
   697 | 8522 | <a rel='nofollow' href='http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1511'>Item1511</a>  arguments to getScriptUrl in wrong order :-( |
       
   698 | 8434 | <a rel='nofollow' href='http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1465'>Item1465</a>  Fix 'TWiki.' to '%TWIKIEB%.' |
       
   699 | 8398 | <a rel='nofollow' href='http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1460'>Item1460</a>  polished up the comment a bit |
       
   700 | 8308 | <a rel='nofollow' href='http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1362'>Item1362</a>  moving mailnotify cron script |
       
   701 | 7848 | <a rel='nofollow' href='http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1167'>Item1167</a>  forced all mail operations to generate absolute URLs |
       
   702 | 7568 | <a rel='nofollow' href='http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item910'>Item910</a>  use SCRIPTURL{view} instead of complex url expr |
       
   703 | 6864 | <a rel='nofollow' href='http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item624'>Item624</a>  mailer templates moved the the right places |
       
   704 | 6861 | <a rel='nofollow' href='http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item624'>Item624</a>  Added proper templates support for plain text mails |
       
   705 | 6809 | <a rel='nofollow' href='http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item623'>Item623</a>  don't print anything if verbosity is switched off. |
       
   706 | 6659 | <a rel='nofollow' href='http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item528'>Item528</a>  Updated MailerContrib. it's working and the sendmail parameter is used. |
       
   707 | 6474 | <a rel='nofollow' href='http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item420'>Item420</a>  removed spurious remove_obsolete_locks from MailerContrib |
       
   708 | 5924 | <a rel='nofollow' href='http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item153'>Item153</a>  fix mail URL-fixing scheme |
       
   709 | 5269 | Minor doc fixes |
       
   710 | 5266 | Doc tidy-ups, added filtering of _ webs, added obsolete lock script |
       
   711 | 5264 | Changed default to add web name to user name (I hope) |
       
   712 | 5263 | Minor doc tidyups |
       
   713 | 5261 | Documentation changes, and fixed to scan all webs. |
       
   714 | 5253 | runnable as CGI script, minor bugfixes, removed dependency on DBCacheContrib |
       
   715 | 5234 | Minor doc changes |
       
   716 | 5231 | Made a change an object, added unit tests to CVS, lots of testing. |
       
   717 @
       
   718 
       
   719 
       
   720 1.2
       
   721 log
       
   722 @buildrelease
       
   723 @
       
   724 text
       
   725 @d1 4
       
   726 a4 1
       
   727 %META:TOPICINFO{author="TWikiContributor" date="1111929255" format="1.0" version="2"}%
       
   728 d12 1
       
   729 a12 1
       
   730    Instead, you could check your fix in, raise a bug in the Bugs web, or mail thge author.
       
   731 d14 1
       
   732 a14 1
       
   733 This module is an add-on to the TWiki kernel that supports e-mail notification of changes.
       
   734 d20 2
       
   735 a21 2
       
   736 ---+ Summary of Contents
       
   737 ---++ <code>tools/mailnotify</code>
       
   738 d59 1
       
   739 a59 1
       
   740 ---++ <code>TWiki/Contrib/MailerContrib</code> code library
       
   741 d62 1
       
   742 a62 1
       
   743 ---+ Installation Instructions
       
   744 d69 1
       
   745 a69 1
       
   746 ---+ Setting up your cron job
       
   747 d72 2
       
   748 a73 2
       
   749 <code>Usage: perl -I <bin> tools/mailnotify [-q] [ <i>web1 web2 ... webN</i> ]</code>
       
   750 <bin> is the path to the TWiki bin directory, so that the script can find the rest of TWiki.
       
   751 d78 3
       
   752 a80 3
       
   753 ---+ Settings
       
   754    * Name of the perl package
       
   755       * Set STUB = TWiki::Contrib::Mailer
       
   756 d82 1
       
   757 a82 1
       
   758 ---+ Contrib Info
       
   759 d120 1
       
   760 a121 1
       
   761 __Related Topics:__ %TWIKIWEB%.TWikiPreferences
       
   762 a122 1
       
   763 -- TWiki:Main/CrawfordCurrie
       
   764 @
       
   765 
       
   766 
       
   767 1.1
       
   768 log
       
   769 @buildrelease
       
   770 @
       
   771 text
       
   772 @d1 2
       
   773 a2 1
       
   774 %META:TOPICINFO{author="TWikiContributor" date="1111929255" format="1.0" version="1"}%
       
   775 d4 7
       
   776 d13 2
       
   777 d32 5
       
   778 a36 5
       
   779 	* Specify topics without a _Web._ prefix
       
   780 	* Topics must exist in this web.
       
   781 	* Topics may be specified using * wildcards
       
   782 	* Each topic may optionally be followed by an integer in parentheses, indicating the depth of the tree of children below that topic. Changes in all these children will be detected and reported along with changes to the topic itself. _Note_ This uses the TWiki "Topic parent" feature.
       
   783 	* Each topic may optionally be preceded by a '+' or '-' sign. The '+' sign means "subscribe to this topic" (the same as not putting anything). The '-' sign means "don't send notifications regarding this topic". This allows users to elect to filter out changes to certain topics (and their children, to an arbitrary depth). Topic filters ('-') take precedence over topic includes ('+').
       
   784 d40 4
       
   785 a43 4
       
   786 	* daisy@@flowers.com
       
   787 	* daisy@@flowers.com: Web*
       
   788 	* DaisyCutter: Petal* (1) WeedKillers (3) Red*Phlox
       
   789 	* StarTrekFan: * - *Wars - *sInTheirEyes - *shipTroopers
       
   790 d61 4
       
   791 a64 4
       
   792 	* Download the ZIP file from the Plugin web (see below)
       
   793 	* Unzip ==%TOPIC%.zip== in your twiki installation directory.
       
   794 	* Run the installer script =MailContrib_intaller.pl= or alternatively resolve all dependencies manually.
       
   795 	* To make sure the installation was successful, run the =mailnotify= script from the command line, with no parameters. In this case it will print out what it would have done to STDOUT.
       
   796 d76 2
       
   797 a77 2
       
   798 	* Name of the perl package
       
   799 		* Set STUB = TWiki::Contrib::Mailer
       
   800 d84 25
       
   801 a108 1
       
   802 |  Change&nbsp;History: | <!-- versions below in reverse order -->&nbsp; |
       
   803 @