source: doc/intro.txt @ e38f315

                     ========================
                     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 Owl supports AIM & zephyr,
but other messaging protocols, including 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 configuration file, so to get started
just run the program.  Owl will take over the terminal window it is
started in, so you may wish to have another terminal window available
at the same time.

On Athena you can find owl in the ktools locker.  To run it, type:

     add ktools
     owl

at the Athena% prompt.  If you wish to run the latest beta release of
owl use:

     add ktools
     owl-beta

instead.  The beta release will often have newer features, but is not
as tried and true as the production release.  As a result it may be
less stable.

The Screen Layout
-----------------
There are three main parts to the owl screen.  The large top portion
of the screen is where messages are displayed.  The status bar
separates this area from the one below and displays owl status
information.  The space below that is used to type 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, described later.

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.

Sending an AIM message
----------------------

Before sending an AIM message you must login to AOL Instant Messenger.
Use the 'aimlogin' command, with your screenname as an argument:

     aimlogin <screenname>

You will be prompted for your password, which you must enter.  Once
you are successfully logged in you can send an AIM message by pressing
the 'a' key, which will bring up an 'aimwrite' command:

     aimwrite <screenname>

Supply the screen name you wish to write to as an argument and then
send the message just as you would send a zephyr, as described above.

Manipulating Messages
---------------------
When there are 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 or down  move to the next message
     C-p or 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
with the 'd' key, 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 message sent to you there is a reply
shortcut:

     r            Reply.  Personal messages get a personal reply,
                       group messages get a group reply.
     R            Reply to sender.  Always replies personally
                       to the sender.
     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 functions that can be performed with a single keystroke:

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

Command Mode
------------
Owl has a command mode from which 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

And for detailed information on the syntax and use of a command you
can use:

     help <command>

For example "help zwrite" will display all the options available when
using the zwrite command.

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:

     print

Owl will show you the value of all variables.  You can also use

     show variables

     show variable <variable>

To display further information on owl variables.


================
Section 3: VIEWS
================

Owl always displays a current "view" of messages.  The view describes
which set of messages should be included on the display.  The default
view is called "all" and includes every message.  However, you can
narrow the view to a particular set of messages:

     M-n          Narrow view to the selected conversation
     M-N          Narrow view to selected conversation by instance
     V            Return to the home view (the 'all' view)
     X            Expunge messages and return to home view

If you press M-n while the pointer is on a personal message, the view
will be narrowed to the conversation with that user only.  If used on
a group message the conversation will be narrowed to that group.

There are also some Owl commands related to views:

     viewclass <class>     Narrow the view to the named zephyr class
     viewuser <user>       Narrow the view to the named user

More information on views and how they work is included in the section
on "FILTERS AND COLORS".

=============================
Section 4: FILTERS AND COLORS
=============================

Filters
-------
Owl will allow you to create custom message filters.  A message filter
is an expression that matches a set of messages based on certain
criteria.  Owl comes with a number of build-in filters already.  You can
view a list of them with the command:

     show filters

The default filters include:

     all              Matches all messages
     none             Matches no messages
     personal         Only personal messages (no group messages)
     login            Login/Logout notifications
     auto             Messages generated by automated programs
     out              Messages sent from you to another user
     aim              AIM messages
     zephyr           Zephyr messages
     trash            "Trash" messages
     ping             Zephyr pings
     reply-lockout    Messages for which the reply commands
                          should not work

If you wish to view the messages that match a particular filter, use
the 'view' command.  For example:

     view personal

This will display only personal messages on the screen.  You can
change back to the 'all' view by pressing the 'V' key (capitalized).
Note that the 'v' key (not capitalized) is a shortcut to bring up the
'view' command.

You can also create your own filters.  For more information on this,
consult the Owl Advanced Users Guide.

Colors
------
Every filter can have a color associated with it.  Messages matching
the filter will then be displayed in that color if your terminal
supports it.  The color for a filter can be set by using the '-c'
option to the filter command.  For example:

     filter personal -c white

This cause all messages in the 'personal' filter to be displayed in
white.  You can produce a list of the colors available to Owl with the
command:

     show colors

If a message matches more than one filter it will be displayed in the
color specified in the last filter listed in the 'show filters'
command.

If you would like your color settings to persist, such that they are
preset every time you start Owl, please read the "Saving Your
Settings" section below.

===============================
Section 5: SAVING YOUR SETTINGS
===============================

Any changes you make to Owl are lost when the program is terminated,
unless you specify otherwise.  If you would like a setting to persist
such that it is available every time you start Owl you can use the
word 'startup' before any command.  For example:

     startup filter personal -c white

Will instruct Owl to color personal messages white both in the current
session and in any future Owl session.  You may revert this behavior
with the 'unstartup' command:

     unstartup filter personal -c white

which will not affect the current session, but will cause future
sessions not to take this action.

Here is another example, this instructs Owl to display zephyr ping
messages:

     startup set rxping on

==========================
Section 6: THE CONFIG FILE
==========================

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

The ~/.owlconf file is interpreted by the perl interpreter.  You may
specify an alternate file by running owl with "owl -c <configfile>".

If you wish to execute an owl command from .owlconf use the function
owl::command().  i.e.:

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

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 to format messages when using the perl style.
                       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

Both owl::format_msg and owl::receive_msg are passed perl owl::Message
objects which contain attributes of the message.  Please see the
advanced.txt file for further documentation of the Perl extension API.

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 4: KEYBINDINGS AND COMMAND ALIASES
==========================================

Aliases
-------

Command aliases allow users to create shortcuts
for commonly used commands.  Aliases can be created wit
the alias command:

    alias NAME VALUE

For example:

    alias zw zwrite

Will make "zw" an alias for the zwrite command.  As such, "zw aphacker"
will be expanded to "zwrite aphacker".  If the value of an
alias is multiple words, use of the alias will result in the alias
command name being replaced by the sequence of words.
Any arguments following the alias name will be appended
after the expanded alias value.  For example:

   alias vs view -s

will result in "vs standard" being expanded to "view -s standard".
There is not yet any way to allow an alias to take arguments
that will be inserted in the middle of the expansion.


Separating Commands
-------------------

Multiple commands can be grouped together with parentheses
and then separated by semicolons.  For example:

   ( smartnarrow ; delete view ; expunge ; view all )

Will result in the four commands being executed
in sequence.  This is particularly useful with key bindings
and coommands.  For example:

   alias sn-delete ( smartnarrow ; delete view )

will create an "sn-delete" alias that will smartnarrow
to a view and them mark the view for deletion.

Using "show commands" will list all existing aliases.


Key Bindings
------------

New key bindings may be created with the "bindkey" command.  Each key
binding is associated with a particular keymap which is applicable in
a particular context/situation.  When the key associated with a
binding is pressed in the right context, it will result in an owl
command being run.  The syntax is:

   bindkey <keymap> <keyseq> command <command>

For example:

   bindkey recv C-k command delete 

will bind Control-k to the delete command, but only in the 
recv window context.

Some keymaps inherit their bindings from more 
general keymaps.  The valid keymaps are:

  - global            - owl-wide defaults (apply everywhere)
    |-edit            - all text editing and command windows
    |  |-editmulti    - multi-line text editing windows
    |  |-editline     - single-line editing and command windows
    |  |-editresponse - single-line responses to questions
    |-popless         - scrolling pop-up windows
    |-recv            - the main message list window 
                        where received messages are displayed

The existing key bindings can be shown with "show keymaps".
The use of "show commands" will list all available commands.
Note that not all commands may be used in all contexts.

Key sequences may be surrounded by quotes and include 
a sequence of keys that must be pressed in order
to execute the command.  For example:

   bindkey recv "C-s v" command view -s vt

will result in "Control-s" followed by "v" in the recv window
causing the command "view -s vt" to be run.