$Id: README,v 1.9 2003/08/27 01:55:51 terminus Exp $

NAME
    gtkgrepmail - a gtk front end to grepmail

SYNOPSIS
      gtkgrepmail

DESCRIPTION
    A gtk front end to grepmail which will allow you a GUI interface to
    search through your sent and saved mail. Support is provided for both
    local mailboxes and remote mailboxes that are accessible using IMAP and
    ssh/rsh.

OPTIONS
    Preferences are set by clicking the *Settings* menu and selecting
    *Preferences*. The options set out there are as follows:

    Path (local or remote) to mail folders
            Here you must specify the *full* path to the directory that
            contains your mail folders. These must be in standard UNIX
            mailbox format, but may be compressed by gzip, tzip or bzip2 if
            those utilities are present on the same system. You do not need
            to prepend a hostname to the path here, this will automatically
            be assumed if a host other than "localhost" is specified below.

    IMAP root
            The location of the root of your IMAP folder tree, if
            applicable. Normally this will be either the same as, or a
            subset of, the path to your mail folders set above.

    Relative path to temporary mailbox
            gtkgrepmail stores your search results in a temporary mailbox.
            Use the default (search-results) unless you have some particular
            reason to choose differently. Do not prepend a path. Do not use
            spaces in the filename.

    Path (local or remote) to grepmail
            Here you must specify the *full* path to grepmail, on whichever
            system contains your mailboxes. You do not need to prepend a
            hostname to the path here, this will automatically be assumed if
            a host other than "localhost" is specified below.

    Path to IMAP or mailbox browser
            If your mailboxes are on the local computer, you can specify any
            program (even a text editor such as vi) that can read the
            mailboxes. The default is ""/usr/bin/X11/xterm -e /usr/bin/elm
            -f"".

            If your mailboxes are on a remote computer, specify a program
            that can accept an IMAP URI such as
            "IMAP://servername/path/to/mailbox". One such program is
            Netscape Navigator.

    Path to ssh or rsh
            If you intend to access remote mailboxes, gtkgrepmail calls
            grepmail on the remote computer using ssh (recommended) or rsh.
            It is important to note that gtkgrepmail *requires* that you can
            log into the remote computer interactively entering a password.
            It is recommended that you achieve this through the use of the
            ssh-agent(1) facility.

    Host    If you intend to access your mailboxes on your local computer,
            leave this set as ""localhost"". Otherwise, enter a name by
            which your remote computer can be reached.

    User    If accessing your mailboxes remotely, enter your username here.
            This is used both for rsh/ssh and for IMAP.

USAGE
    The main window of the gtkgrepmail application has three tabbed panes:

    Search for
            Type the expression you wish to search for in the first textbox
            field. In the second field you may type another expression which
            you wish to combine with the first in order to return results
            which only match both expressions (toggle the "and" radio
            button) or which match either expression (toggle the "or" radio
            button). If you wish to ensure that a certain expression does
            not exist in the search results, enter that expression in the
            third field. In all three cases, you may choose to restrict your
            search on that expression to the body or the header of emails by
            untoggling the Header or Body checkboxes respectively.

    Search in
            Here will be listed all of the mailboxes that are available for
            you to search. Select one or more mailboxes by clicking them.
            Press "Refresh" if the available mailboxes have changed since
            the list was drawn.  Press "Save" to save the currently selected
	    mailboxes as your defaults.

    Search options
            Here you can restrict your search by date: click the "Between"
            radio button if you wish to search for emails between two dates,
            or click the "Expression" radio button and describe the period
            in which you are interested. You can use expressions such as
            "today", "yesterday", "5 days ago", "5 weeks ago", "before July
            2001", "12/10/00" and so on: for complete details see
            Date::Manip(3pm).

            As for the other options found on this pane, "Case insensitive"
            should be self-explanatory, "Inverse match" will find emails
            that do *not* match your first two search expressions. The state
            of the "and/or" toggle will not make any difference in this
            case; if "apple" and "pear" are your first two expressions, the
            results will be all emails that contain neither of those terms.
            The "Skip non-text attachments" option will ignore MIME
            attachments to your emails that are not in a plain text format
            (this is generally a good idea when searching for short words).

    Buttons The buttons at the bottom of the main window control the main
            functions of the program. "Clear" will reset the data in all
            three tabs of the form to their default values. "Search" will
            commence the search that you have specified. "View" will launch
            your IMAP or mailbox browser so that you can see the search
            results.

AUTHOR
    Jeremy Malcolm <Jeremy@Malcolm.id.au>

SEE ALSO
    grepmail(1), grep(1), perl(1), ssh(1), ssh-agent(3), rsh(1),
    Date::Manip(3pm)

BUGS
    Does not offer complete feature-compatibility with grepmail. For example
    by clicking "Header" and "Body" checkboxes you are specifying that you
    want the text to appear *either* in the header or body, not that you
    want it to appear in both. There is no way of specifying that.

    Has no provision to prompt you for your SSH password or to save or cache
    that password. The latter might be construed as as a feature, rather
    than a bug.

    The application will appear to hang while a search is in progress. How
    noticeable that is will depend on how large your mailboxes are and how
    busy your network connection is (if applicable).

    The status bar does not update before a search is made or a directory
    listing is compiled.

    The "Inverse match" option does not do what you might expect. The state
    of the "and/or" radio buttons is ignored and the contents of the "Not"
    field remains uninverted. At the moment, I am disinclined fix this bug,
    as it would only make the meaning of "Inverse match" more confusing than
    it already is.
