source: doc/intro.txt @ 5d9c664

barnowl_perlaimdebianowlrelease-1.10release-1.4release-1.5release-1.6release-1.7release-1.8release-1.9
Last change on this file since 5d9c664 was 675ce49, checked in by James M. Kretchmar <kretch@mit.edu>, 21 years ago
*** empty log message ***
  • Property mode set to 100644
File size: 12.4 KB
Line 
1                     ========================
2                     Quick Guide To Using Owl
3                     ========================
4
5=======================
6Section 1: INTRODUCTION
7=======================
8
9Owl is a tty, curses-based instant messaging client.  This is a quick
10guide to learning how to use it.  Currently Owl supports AIM & zephyr,
11but other messaging protocols, including Jabber, are on the way.  Some
12major features of owl include:
13
14   o) As a tty client it can be run over telnet, rlogin or text ssh
15      sessions
16
17   o) It uses a perl configuration file for setting preferences and
18      formatting messages
19
20   o) Emacs style editing of messages
21
22   o) It is easy to use and runs without a configfile.
23
24   o) Advanced sorting and coloring of messages
25
26==========================
27Section 2: GETTING STARTED
28==========================
29
30Owl will run happily without a configuration file, so to get started
31just run the program.  Owl will take over the terminal window it is
32started in, so you may wish to have another terminal window available
33at the same time.
34
35On Athena you can find owl in the ktools locker.  To run it, type:
36
37     add ktools
38     owl
39
40at the Athena% prompt.  If you wish to run the latest beta release of
41owl use:
42
43     add ktools
44     owl-beta
45
46instead.  The beta release will often have newer features, but is not
47as tried and true as the production release.  As a result it may be
48less stable.
49
50The Screen Layout
51-----------------
52There are three main parts to the owl screen.  The large top portion
53of the screen is where messages are displayed.  The status bar
54separates this area from the one below and displays owl status
55information.  The space below that is used to type messages and is
56also used by owl to give warnings and information to the user.
57
58On Line Help
59------------
60Owl has a full on line help system.  Pressing the 'h' key will bring
61up the basic help screen.  Further help can be obtained using the help
62command, described later.
63
64Sending a Zephyr
65----------------
66To send a zephyr press the 'z' key.  This will start a zwrite command,
67which you can finish by typing the name of the user you wish to send
68to, followed by enter.  Begin typing your message.  You will notice
69that most emacs-style editing is available.  When you are ready to
70send the message type Control-D or a dot ('.') on a line by itself.
71If instead you wish to cancel the message type Control-C.
72
73If you wish to send to a class/instance pair simply supply -c and -i
74arguments to the zwrite command as you normally would.
75
76Sending an AIM message
77----------------------
78
79Before sending an AIM message you must login to AOL Instant Messenger.
80Use the 'aimlogin' command, with your screenname as an argument:
81
82     aimlogin <screenname>
83
84You will be prompted for your password, which you must enter.  Once
85you are successfully logged in you can send an AIM message by pressing
86the 'a' key, which will bring up an 'aimwrite' command:
87
88     aimwrite <screenname>
89
90Supply the screen name you wish to write to as an argument and then
91send the message just as you would send a zephyr, as described above.
92
93Manipulating Messages
94---------------------
95When there are zephyrs in the message window, one of them will be the
96'current' message.  Owl will indicate which one it is with an arrow
97that looks like this: -> The following keys will move you to different
98messages:
99
100     n            move to the next non-deleted message
101     p            move to the previous non-deleted message
102     C-n or down  move to the next message
103     C-p or up    move to the previous message
104     <            move to the first message
105     >            move to the last message
106     C-v          page down
107     M-v          page up
108     right        scroll the screen to the right
109     left         scroll the screen to the left
110     P            move to the next personal message
111     M-P          move to the previous personal message
112
113When you are ready to delete a message you can mark it for deletion
114with the 'd' key, and a 'D' will appear to the left of the message.
115Messages will not actually be removed until you perform an expunge.
116The following keys are used to delete, undelete and expunge messages:
117
118     d            mark a message for deletion
119     u            unmark a message for deletion
120     x            expunge deleted messages
121     T            mark all 'trash' messages for deletion
122     M-D          mark all messages in the view for deletion
123     M-u          unmark all messages in the view for deletion
124
125If you would like to respond to a message sent to you there is a reply
126shortcut:
127
128     r            Reply.  Personal messages get a personal reply,
129                       group messages get a group reply.
130     R            Reply to sender.  Always replies personally
131                       to the sender.
132     M-r          Reply but allow editing of the command line.
133     M-R          Reply to sender but allow editing of the
134                       command line.
135
136In the event that the current message is too large to fit on the
137screen, you can scroll within the message using the following keys:
138
139     SPACE        page down
140     b            page up
141     RETURN       line down
142     BACKSPACE    line up
143
144The message pointer will change to indicate that the message is not
145starting at the first line.
146
147Two other keys that relate to the current message:
148
149     i            print detailed information about the message
150     w            instruct netscape to visit a URL in the message
151
152Other Functions
153----------------
154Some other functions that can be performed with a single keystroke:
155
156     A            toggle zephyr zaway on or off
157     C-l          refresh and resize the screen
158     C-z          suspend
159
160Command Mode
161------------
162Owl has a command mode from which you can enter more detailed commands
163for Owl to process.  To enter command mode press the colon (':') key:
164
165     :            begin command mode
166
167Owl will give you a command prompt and you can begin typing your
168command.  Type Enter to execute the command, Control-C to cancel.
169There are many commands.  The basic commands are listed on the basic
170help screen (by pressing 'h').  If you'd like a list of all commands
171you can use the command:
172
173     show commands
174
175And for detailed information on the syntax and use of a command you
176can use:
177
178     help <command>
179
180For example "help zwrite" will display all the options available when
181using the zwrite command.
182
183Variables
184---------
185Owl has a number of internal variables that can be used to change the
186behavior the program.  The 'print' command will let you view the value
187of a variable and the 'set' commmand will let you set the value of a
188variable.  For example:
189
190     set personalbell on
191
192will set the value of the variable 'personalbell' to 'on'.  The
193command:
194
195     print personalbell
196
197will show you the current value.  The 'print' command with no
198arguments:
199
200     print
201
202Owl will show you the value of all variables.  You can also use
203
204     show variables
205
206     show variable <variable>
207
208To display further information on owl variables.
209
210
211================
212Section 3: VIEWS
213================
214
215Owl always displays a current "view" of messages.  The view describes
216which set of messages should be included on the display.  The default
217view is called "all" and includes every message.  However, you can
218narrow the view to a particular set of messages:
219
220     M-n          Narrow view to the selected conversation
221     M-N          Narrow view to selected conversation by instance
222     V            Return to the home view (the 'all' view)
223     X            Expunge messages and return to home view
224
225If you press M-n while the pointer is on a personal message, the view
226will be narrowed to the conversation with that user only.  If used on
227a group message the conversation will be narrowed to that group.
228
229There are also some Owl commands related to views:
230
231     viewclass <class>     Narrow the view to the named zephyr class
232     viewuser <user>       Narrow the view to the named user
233
234More information on views and how they work is included in the section
235on "FILTERS AND COLORS".
236
237=============================
238Section 4: FILTERS AND COLORS
239=============================
240
241Filters
242-------
243Owl will allow you to create custom message filters.  A message filter
244is an expression that matches a set of messages based on certain
245criteria.  Owl comes with a number of build-in filters already.  You can
246view a list of them with the command:
247
248     show filters
249
250The default filters include:
251
252     all              Matches all messages
253     none             Matches no messages
254     personal         Only personal messages (no group messages)
255     login            Login/Logout notifications
256     auto             Messages generated by automated programs
257     out              Messages sent from you to another user
258     aim              AIM messages
259     zephyr           Zephyr messages
260     trash            "Trash" messages
261     ping             Zephyr pings
262     reply-lockout    Messages for which the reply commands
263                          should not work
264
265If you wish to view the messages that match a particular filter, use
266the 'view' command.  For example:
267
268     view personal
269
270This will display only personal messages on the screen.  You can
271change back to the 'all' view by pressing the 'V' key (capitalized).
272Note that the 'v' key (not capitalized) is a shortcut to bring up the
273'view' command.
274
275You can also create your own filters.  For more information on this,
276consult the Owl Advanced Users Guide.
277
278Colors
279------
280Every filter can have a color associated with it.  Messages matching
281the filter will then be displayed in that color if your terminal
282supports it.  The color for a filter can be set by using the '-c'
283option to the filter command.  For example:
284
285     filter personal -c white
286
287This cause all messages in the 'personal' filter to be displayed in
288white.  You can produce a list of the colors available to Owl with the
289command:
290
291     show colors
292
293If a message matches more than one filter it will be displayed in the
294color specified in the last filter listed in the 'show filters'
295command.
296
297If you would like your color settings to persist, such that they are
298preset every time you start Owl, please read the "Saving Your
299Settings" section below.
300
301===============================
302Section 5: SAVING YOUR SETTINGS
303===============================
304
305Any changes you make to Owl are lost when the program is terminated,
306unless you specify otherwise.  If you would like a setting to persist
307such that it is available every time you start Owl you can use the
308word 'startup' before any command.  For example:
309
310     startup filter personal -c white
311
312Will instruct Owl to color personal messages white both in the current
313session and in any future Owl session.  You may revert this behavior
314with the 'unstartup' command:
315
316     unstartup filter personal -c white
317
318which will not affect the current session, but will cause future
319sessions not to take this action.
320
321Here is another example, this instructs Owl to display zephyr ping
322messages:
323
324     startup set rxping on
325
326==========================
327Section 6: THE CONFIG FILE
328==========================
329
330*** WARNING: This interface may change substantially in the near future ***
331
332This file is interpreted by the perl interpreter.
333If you wish to execute an owl command use the
334function owl::command().  i.e.
335
336     owl::command("set zsigproc \"/mit/kretch/bin/getzsig foo\"");
337
338will set the owl variable zsigproc.  Note that commands will currently
339be executed in order after the called configuration subroutine exits.
340
341Subroutines created with the names below will be executed at the
342specified times:
343
344    subroutine name    properties
345    ---------------    ----------
346    owl::startup()     run when owl first starts
347    owl::shutdown()    run when owl exits
348    owl::format_msg()  run when a new message arrives, the return
349                          value is used to display the message on the
350                          screen
351    owl::receive_msg() run when a message is received, and after
352                       it has been added to the message list
353
354
355The following variables will be set each time a message is recevied:
356
357    $owl::class, $owl::instance, $owl::recipient,
358    $owl::sender, $owl::opcode, $owl::zsig,
359    $owl::msg, $owl::time, $owl::host, @owl::fields, $owl::id
360
361The "appendtosepbar" variable may be set in owl::format_msg()
362to set text to be appended to sepbar that separates the received
363message list from the edit window.
364
365
366==========================================
367Section 4: KEYBINDINGS AND COMMAND ALIASES
368==========================================
369
370
371==============================
372Section 6: FURTHER INFORMATION
373==============================
374
375$Id$
Note: See TracBrowser for help on using the repository browser.