source: doc/intro.txt @ aa2f6364

                     ========================
                     Quick Guide To Using Owl
                     ========================

=======================
Section 1: INTRODUCTION
=======================

Owl is a tty, curses-based instant messaging client.  This is a quick
guide to learning how to use it.  Currently it supports only zephyr,
but other messaging protocols, including AIM and Jabber, are on the
way.  Some major features of owl include:

   o) As a tty client it can be run over telnet, rlogin or text ssh
      sessions

   o) It uses a perl configuration file for setting preferences and
      formatting messages

   o) Emacs style editing of messages

   o) It is easy to use and runs without a configfile.

   o) Advanced sorting and coloring of messages

==========================
Section 2: GETTING STARTED
==========================

Owl will run happily without a configfile, so to get started just run
the program.  Owl will take over the terminal window it's started in,
so you may wish to have another terminal around at the same time.

On Athena you can find owl in the ktools locker.  So to run it you can
type:

        add ktools
        owl

at the Athena% prompt.  If you wish to run the latest beta release of
owl type 'owl-beta' instead of 'owl'.

The Screen Layout
-----------------
There are three main parts to the owl screen.  The large top portion
of the screen is where zephyrs are displayed.  The status bar
separates this area from the one below and displays some status
information.  The space below that is used to type in messages and is
also used by owl to give warnings and information to the user.

On Line Help
------------
Owl has a full on line help system.  Pressing the 'h' key will bring
up the basic help screen.  Further help can be obtained using the help
command.

Sending a Zephyr
----------------
To send a zephyr press the 'z' key.  This will start a zwrite command,
which you can finish by typing the name of the user you wish to send
to, followed by enter.  Begin typing your message.  You will notice
that most emacs-style editing is available.  When you are ready to
send the message type Control-D or a dot ('.') on a line by itself.
If instead you wish to cancel the message type Control-C.

If you wish to send to a class/instance pair simply supply -c and -i
arguments to the zwrite command as you normally would.

Manipulating Messages
---------------------
When there are one or more zephyrs in the message window, one of them
will be the 'current' message.  Owl will indicate which one it is with
an arrow that looks like this: -> .  The following keys will move you
to different messages:

        n               move to the next non-deleted message
        p               move to the previous non-deleted message
        C-n , down      move to the next message
        C-p , up        move to the previous message
        <               move to the first message
        >               move to the last message
        C-v             page down
        M-v             page up
        right           scroll the screen to the right
        left            scroll the screen to the left
        P               move to the next personal message
        M-P             move to the previous personal message

When you are ready to delete a message you can mark it for deletion
and a 'D' will appear to the left of the message.  Messages will not
actually be removed until you perform an expunge.  The following keys
are used to delete, undelete and expunge messages:

        d               mark a message for deletion
        u               unmark a message for deletion
        x               expunge deleted messages
        T               mark all 'trash' messages for deletion
        M-D             mark all messages in the view for deletion
        M-u             unmark all messages in the view for deletion

If you would like to respond to a zephyr sent to you there is a reply
shortcut.

        r               Reply.  Personal zephyrs get a personal reply,
                        class/instance zephyrs get a public reply.
        R               Reply to sender.  Always replies personally
                        to the user.
        M-r             Reply but allow editing of the command line.
        M-R             Reply to sender but allow editing of the
                        command line.

In the event that the current message is too large to fit on the
screen, you can scroll within the message using the following keys:

        SPACE           page down
        b               page up
        RETURN          line down
        BACKSPACE       line up

The message pointer will change to indicate that the message is not
starting at the first line.

Two other keys that relate to the current message:

        i               print detailed information about the message
        w               instruct netscape to visit a URL in the message


Other Functions
----------------
Some other funcions that can be performed with a single keystroke:

        A               toggle zaway on or off
        C-l             refresh and resize the screen
        C-z             suspend

Command Mode
------------
Owl has a command mode where you can enter more detailed commands for
owl to process.  To enter command mode press the colon (':') key:

        :               begin command mode

Owl will give you a command prompt and you can begin typing your
command.  Type Enter to execute the command, Control-C to cancel.
There are many commands.  The basic commands are listed on the basic
help screen (by pressing 'h').  If you'd like a list of all commands
you can use the command "show commands".  To get detailed information
on the syntax and use of a command you can use the command 'help
<command>' as in:

        help zwrite

Variables
---------

Owl has a number of internal variables that can be used to change the
behavior the program.  The 'print' command will let you view the value
of a variable and the 'set' commmand will let you set the value of a
variable.  For example:

        set personalbell on 

will set the value of the variable 'personalbell' to on.  The command:

        print personalbell

will show you the current value.  The 'print' command with no
arguments will show you the value of all variables.  A list of all
variables is available on the basic help screen, or by using the
command "show variables".  The command "show variable <variablename>"
will show you detailed information about a variable and how to use it.
As in:

        show variable personalbell

=============================
Section 3: FILTERS AND COLORS
=============================



==========================
Section 4: THE CONFIG FILE
==========================

*** WARNING: This interface may change substantially in the near future ***

This file is interpreted by the perl interpreter.
If you wish to execute an owl command use the
function owl::command().  i.e.

     owl::command("set zsigproc \"/mit/kretch/bin/getzsig foo\"");

will set the owl variable zsigproc.  Note that commands will currently
be executed in order after the called configuration subroutine exits.

Subroutines created with the names below will be executed at the
specified times:

    subroutine name    properties
    ---------------    ----------
    owl::startup()     run when owl first starts
    owl::shutdown()    run when owl exits
    owl::format_msg()  run when a new message arrives, the return
                          value is used to display the message on the
                          screen
    owl::receive_msg() run when a message is received, and after
                       it has been added to the message list


The following variables will be set each time a message is recevied:

    $owl::class, $owl::instance, $owl::recipient,
    $owl::sender, $owl::opcode, $owl::zsig,
    $owl::msg, $owl::time, $owl::host, @owl::fields, $owl::id

The "appendtosepbar" variable may be set in owl::format_msg()
to set text to be appended to sepbar that separates the received
message list from the edit window.


==============================
Section 5: FURTHER INFORMATION
==============================

$Id$