---------------------------------------------------------------------------
SIMAP4 README.en
---------------------------------------------------------------------------
simap4.el --- A simple IMAP4 (RFC 2060) protocol driver module
simap4-console.el --- An Emacs mode to intractively examine IMAP server.
---------------------------------------------------------------------------

Abstract
----

simap4.el is an elisp library intended for use by Emacs elisp
programs, to connect and exchange internet messages with IMAP4rev1
(RFC 2060) Servers. It is assumed that the library is used by MUA
programs which run on Emacs. Only default authorization method is
supported, and it's just to convert IMAP4rev1 commands and responses
defined in RFC 2060 to lisp forms for easy use with Emacs lisp
programs.

simap4-console.el is a command line based user interface to execute
simap4 functions and run as a major mode on Emacs. A purpose of this
program is to help debugging of simap4 library.


Install
-------

Since there are only few files (essentially only simap4.el), manual
copy and compilation would be the fastest way to install. Make a
directory with appropriate name like simap4, and copy simap4.el there.
To compile, a simple way is to use dired mode, and type "B"
(dired-do-byte-compile) on the line of simap4.el. If you want to
install simap4-control.el as well, do the same procedure as simap4.el.

make (Unix) and makeit.bat (Windows) may be used to compile and
install.  To use make, edit EMACS and INSTALLDIR in Makefile as
appropriate for your environment, and run make install. To use
makeit.bat, copy makeit.bat to a file such as %HOME%/.elispmk and set
necessary environment variables (PREFIX, EMACS, EXEC_PREFIX, LISPDIR,
INFODIR, VERSION_SPECIFIC_LISPDIR) and run ./makeit.bat
install. Please refer to the header comment part of makeit.bat file,
where more detailed information can be found.

Usage
-----

Since simap4.el itself is a program library, there is no user visible
usage. For usage of functions defined in this library, please see
simap4.el and RFC 2060.


To use simap4-console.el, load the program and type M-x
simap4-console. It will prompt for a name of the server you want to
connect, so type the server name. If it has been already connected by
other application program, it will enter command mode. (The opened
connection will be used.) If not connected yet, it prompts for login
name and password. Enter them, then it will enter command mode.

Following is an example of command mode buffer.

  -- SIMAP4 Console -- type help for usage.
  SIMAP4> 


Type IMAP4 command at SIMAP4> prompt, then the result will be
displayed.

Examples of commands:
  SIMAP4> connect
  SIMAP4> login
  SIMAP4> list "\"\"" "*"
  SIMAP4> select inbox
  SIMAP4> search "all"

Other than IMAP4 protocol related commands, it supports native
commands such as help, print and showbuf. Help command shows a list of
commands. Or it shows usage of IMAP4 protocol command if protocol
command is given as an argument. Print command will show information
about the connected IMAP4 session. Showbuf displays the IMAP4 process
buffer in other window.

The following is an example session log, which monitored a IMAP4
session that has been already established by other program. It gives a
convenient way to confirm its execution while running other program in
another frame/window.

-----------------------------------------------------------------------------
-- SIMAP4 Console -- type help for usage.
SIMAP4> showbuf
SIMAP4> expunge
proc: imap4
selected-mailbox: inbox
state: selected
last-command-string: expunge
last-command-start: 527
last-command-end: 564
last-command-result: OK
last-command-explanation: Completed
resp-exists: 5
resp-recent: 0
resp-expunge: (6)
SIMAP4> check
proc: imap4
selected-mailbox: inbox
state: selected
last-command-string: check
last-command-start: 588
last-command-end: 588
last-command-result: OK
last-command-explanation: Completed
SIMAP4> check
proc: imap4
selected-mailbox: inbox
state: selected
last-command-string: check
last-command-start: 636
last-command-end: 660
last-command-result: OK
last-command-explanation: Completed
resp-exists: 6
resp-recent: 1
SIMAP4> print resp
resp-ok: nil
resp-no: nil
resp-bad: nil
resp-preauth: nil
resp-bye: nil
resp-capability: nil
resp-list: nil
resp-lsub: nil
resp-status: nil
resp-search: nil
resp-exists: nil
resp-recent: nil
resp-expunge: nil
resp-fetch: nil
SIMAP4> expunge
proc: imap4
selected-mailbox: inbox
state: selected
last-command-string: expunge
last-command-start: 12241
last-command-end: 12343
last-command-result: OK
last-command-explanation: Completed
resp-exists: 0
resp-recent: 0
resp-expunge: (1 1 1 1 1 1)
SIMAP4> 
-----------------------------------------------------------------------------
