NAME
      ec - E-mail reader and composer for Unix and Perl/Tk.

SYNOPSIS
      ec [-f filename][-hkvdo]

  Command Line Options

    -f filename
        Use <filename> instead of the default server authentication
        file.

    -h  Print help message and exit.

    -k  Don't delete messages from POP server.

    -v  Print verbose transcript of dialogs with servers.

    -d  Print debugging information on the terminal.

    -o  Offline - don't fetch mail from server.

CONTENTS
    DESCRIPTION
    USING EC
    Sorting Messages
    Entering Messages
    MIME Attachments
    CONFIGURATION
    Configuration Files
    Mail Directories and Folders
    Filters
    Mail Transport Agents
    Editing the Library Path Names in the Source File
    PRINTING THE DOCUMENTATION IN DIFFERENT FORMATS
    LICENSE
    VERSION INFO
    CREDITS
DESCRIPTION
    EC is an Internet email reader and composer that can download
    incoming messages from one or more POP3 servers, and send mail
    directly to a SMTP server, or via sendmail or qmail if either is
    installed.

    EC provides options for configuring user defined mail folders
    and mail filtering by matching text patterns in incoming
    messages. The program stores the incoming messages in folders
    that you configure, or sends them directly to the Trash folder
    for deletion. With no additional configuration, however, EC
    displays incoming messages in, naturally, the "Incoming" folder.
    (EC capitalizes the first letter of directory names when
    creating folder names.) EC displays the number of unread and
    total messages in each folder on the "Folder" menu. Messages can
    be moved from folder to folder, including the Trash folder, so
    you can retrieve messages that you accidentally delete.

    EC permanently deletes messages stored in the Trash folder after
    a user-configurable period of time (two days is the default).
    Refer to the section, "Configuration Files," below.

    EC also supports encoding and decoding of Base64 MIME
    attachments, using an external filter program included in the
    distribution package.

USING EC
    EC uses two windows for email processing: the main window where
    you can read, sort, save, or delete incoming messages, and a
    composer window where you can enter new messages and reply to
    messages in the main window.

    If you installed EC and its supporting files correctly (as well
    as Perl and the Perl/Tk library modules), typing at the shell
    prompt in an xterm:

       # ./ec

    should start up the program and display the main window with the
    Incoming mail folder. If you receive an error message that the
    program cannot connect to the POP mail server, use the -v
    command line switch to produce a transcript of the dialog with
    the server:

      # ./ec -v

    If EC pops up an error message, or refuses to start at all, or
    spews a bunch of Perl error messages all over the xterm, consult
    the INSTALL file once again. If you need assistance with the
    installation, please contact the author of the program. The
    email address is given in the section: "CREDITS," below.

    The functions on the menu bar should be fairly self-explanatory.
    You can view different mail folders by selecting them from the
    "Folder" menu, and move messages from one folder to another by
    selecting the destination folder from the "Message -> Move To"
    submenu. If you have Motif installed, you can "tear off" the
    menus so they are displayed in a separate window.

    The "File -> Browse URL" function pops up a dialog box with the
    URL under the text cursor. If you click "OK," EC opens the
    browser that is named in the .eccconfig file, and loads the URL.
    If the browser is already open or iconified, EC will use that
    browser window to view the URL. EC supports Netscape 4.5-4.7,
    Amaya 2.4, Opera 5.0, and Lynx in an xterm. If you select Lynx,
    you will probably also need to set the xterm option in the
    .ecconfig file.

    The "File -> Attachments" function opens a dialog window to save
    attachments to disk in the main window. When you select "File ->
    Attachments" from in the composer window, the dialog allows you
    to select files that will be attached to the outgoing message.
    Refer also to the section, "MIME Attachments," below.

    There are a number of options for quoting original messages when
    composing a reply. Refer to the .ecconfig file for information
    about these options.

    EC also uses the X clipboard, so you can cut and paste between
    windows in EC as well as other applications. If a program does
    not have "Cut," "Copy," or "Paste" menu options, you can select
    text in the original application by holding down the left mouse
    button and dragging it across the text to highlight it, then
    changing to the destination text window, and pressing the middle
    mouse button (or the left and right buttons simultaneously on
    mice with only two buttons).

  Sorting Messages

    You can select whether to sort messages by Date (the default),
    the sender, or the subject, either newest first or oldest first,
    by selecting the sort field from the "Options -> Sort by"
    submenu and the "Options -> Sort Order" submenu, or by clicking
    on the headings of the message listing.

  Entering Messages

    When you click on the "New" button on the function bar below the
    incoming message listing, or select "Message -> Compose New
    Message" from the menu, a window opens with a new message form
    with header lines for the addressee, the subject, and the name
    of the FCC (File Carbon Copy) file to save a copy of the message
    in. If you have a ~/.signature file (refer to the .ecconfig file
    to configure this option), EC will insert that at the end of the
    text. You can enter the message below the separator line.

    Clicking on the function bar's "Reply" button, or selecting
    "Message -> Reply" from the menu bar, will open a compose window
    with the address and subject of the original message filled in,
    and the message quoted in the text area. There are several
    options that determine how EC fills in reply addresses and
    quotes original messages. Again, refer to the .ecconfig file for
    information about these options.

    Each message contains header information and body text,
    separated by a boundary line:

      --- Enter the message text below this line. ---

    This line must exist for EC to process the message, but it is
    not included in the outgoing message.

    Outgoing messages require at least the valid email address of a
    recipient to be entered on the "To:" header line.

    You can use the optional fields Cc:, Bcc:, and Reply-To:, either
    by adding them manually above the separator line, or selecting
    them from the "Message -> Insert Field" menu selection.

    EC supports a limited form of address "unfolding," so you can
    enter more than one email address on a To:, Cc:, Reply-To:, or
    Bcc: line, separated by commas. EC will include the multiple
    addresses in the outgoing message's header or will process the
    message to route it to all recipients.

  MIME Attachments

    You can attach Base64 binary encoded MIME attachments to
    outgoing messages by selecting the "File -> Attachments..." menu
    item in the compose window, then selecting the file or files to
    attach. If you select "File -> Attachments" from the main
    window, EC will show you a list of file attachments for the
    current message, which you can then save in their original
    format.

    When attachments are selected, EC also encloses the text portion
    of the message as a MIME "text/plain" section, and sets the
    header's Content-Type: field to "multipart/mixed." All messages
    contain the required MIME-Version:, Content-Type:, and Content-
    Transfer-Encoding: headers, whether or not the message contains
    any attachments.

CONFIGURATION
  Configuration Files

    The email client uses two configuration files, .ecconfig and
    .servers. They reside in the ~/.ec directory by default,
    although you can change their names and locations by editing
    their path names in the "ec" and ~/.ec/EC/Config.pm files
    directly . The files and directory are not visible in normal
    directory listings. Use the "-a" option to ls to view them:

      # ls -a ~/.ec

    The .ecconfig file contains user-settable defaults for the
    program's operating parameters using <option> <value> statements
    on each line. The function of each setting is explained in the
    .ecconfig file's comments.

    You can also edit the .ecconfig file by selecting 'Sample
    .ecconfig File...' from the Help menu. Pressing mouse button 3
    (the right button on many systems), pops up a menu over the text
    area. where you can save your changes. You must exit and restart
    EC for the changes to take effect.

    The .servers file contains the user login name, host name, port
    and password for each POP3 and SMTP server. EC allows incoming
    mail retrieval from multiple POP3 servers, but only allows one
    SMTP server for sending outgoing mail. The format of each line
    is:

      <server-name> <port> <user-login-name> <password>

    If there is a hyphen, '-', in the password field, then EC will
    prompt you for the server's password when the program logs on to
    the server.

    In standard configurations, POP3 servers use port 110, and the
    single SMTP server uses port 25.

    The .servers file must have only user read-write permissions
    (0600), otherwise the program complains. The correct permissions
    can be set with the command:

      # chmod 0600 .ec/.servers

    You must be the file's owner, of course, in order to be able to
    reset the file's permissions.

    The '.servers' file is not editable from the Help menu.

  Mail Directories and Folders

    EC can save messages in any number of user-configurable
    "folders," or directories, and it can move messages between the
    directories with the Message -> Move To submenu. By default, the
    mail folders are subdirectories of the <maildir> setting.

    Assuming that a user's HOME directory is /home/bill, the
    directories that correspond to mail folders would are:

      Option     Value      Path
      ------     -----      ----
      maildir    ~/Mail     /home/bill/Mail
      incoming   incoming   /home/bill/Mail/incoming
      trash      trash      /home/bill/Mail/trash

    The 'Incoming' and 'Trash' folders are required. These
    directories must exist before using EC. The program will not
    create them on its own.

    EC makes the first letter of folder names uppercase, regardless
    of whether the directory name starts with a capital or small
    letter.

    All other directories can be configured in the .ecconfig file,
    using the 'folder' directive. You must create the directories
    before EC can move messages into them.

  Filters

    You can sort incoming mail by matching the text in an incoming
    message with a specified pattern. Each "filter" line in the
    .ecconfig file is composed of a text pattern, a double equals
    sign, and the folder the mail is to be saved in. The format of a
    filter line in the configuration file is:

      filter <text-pattern>==<folder-directory>

    Because the text pattern is used "raw" by Perl, you can use
    whatever metacharacters Perl recognizes (refer to the perlre man
    page). Pattern matches are not case sensitive, and the folder-
    directory that the pattern matches must exist.

    Because of Perl's pattern matching, you must quote some
    characters that are common in email addresses which Perl
    recognizes as metacharacters, by preceding them with a
    backslash. These characters include '@', '['. ']', '<', and '>'.
    Refer to the example filter definitions in the .ecconfig file.

  Mail Transport Agents

    In additon to an ISP's SMTP server, EC can send outgoing
    messages to sendmail or qmail, if either is installed. In the
    .ecconfig file, the "usesendmail" and "useqmail" options
    determine which program is used. If the value of either is non-
    zero, then outgoing mail is routed to the MTA; otherwise, the
    default is to send mail directly to the ISP's SMTP server, using
    the information in the ~/.ec/.servers file.

    In most sendmail configurations, either the local sendmail must
    be configured to relay messages, or have a "smart host" defined.
    The comments in the .ecconfig file describe only a few possible
    settings. Refer to the sendmail documentation for further
    information.

    If the "useqmail" option is set, make sure that you can execute
    the qmail-inject program, which is /var/qmail/bin/qmail-inject
    in qmail's default configuration. EC still connects directly to
    an ISP's POP3 server, and uses the system UNIX mailbox, usually
    /var/spool/mail/<user>, for incoming messages.

    The qmail-inject -f option is not implemented. The format of the
    sender's return address can be set using environment variables.
    Refer to the qmail-inject manual page for information.

  Editing the Library Path Names in the Source File

    If you would like to change the path names of library files, use
    a text editor to edit the values of $iconpath, $cfgfilename,
    $serverfilename, and $base64enc at the beginning of the main
    source file, "ec," and ~/.ec/EC/Config.pm.

    The expand_path function expands leading tildes ('~') in file
    and path names to the value of the $HOME environment variable,
    following the convention of the UNIX Bourne shell. Directory
    separators are forward slashes ('/'), so compatibility with non-
    UNIX file systems depends on the Perl environment to perform the
    path name translation.

PRINTING THE DOCUMENTATION IN DIFFERENT FORMATS
    It is possible produce this documentation in various formats
    using Perl's POD formatting utilities:

      pod2html <ec >doc.html
      pod2latex <ec >doc.tex
      pod2man <ec >doc.man
      pod2text <ec >doc.txt
      pod2usage <ec >doc.hlp

    Refer to your system's manual pages for instructions of how to
    use these utilities.

LICENSE
    EC is licensed using the same terms as Perl. Please refer to the
    file "Artistic" in the distribution archive.

VERSION INFO
      $Id: ec,v 1.14 2002/03/09 01:01:18 kiesling Exp $

CREDITS
      Written by Robert Kiesling, rkiesling@mainmatter.com

      Perl/Tk by Nick Ing-Simmons.

      The POP server interface is based on:
      POPMail Version 1.6 (RFC1081) Interface for Perl,
          Written by:
          Kevin Everets <flynn@engsoc.queensu.ca>
          Abhijit Kalamkar <abhijitk@india.com>
          Nathan Mahon <vaevictus@socket.net>
          Steve McCarthy <sjm@halcyon.com>
          Sven Neuhaus <sven@ping.de>
          Bill Reynolds <bill@goshawk.lanl.gov>
          Hongjiang Wang <whj@cs-air.com>

      The encdec Base64 filter was written by Jrgen Hgg and posted
      to the comp.mail.mime Usenet News group.  Please refer to the
      source file, .ec/encdec.c, for licensing information.

