source: doc/intro.txt @ 7e6d1fd

barnowl_perlaimdebianowlrelease-1.4release-1.5release-1.6release-1.7release-1.8release-1.9
Last change on this file since 7e6d1fd was c82b055, checked in by Erik Nygren <nygren@mit.edu>, 18 years ago
Updated intro.txt and advanced.txt documents (still in progress).
  • Property mode set to 100644
File size: 15.0 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. 
339
340Subroutines created with the names below will be executed at the
341specified times:
342
343    subroutine name    properties
344    ---------------    ----------
345    owl::startup()     run when owl first starts
346    owl::shutdown()    run when owl exits
347    owl::format_msg()  run to format messages when using the perl style.
348                       The return value is used to display the message on the
349                       screen.
350    owl::receive_msg() run when a message is received, and after
351                       it has been added to the message list
352
353Both owl::format_msg and owl::receive_msg are passed
354perl owl::Message objects which contain attributes of the message.
355Please see the advanced.txt file for further documentation
356of the Perl extension API.
357
358The "appendtosepbar" variable may be set in owl::format_msg()
359to set text to be appended to sepbar that separates the received
360message list from the edit window.
361
362
363==========================================
364Section 4: KEYBINDINGS AND COMMAND ALIASES
365==========================================
366
367Aliases
368-------
369
370Command aliases allow users to create shortcuts
371for commonly used commands.  Aliases can be created wit
372the alias command:
373
374    alias NAME VALUE
375
376For example:
377
378    alias zw zwrite
379
380Will make "zw" an alias for the zwrite command.  As such, "zw aphacker"
381will be expanded to "zwrite aphacker".  If the value of an
382alias is multiple words, use of the alias will result in the alias
383command name being replaced by the sequence of words.
384Any arguments following the alias name will be appended
385after the expanded alias value.  For example:
386
387   alias vs view -s
388
389will result in "vs standard" being expanded to "view -s standard".
390There is not yet any way to allow an alias to take arguments
391that will be inserted in the middle of the expansion.
392
393
394Separating Commands
395-------------------
396
397Multiple commands can be grouped together with parentheses
398and then separated by semicolons.  For example:
399
400   ( smartnarrow ; delete view ; expunge ; view all )
401
402Will result in the four commands being executed
403in sequence.  This is particularly useful with key bindings
404and coommands.  For example:
405
406   alias sn-delete ( smartnarrow ; delete view )
407
408will create an "sn-delete" alias that will smartnarrow
409to a view and them mark the view for deletion.
410
411Using "show commands" will list all existing aliases.
412
413
414Key Bindings
415------------
416
417New key bindings may be created with the "bindkey" command.  Each key
418binding is associated with a particular keymap which is applicable in
419a particular context/situation.  When the key associated with a
420binding is pressed in the right context, it will result in an owl
421command being run.  The syntax is:
422
423   bindkey <keymap> <keyseq> command <command>
424
425For example:
426
427   bindkey recv C-k command delete
428
429will bind Control-k to the delete command, but only in the
430recv window context.
431
432Some keymaps inherit their bindings from more
433general keymaps.  The valid keymaps are:
434
435  - global            - owl-wide defaults (apply everywhere)
436    |-edit            - all text editing and command windows
437    |  |-editmulti    - multi-line text editing windows
438    |  |-editline     - single-line editing and command windows
439    |  |-editresponse - single-line responses to questions
440    |-popless         - scrolling pop-up windows
441    |-recv            - the main message list window
442                        where received messages are displayed
443
444The existing key bindings can be shown with "show keymaps".
445The use of "show commands" will list all available commands.
446Note that not all commands may be used in all contexts.
447
448Key sequences may be surrounded by quotes and include
449a sequence of keys that must be pressed in order
450to execute the command.  For example:
451
452   bindkey recv "C-s v" command view -s vt
453
454will result in "Control-s" followed by "v" in the recv window
455causing the command "view -s vt" to be run.
456
457
458
459==============================
460Section 6: FURTHER INFORMATION
461==============================
462
463$Id$
Note: See TracBrowser for help on using the repository browser.