Provided by: asmail_2.1-4_amd64 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.