dockapps/wmail/README

Name            : wmail
Description     : a enhanced Window Maker email flagging docklet
Current version : 2.1
Licence         : see file COPYING for licencing details
Web/Home        : https://www.dockapps.net/wmail
Contact         : Window Maker Developers <wmaker-dev@googlegroups.com>

Description:

 This is wmail - a nifty Window Maker docklet watching your inbox, which is
 either a ordinary mbox or a directory conforming to qmail's Maildir format.
 It provides a nice little GUI displaying some useful pieces of information
 about your inbox (as many other nice wm-apps doing nearly the same thing...).
 Per default it uses the $MAIL environment-variable to locate the inbox you
 are using, other mailing mechanisms like POP or IMAP are not supported - use
 a tool like fetchmail to retrieve POP- or IMAP-based mail.

 It displays the following:

 - a mail-icon in the upper-left if your inbox contains some mails
 - a frequently flashing "M@iL" in the upper-right if there are unread mails
 - a ticker displaying either complete mail-address, its name-part or the
   full sender's name (without the "-n" option each sender found in the inbox
   is tickered, else only the unread ones)
 - the number of new and read emails found (or the number of unread messages
   if invoked with the "-n" option)

 In addition, the lower-right button allowes you to quickly launch your
 preferred email user agent (xterm -e mail, mutt, pine, etc.)

 wmail is highly customizable, both command-line and configuration-file support
 is provided. The following list describes all customizable items,
 their associated cmd-line options, config-file statements and default values:

 item             : X11 display
 cmd-line option  : -display <string>
 rc-file statement: Window.Display = "<string>"
 default value    : <unset>

 item             : toggle nonshaped mode
 cmd-line option  : -ns
 rc-file statement: Window.NonShaped = Yes|No
 default value    : No

 item             : button command to execute
 cmd-line option  : -c <string>
 rc-file statement: Window.Button.Command = "<string>"
 default value    : "xterm -e mail"

 item             : your mailbox (file => mbox, directory => Maildir)
 cmd-line option  : -mb <string>
 rc-file statement: Mail.MailBox = "<string>"
 default value    : <unset, $MAIL is used>

 item             : file to store the checksums used to identify mbox mails
 cmd-line option  : <no option>
 rc-file statement: Mail.ChecksumFile = "<string>"
 default value    : "~/.wmail-cksums"

 item             : ticker (and count) only unread mails
 cmd-line option  : -n
 rc-file statement: Mail.ShowOnlyNew = Yes|No
 default value    : No

 item             : mail check intervall (sec)
 cmd-line option  : -i <num>
 rc-file statement: Mail.CheckIntervall = <num>
 default value    : 1

 item             : consider status-field (not used when in maildir mode)
 cmd-line option  : -sf
 rc-file statement: Mail.UseStatusField = Yes|No
 default value    : No

 item             : custom status field content used for read mails
 cmd-line option  : -rs
 rc-file statement: Mail.ReadStatus = "<string>"
 default value    : "O"

 item             : show nick names in the ticker (all before the @)
 cmd-line option  : -s
 rc-file statement: Ticker.Mode = NickName
 default value    : Address

 item             : show family names in the ticker (if available)
 cmd-line option  : -f
 rc-file statement: Ticker.Mode = FamilyName
 default value    : Address

 item             : how many ticker frames per sec
 cmd-line option  : -fps <num>
 rc-file statement: Ticker.Frames = <num>
 default value    : 30

 item             : use a real X11 font when drawing the ticker
 cmd-line option  : -fn <string>
 rc-file statement: Ticker.X11Font = "<string>"
 default value    : <unset, a buildin font is used>

 item             : command to execute when new mail has arrived
 cmd-line option  : -e <string>
 rc-file statement: Mail.OnNew.Command = "<string>"
 default value    : <unset>

 item             : sender-names to skip (don't ticker and count them)
 cmd-line option  : <no option>
 rc-file statement: Mail.SkipSender = "<string>"
 default value    : <unset>

 item             : color for upper symbols (envelope and MAiL)
 cmd-line option  : -sc <string>
 rc-file statement: Colors.Symbols = "<string>"
 default value    : "#20B2AA"

 item             : ticker font color
 cmd-line option  : -fc <string>
 rc-file statement: Colors.Font = "<string>"
 default value    : "#D3D3D3"

 item             : backlight color (dockapp background)
 cmd-line option  : -bc <string>
 rc-file statement: Colors.Backlight = "<string>"
 default value    : "#282828"

 item             : color of inactive symbols
 cmd-line option  : -oc <string>
 rc-file statement: Colors.OffLight = "<string>"
 default value    : "#282828"

 item             : outer frame color (used in nonshaped window mode)
 cmd-line option  : -bg <color>
 rc-file statement: Colors.NonShapedFrame = "<string>"
 default value    : <unset, this color is translucent>

 libdockapp provides the following additional cmd-line options:

 windowed-mode        : -w

 show help and exit   : -h

 show version and exit: -v

Known bugs:

 - Solaris: sometimes wmail gets terminated by Xlib displaying the message:
   XIO:  fatal IO error 0 (Error 0) on X server ":0.0"
         after XXX requests (YYY known processed) with 0 events remaining.
   I do not have any ideas on how to fix this ... :-( --> PLEASE HELP!!!
 - "From" header field folding (see RFC822) is not supported
 - Reconfiguration during run-time results in a complete state-lost -> all
   email in your mbox is assumed to be unread again

 Please keep in mind this code is free and comes with absolutly no warranty
 (see file COPYING included in the package) - but if you think something goes
 wrong, please let me know!

What is still missing (and when it will be done :)

 - Pop3/Imap support (never - use fetchmail)
 - Character encoding in ticker - at least latin1 (currently in progress)
 - Multiple mailslots (never)
 - Displaying/tickering of other email header fields (hmm, i don't know...)
 - Your needs/ideas...?

Requirements:

 This application needs a running X window system and libdockapp v0.2 or newer
 (0.4.0 required for windowed-mode), that for itself has some requirements
 (Xpm support for example). libdockapp comes with Window Maker - if not sure,
 see what the configure-script says when running it.

Compile:

 Simply follow these steps:
 1. Call "./configure", try "./configure --help" for a list of options.
 2. Call "make" to build the binary (or gmake if make isn't GNU make compliant)

 If compiling does not succeed due to missed header files or libraries
 you have to make use of configure's `--includedir=DIR' and/or `--libdir=DIR'
 cmdline options in order to specify paths to those files.

Porting:

 This code (without using the new Maildir code and autoconf package setup)
 is known to work under:
 - Linux >=2.4.10 on x86
 - Osf 3.2 on Dec/Alpha
 - Sun Solaris 4.0 on Sparc Station 4 and 10
 - Sun Solaris 6, 7 and 8 (thanx to Kristian Borum!)
 - SunOs 5.7 on Ultra Sparc 5 (thanx to Alessandro!)

 ...together with Window Maker v0.60.0 or better (or standalone of course) and
 libdockapp v0.4.0.

 Please let me know if you have ported this to a platform not listed
 above to mention it (and your name of cource ;). Some users had
 trouble porting wmail to Solaris because the original timer signal handling
 has not worked properly. This was caused by different semantics of libc's
 signal function and should got fixed since releases >= v1.3.

Install:

 Call "make install" or copy the binary found in the src subdirectory by hand.

 Keep in mind, libdockapp must be installed properly (i.e. let reside it in
 your X11 base library directory or let $LD_LIBRARY_PATH point to the lib).
 If you would like to use rc-based configuration, look into the provided
 sample-file "wmailrc-sample" and use it as a base for your particular needs
 by copying it to ~/.wmailrc.  Note: the name of this rc-file is hard-wired and
 cannot be customized.

Run:

 Try wmail -h to see a list of all available options.

Final words:

 Thanx to Thomas Kurschel for his suggestions and coding assistance.
 Thanx to Juergen A. Erhard for his codings and Debian packaging efforts.
 Thanx to many users on the web for their ideas, test- and bug reports.

 And many great thanx to all the GNUstep and Window Maker people who've
 provided us with such a great user environment!

 Hope you will ENJOY!