---------------------------------------------------------------------------
ONLINE README.ja
---------------------------------------------------------------------------
online.el --- A elisp program to monitor reachability of the servers.
---------------------------------------------------------------------------

Abstract
--------

The purpose of this program is to gurantee relatively short response
time for a TCP connection establishment attempt even when the server
cannot be reached and expected to fail, plus provide a way to query
reasonably recent status of server reachability. It also provides
hooks to automatically execute procedures when reachability status
changes between off-line and on-line. This may be useful when changing
status display, and any background synchronization of off-line mode
work. Additional features provided include:

  o A hook function to display status on the mode line. 
  o Statistics report. 


Known Emacsen & versions and OS that work with online.el
--------------------------------------------------------

  o GNU Emacs 20.6 / FreeBSD 3.4 (166MHz Pentium) 
  o Meadow 1.10 / Windows NT (366MHz Pentium II) 
  o Meadow 1.14 / Windows 2000 (400Hz Celaron)
  o Mule 2.3 on GNU Emacs 19.34 / FreeBSD 3.4 (166MHz Pentium) 


Other information, usage, etc. 
------------------------------

To install, place this file in your load-path (and byte compile if you
like). 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.

To use the basic open-network-stream extention, simply load
this module from your .emacs file, by:

  (load "online")

You can use customize to change option values once the module is loaded. M-x customize-group and type online to invoke the customize for this. 
If you'd like to display online status on the mode line, you need to customize online-display-status-servers to list servers. 

If you would like to display online status on the mode line, set
online-display-status-servers to a list of server names in string, and
reload online.el. For example, evaluating the below:

  (setq online-display-status-servers '("mail.ml-search.com"))
  (load "online")

will display [*] (online status) or [-] (offline status) on the mode
line. ([?] is also possible, which means the status is not known yet
since no check has been done yet.) If multiple server names are
listed, the status of each server will be displayed, one status
character for each server, in the order it appears in the list. For
example, when 4 servers are listed, and only the 3rd server is
reachable, then mode line would disply [--*-].

The following is M-x online-report-stats display shapshot. 

-------------------------------------------------------------------------
Server                     status   max  min  ave atmpt  succ  +hit  -hit
-------------------------- ------- ---- ---- ---- ----- ----- ----- -----
localhost                : online     2    2    2     1     1     0     0
mail.ml-search.com       : online   371  326  353     3     3     0     2
www.ml-search.com        : online  1217  399  808     2     2     0     0


Ping process invoke time (msec):     12
Ping process attempt count:          22
-------------------------------------------------------------------------

Other documentation (design note etc.) is also available in the header part of online.el. 


BUGS
----

When connecting over a low bandwidth connection and other high volume
activities such as download is happening, this program sometimes
detects a off-line condition since ping may not come back in
time. This is not a major problem, since by adjusting timer values
this false detection could be reduced, and once the high volume
activity stops then a online condition will be detected
again. However, there is some room for improvement in this area.
