<chapter id='announce_plugin'>
    <title>The Announce Plugin</title>
    <para>The Gradle announce plugin allows you to send custom announcements during a build. The following notification systems are supported:
	<itemizedlist>
 		<listitem><ulink url='http://twitter.com'>Twitter</ulink></listitem>
 		<listitem><ulink url='http://manpages.ubuntu.com/manpages/gutsy/man1/notify-send.1.html'>notify-send</ulink> (Ubuntu)</listitem>
        <listitem><ulink url="https://sites.google.com/site/snarlapp/home">Snarl</ulink> (Windows)</listitem>
        <listitem><ulink url="http://growl.info/">Growl</ulink> (Mac OS X)</listitem>
 	</itemizedlist>
	</para>

    <section id="sec:announce_usage">
        <title>Usage</title>
        <para>To use the announce plugin, apply it to your build script:</para>
        <sample id="useAnnouncePlugin" dir="announce" title="Using the announce plugin">
            <sourcefile file="build.gradle" snippet="use-plugin"/>
        </sample>

        <para>Next, configure your notification service(s) of choice (see table below for which configuration properties are available):</para>
        <sample id="useAnnouncePlugin" dir="announce" title="Configure the announce plugin">
            <sourcefile file="build.gradle" snippet="announce-plugin-conf"/>
        </sample>

        <para>Finally, send announcements with the <literal>announce</literal> method:</para>
        <sample id="useAnnouncePlugin" dir="announce" title="Using the announce plugin">
            <sourcefile file="build.gradle" snippet="announce-usage"/>
        </sample>

        <para>The <literal>announce</literal> method takes two String arguments: The message to be sent, and the notification
            service to be used. The following table lists supported notification services and their configuration properties.
        </para>

   <table>
       <title>Announce Plugin Notification Services</title>
       <thead>
           <tr>
               <td>Notification Service</td>
               <td>Operating System</td>
               <td>Configuration Properties</td>
               <td>Further Information</td>
           </tr>
       </thead>
       <tr>
           <td>twitter</td>
           <td>Any</td>
           <td>username, password</td>
           <td></td>
       </tr>
       <tr>
           <td>snarl</td>
           <td>Windows</td>
           <td></td>
           <td></td>
       </tr>
       <tr>
           <td>growl</td>
           <td>Mac OS X</td>
           <td></td>
           <td></td>
       </tr>
       <tr>
           <td>notify-send</td>
           <td>Ubuntu</td>
           <td></td>
           <td>Requires the notify-send package to be installed. Use <literal>sudo apt-get install libnotify-bin</literal>
               to install it.</td>
       </tr>
       <tr>
           <td>local</td>
           <td>Windows, Mac OS X, Ubuntu</td>
           <td></td>
           <td>Automatically chooses between snarl, growl, and notify-send depending on the current operating system.</td>
       </tr>
   </table>
    </section>

    <section id="sec:announce_configuration">
        <title>Configuration</title>
        <para>See the <apilink class="org.gradle.api.plugins.announce.AnnouncePluginExtension"/> class in the API documentation.</para>
    </section>
</chapter>
