Provided by: asmail_2.1-3_i386 bug

NAME

       asmail - the AfterStep e-mail monitor

SYNOPSIS

       asmail [-h] [-V] [-v] [-nox]
               [-insecure]
               [-noconfig]
               [-f resource file]
               [-geometry X geometry specification]
               [-iconic]
               [-withdrawn]

DESCRIPTION

       The  asmail  is  a X11 application that acts as an e-mail monitor for a
       number of various format mailboxes.  The asmail provides a  distinctive
       Afterstep window manager look and feel and features multiple options to
       allow the customization.

       Basically, the tool shows you the following:

       - The background image changes depending on whether
         there is e-mail in your mailboxes or not.
         Custom images may be loaded and used for animation
         sequences.

       - The tool will display the number of e-mails waiting
         in each mailbox and/or the total numbers for all
         mailboxes together.

       - For each mailbox, there is a status indicator that
         shows whether the update is running at this moment
         and indicates if there is an error. The same indicator
         shows up next to the summary line.

       The folowing indicators are used for the status display:

         R  An update on the mailbox is running at this moment.
            For small mailboxes with fast access, you may never
            actually see it - so fast it disappears.

         L  An error occured that has to do with the login
            procedure. Most probably, your name/password
            combination was not accepted by the server.

         C  A connection problem. asmail could not
            connect to the server for some reason. The reasons
            may be many - server down, network unreachable,
            service not available and so on.

         T  A time-out has occured while asmail was
            waiting for the server's answer. If you have a
            frequent problem with this but the server seems
            to be available in other applicaitons, try
            increasing the "timeout" setting for the mailbox.

         F  This is an indicator of a general error condition.
            Something is wrong, maybe the configuration is not
            correct, or the mailbox is not readable. Check the
            output of asmail by running from the terminal -
            this should give you an idea of what is wrong.

       The resource files may be specified with a  command  line  option.  The
       logic  of  asmail is simple: first it parses the resource file that you
       specified on the command line.  If you do not specify the resource file
       on  the  command  line,  asmail  will  look  in  the  default  location
       (~/.asmailrc).  If it  exists,  asmail  will  parse  that  one.  If  no
       configuration  file  was  given  on  the  command  line and there is no
       configuration file in the default  location,  asmail  will  attempt  to
       monitor the mailbox specified by the $MAILBOX environment variable.

       How asmail distinguishes between old and new mail.

       The UNIX mailbox format does not contain any indication on the outside.
       The mailbox must be parsed to check if some e-mail is new. Parsing  the
       mailbox  is an expensive operation, especially if the mailbox is large.
       asmail checks the mailbox  file  modification  time  with  the  stat(2)
       system  call.  When  the file modification time changes, the mailbox is
       parsed. The lines "From " are counted and taken to be the number of  e-
       mails  in  the  box.  After  each  "From  "  line, asmail looks for the
       "Status:" header. This header contains flags when the message was  seen
       and  read.  Messages without this header line (or with an empty header)
       are considered to be new.

       The Maildir format is very well-behaved. There are separate folders for
       old  and  new e-mails so we just count the number of files in "cur" and
       "new" subdirectories.  The "tmp" subdirectory is ignored since this  is
       the temporary storage and is not supposed to be taken into account.

       The  mH  format  is  somewhere  between  Maildir  and  the UNIX mailbox
       formats. It is used by mh, nmh, balsa  and  xfmail  among  others.  The
       messages  are  all  stored in separate files, one message per file, and
       all of the messages in a single directory. Each message file  is  named
       with an increasing number, so the first message recieved in the mailbox
       is stored as "1" and the 39th message is stored as "39".  There are two
       ways  that the status of the messages are kept track of. Traditionally,
       the mH tools used a file called ".mh_sequences", which is stored in the
       mH  directory,  to keep track of status. This file contains a series of
       sequences, each one starting with a token followed by a colon and  then
       by  a  series of message numebrs, representing the messages that belong
       to that sequence. It looks something like this:
              unseen: 1 2 3-5 19 25-31
       Although there are many sequences, some standard and some user-defined,
       if  the  use-mh-sequences configuration option is set to "yes" for that
       mailbox, then asmail will parse this file,  looking  for  the  "unseen"
       sequence  to  determine  how  many messages are new.  Some mail clients
       don't use the .mh_sequences file and instead treat the files in the  mH
       mailbox  just  like  a  collection  of  seperate  messages  from a UNIX
       mailbox. So, if the use-mh-sequences configuration  option  is  set  to
       "no",  or  is  not  specified at all, then asmail will parse all of the
       files in the mH directory, searching for the Status header.  Therefore,
       this  mode  is  definitely  the most "processor hungry" format from the
       point of view of asmail.  mh, nmh, and newer versions of balsa  utilize
       the  .mh_sequences  file,  while  older versions of balsa and xfmail do
       not.  It is not known how other clients treat mH mailboxes.

       The POP3 protocol does not support the notion of  new  or  old  e-mail.
       Your  e-mail  client  keeps a list of messages and can tell whether you
       read one of them or not. Since asmail does not keep a list of  messages
       there  is no way to tell a new message from the old one. Ok, so what we
       do is assume that all e-mail is new at  start-up.  This  is  a  logical
       assumption for most of the people because they store the e-mail locally
       and remove it from the server.  Others are out of luck. Now,  when  the
       number  of  messages decreases, we assume that you read all your e-mail
       and deleted some, so all messages are marked as old. When the number of
       messages  increases,  we assume that the new mail arrived and we report
       the additional mail as new.

       The IMAP protocol is very well behaved, it reports the number of new e-
       mails  and  the  number  of old e-mails if you ask politely :) Since we
       open the mailbox in read-only mode, we do not cause any status  changes
       for  the mailbox on the server. The IMAP server will store a special e-
       mail into your mailbox if it is in UNIX format. This e-mail allows  the
       server  to  keep  track of the new and old e-mails. The server will not
       report this e-mail into the number of e-mails, so  that  if  you  check
       your UNIX mailbox directly the number of messages will be one more.

CONFIGURATION OPTIONS

       -h
              prints a short description and usage message.

       -V
              Version control. Prints out the version of the program.

       -v
              Verbose  mode.  In  this mode, asmail will print the information
              about mailboxes onto the controlling terminal.  The  information
              includes:  number of updates requested, per mailbox: thread PID,
              [R]unning or idle, any errors are  signalled  with  leters  (see
              above)  and  the  number  of e-mails in the format new/old. This
              mode is useful  for  debugging  or  could  be  used  to  monitor
              mailboxes without X Windows interface (give the -nox option).

       -f resource file
              Specifies  the  alternative location for the resource file.  The
              default location is  ~/.asmailrc  If  the  alternative  file  is
              specified, the default location is ignored.

       -geometry X geometry specification
              Specifies the size and position of the application on the screen
              in  the  standard  X11  format  (see  XParseGeometry  (3x)   for
              details):

              [=][<width>{xX}<height>][{+-}<xoffset>{+-}<yoffset>]

       -noconfig
              Forces  asmail  to  ignore  the  resource  file  even  if one is
              present. asmail will run with all default settings and check the
              Unix mailbox specified by the $MAIL environment variable.

       -nox
              Starts  the  asmail application in the terminal-only mode. The X
              Windows interface is not  started.  The  configuration  file  is
              still parsed as usual though.

              This option implies -v option.

       -insecure
              Usually,  asmail  will  check that the resource file has the 600
              mode, that is  there  are  no  access  rights  for  "group"  and
              "others".  If  such  access  rights  are  granted,  asmail  will
              complain and exit.  This  is  done  to  make  you  remember  the
              passwords  you  put  into  the  resource  file.  If there are no
              passwords stored in the file (e.g. you are using UNIX mailbox on
              the local machine) the check is not applied.

              This  option  forces  asmail  to  continue operation even if the
              resource file has insecure permissions and passwords are  stored
              in that file.

       -iconic
              This option will cause asmail to start up as an icon rather than
              as a normal window. The application can still be de-iconized and
              iconized as usual.

       -withdrawn
              This  option  will  cause  asmail  to  start  up  in a so-called
              "withdrawn" mode.  This  mode  is  used  by  WindowMaker  window
              manager to dock the application into their version of the Wharf.

RESOURCE FILE SYNTAX

       The  syntax  of  the  resource file is described in a separate man page
       under asmailrc (5).

INVOCATION

       asmail can be called in different ways.  The most common invocation  is
       the command line:

            user@host[1]% asmail &

       Another way to call asmail is from the window manager:

            *Wharf "asmail" nil Swallow "asmail" /usr/local/bin/asmail &

       This  line,  when  placed  in  the  wharf  file  in the users Afterstep
       configuration directory will cause asmail to become  a  button  on  the
       Wharf (1) button bar under the afterstep (1) window manager.

BUGS

       My programs do not have bugs, they just develop random features ;-)

       Well,  there are limitations. All the strings for the color names, file
       names, and other strings  have  the  length  limit  of  256  characters
       (terminating zero included).  The program will complain about very long
       names in the configuration file.

       The number of mailboxes is not limited by the space on the icon but the
       stats  will be chopped (not shown) if you have too many and they do not
       fit into the icon.  Make sure you pick up a tall icon if you have  many
       mailboxes  and  want to see info on each of them because they are shown
       from the top down and there is no way to change this.

       The information about mailboxes will not appear when you  use  "shaped"
       windows with transparency if it is printed in the transparent area.

       asmail  may  interfere  with  your mail client program when you use the
       POP3 server. There is no way to login to the POP3  server  twice  (from
       the  mail  client  and  asmail), so there is an inherent race condition
       between the two.  The one that tries  to  log  in  second,  will  fail.
       asmail  logs  out  immediately  after checking so your mail client will
       have a much higher chance of precluding asmail from logging in than the
       other way around.

       If  the  program  is not satisfied with the specification of one of the
       mailboxes, it will print an error message,  set  the  status  for  that
       mailbox  to  F  (Failed)  and  exit the thread (only the thread that is
       responsible for handling that particular mailbox). Other mailboxes will
       be checked normally.  Check the standard output of the tool to see what
       the problem is.

FILES

       ~/.asmailrc

SEE ALSO

       asmailrc(5) afterstep(1)

COPYRIGHTS

       Copyright (c) 2002-2007  Albert Dorofeev <albert@tigr.net>

       Distributed under GNU General Public License v2 ; see LICENSE file  for
       more informations.

AUTHORS

       Albert "Tigr" Dorofeev <albert@tigr.net>

       See the README file for credits.