source: doc/intro.txt @ 3713b86

release-1.10release-1.4release-1.5release-1.6release-1.7release-1.8release-1.9
Last change on this file since 3713b86 was d7cc50b, checked in by Anders Kaseorg <andersk@mit.edu>, 15 years ago
Death to more RCS keywords. Signed-off-by: Anders Kaseorg <andersk@mit.edu>
  • 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
332The ~/.owlconf file is interpreted by the perl interpreter.  You may
333specify an alternate file by running owl with "owl -c <configfile>".
334
335If you wish to execute an owl command from .owlconf use the function
336owl::command().  i.e.:
337
338     owl::command('set zsigproc "/mit/kretch/bin/getzsig foo"');
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 perl owl::Message
354objects which contain attributes of the message.  Please see the
355advanced.txt file for further documentation of the Perl extension API.
356
357The "appendtosepbar" variable may be set in owl::format_msg() to set
358text to be appended to sepbar that separates the received message list
359from the edit window.
360
361
362==========================================
363Section 4: KEYBINDINGS AND COMMAND ALIASES
364==========================================
365
366Aliases
367-------
368
369Command aliases allow users to create shortcuts
370for commonly used commands.  Aliases can be created wit
371the alias command:
372
373    alias NAME VALUE
374
375For example:
376
377    alias zw zwrite
378
379Will make "zw" an alias for the zwrite command.  As such, "zw aphacker"
380will be expanded to "zwrite aphacker".  If the value of an
381alias is multiple words, use of the alias will result in the alias
382command name being replaced by the sequence of words.
383Any arguments following the alias name will be appended
384after the expanded alias value.  For example:
385
386   alias vs view -s
387
388will result in "vs standard" being expanded to "view -s standard".
389There is not yet any way to allow an alias to take arguments
390that will be inserted in the middle of the expansion.
391
392
393Separating Commands
394-------------------
395
396Multiple commands can be grouped together with parentheses
397and then separated by semicolons.  For example:
398
399   ( smartnarrow ; delete view ; expunge ; view all )
400
401Will result in the four commands being executed
402in sequence.  This is particularly useful with key bindings
403and coommands.  For example:
404
405   alias sn-delete ( smartnarrow ; delete view )
406
407will create an "sn-delete" alias that will smartnarrow
408to a view and them mark the view for deletion.
409
410Using "show commands" will list all existing aliases.
411
412
413Key Bindings
414------------
415
416New key bindings may be created with the "bindkey" command.  Each key
417binding is associated with a particular keymap which is applicable in
418a particular context/situation.  When the key associated with a
419binding is pressed in the right context, it will result in an owl
420command being run.  The syntax is:
421
422   bindkey <keymap> <keyseq> command <command>
423
424For example:
425
426   bindkey recv C-k command delete
427
428will bind Control-k to the delete command, but only in the
429recv window context.
430
431Some keymaps inherit their bindings from more
432general keymaps.  The valid keymaps are:
433
434  - global            - owl-wide defaults (apply everywhere)
435    |-edit            - all text editing and command windows
436    |  |-editmulti    - multi-line text editing windows
437    |  |-editline     - single-line editing and command windows
438    |  |-editresponse - single-line responses to questions
439    |-popless         - scrolling pop-up windows
440    |-recv            - the main message list window
441                        where received messages are displayed
442
443The existing key bindings can be shown with "show keymaps".
444The use of "show commands" will list all available commands.
445Note that not all commands may be used in all contexts.
446
447Key sequences may be surrounded by quotes and include
448a sequence of keys that must be pressed in order
449to execute the command.  For example:
450
451   bindkey recv "C-s v" command view -s vt
452
453will result in "Control-s" followed by "v" in the recv window
454causing the command "view -s vt" to be run.
Note: See TracBrowser for help on using the repository browser.