What is Melon?
--------------

Melon is a simple utility that notifies user for newly received e-mails,
through a nice couple of configurable icons. In short, it is an
xbiff replacement.
When a mailbox has received new e-mails, the icon changes and an
acoustic warning is played.

Features
--------

Melon supports multiple mailboxes handling, acoustic warnings, 
execution of external application on request. 
By default, melon checks only the modification time of a file, so
you can monitor every kind of files with it, not just mailboxes.
If you prefer, melon is able to scan the mailbox looking for the
status flag for each message. 
When adding a mailbox to the file list, you can specify the 
check's method depending of your requirements (see "Set Mailboxes").

Download
--------

Latest version of melon is always available here:

	http://www.entropika.net/melon/packages/melon_current.tar.gz

Changelog:

	http://www.entropika.net/melon/packages/Changelog

Readme file:

	http://www.entropika.net/melon/packages/README

Installation
------------

See the INSTALL file.

Upgrading from Melon-1.0
------------------------

The name of install dir is changed. Now the format is 'melon-x'.
If you added your own pixmaps and audio files to the old install
dir, you need to move them to the new location.

Upgrading from Melon-1.1, Melon-1.2
-----------------------------------

The configuration file melon.cfg and the status file melon.status
are now stored in ~/.melon directory. In order to use your old
~/.melon.cfg file, you have to move it to the new location.
Note that ~/.melon directory is created when you launchs melon, if
it don't already exists.

Upgrading from Melon-1.3
------------------------

Your already set mailboxes/files will be treated as mailbox by 
Melon (see "Set Mailboxes"). In order to avoid the check based upon
the status flag, you have to reset the type to file into the "Set Mailboxes"
pupup.

Start with Melon
----------------

Probably the more confortable way to start melon is to put 
it in your .xinitrc file to get it executed every time X starts.
Of course you can start it by hand if you like it.
If all goes right, you will see a melon icon (the default one) 
in the top/left part of your desktop.

TIP: to add melon in the .xinitrc you need to add a line like
the following *before* the line that starts your window manager:

melon &

For example this is my .xinitrc:

--- .xinitrc ---
melon &
exec fvwm2
----------------

Needless to say you can execute melon using some feature of your
window manager.

Command line options
--------------------

Usage: melon [OPTIONS]

        -p              ignore pidfile                     
        -g, -geometry   specify windows coordinates        
                        example: melon -geometry -1+10     
        -v              show version and paths             
        -h              print this help              

Description

-p
	Normally, melon saves its pid on the file ~/.melon/melon.pid at 
	start time. In this way, you are able to perform some action
	using a preexistent melon instance (see "Control Commands" for
	more information). The -p switch allows multiple instances of
	melon to be executed simultaneously, loosing however the use of
	control commands.

-g, -geometry +/-x+/-y
	
	You can specify the coordinates of melon icon.
	Examples:

	melon -g -0-0		
	The icon appears at right-bottom corner of the screen.

	melon -g -0+0		
	The icon appears at right-top corner of the screen.

	All values into the range of your screen width/height are allowed.


Control Commands
----------------

If a melon instance is already running, the following commands are
recognized:

open
	melon executes the program defined as "mailer command" in melon
	configuration. For example, my mailer command is

	"/usr/bin/X11/xterm -vb -bg black -fg gray90 \
	-fn -*-clean-medium-r-*-*-17-*-*-*-*-*-*-* -e /usr/bin/mutt -f %M"

	I have defined a keyboard shortcut in my windows manager configuration,
	so I can open mutt with the active mailbox by pressing a couple of keys.

reset 
	causes melon to reset the status of all mailbox to inactive.

stop
	surprisingly melon quits!


Configuration
-------------

Melon provides a GUI to configure icons, sound, position and so on,
so you don't need to edit by hand any configuration file.
By clicking with the right button of your mouse on melon icon, you'll see
a little menu that shows all the configurable items.

"Set Mailboxes"

When adding a mailbox, you can specify what kind of check melon
will perform on this file. There is two icons into the buttons bar
at the bottom of the mailboxes popup. One is for setting "mbox" type, 
i.e. melon will scan the file, looking for the status flag for each
message. The other is for "file" type and causes melon to check only
the modification time of the file.

"Configure Mailer"

You can put into this entry field the command line of the program 
you mean to start every time you clicks with the left button
on the icon. 
Note that the FULL filepath is required.
By default, no external program is called when you clicks on icon: 
if the mailbox is active (i.e. have received new e-mails), you'll simply unset
its active status by clicking.

This is, for example, the command line I'm using with mutt:

/usr/bin/X11/xterm -geometry 100x40+120+20 -e /usr/local/bin/mutt -f %M

An other example, using pine:

/usr/bin/X11/xterm -e /usr/local/bin/pine -i -f %M

Note that '%M' is a special keyword that melon will substitute with
the mailbox path to open, useful if you have configured more than one
mailbox. 

"Set Beep -> Set beep mode"

There is two ways to notify newly received e-mails with
acoustic warnings. With the first one ("Play once for mailbox"),
melon beeps only when a mailbox receives new e-mail the first time and
stays silent until you reset mailbox status by clicking on icon or on
active mailbox menu. With "Play for each new e-mail", melon beeps each 
time a new e-mail is received.

"Set Beep -> Set audio device"

Melon can play its acoustic warnings on /dev/dsp or /dev/audio.
Through this submenu you can select the appropriate audio device
for melon. The package provides a set of au and voc files.

"Check Options -> Save Status"

Melon can save the status of your mailboxes before quitting.
Next time you'll launch it, Melon will be able to notify if 
new mails was received since it was off.
Note that the status is based only on the modification time
and size of the file, so melon will be confused  if you access a mailbox
when it is shut down.

"Check Options -> Set Interval"

It is recommended to set it to a low value, about 2000/3000 ms.
Since melon performs his operations only if the modification
time of the file has changed, you should not worry about resources
wasting. 

Adding pixmaps and audio files
------------------------------

How to add a new pixmap set?

Melon uses two pixmaps to display mailbox status. One is for
the "no new mail status" and its filename is 1.xpm, the other
is for "new mail status" with filename 2.xpm.

All the pixmaps are organized as follows:

Every set (i.e. a couple of pixmap) is put inside the "root pixmap directory"
with the name of the set. So if you need to add a new set called "foo" you
need to create a directory with this name inside /usr/local/share/melon-1/pix/
(with mkdir /usr/local/share/melon-1/pix/foo) and copy the two .xpm files
inside.

The /usr/local/share/melon-1/pix path is only the default. Maybe you changed
it at istall time so to obtain the right root pixmap directory use the '-v' switch
of melon.

To see the new set in the configuration menu you need to restart melon, so it
will rescan the sets.

How to add a new audio file?

The audio files are all inside a directory (/usr/local/share/melon-1/au and
/usr/local/share/melon-1/voc by default).
In order to add a new audio file just copy the audio file here.
If Melon plays on /dev/dsp, you have to add a .voc file to the 
voc directory. If it's plays on /dev/audio, add a .au file to the
au directory.

As stated for the pixmap the audio file root directory may be configured at install
time. Try `melon -v' to see the right path for your binary.

Feedbacks
---------

For problems, bug reports and suggestions, feel free to contact
Elisa Manara <e@entropika.net>

License
-------

Melon is Copyright(C) 2001-2002 Elisa Manara <e@entropika.net>;
the code is released under the GPL License version 2. 
See the COPYING file for more information.