1 | ======================== |
---|
2 | Quick Guide To Using Owl |
---|
3 | ======================== |
---|
4 | |
---|
5 | ======================= |
---|
6 | Section 1: INTRODUCTION |
---|
7 | ======================= |
---|
8 | |
---|
9 | Owl is a tty, curses-based instant messaging client. This is a quick |
---|
10 | guide to learning how to use it. Currently Owl supports AIM & zephyr, |
---|
11 | but other messaging protocols, including Jabber, are on the way. Some |
---|
12 | major 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 | ========================== |
---|
27 | Section 2: GETTING STARTED |
---|
28 | ========================== |
---|
29 | |
---|
30 | Owl will run happily without a configuration file, so to get started |
---|
31 | just run the program. Owl will take over the terminal window it is |
---|
32 | started in, so you may wish to have another terminal window available |
---|
33 | at the same time. |
---|
34 | |
---|
35 | On Athena you can find owl in the ktools locker. To run it, type: |
---|
36 | |
---|
37 | add ktools |
---|
38 | owl |
---|
39 | |
---|
40 | at the Athena% prompt. If you wish to run the latest beta release of |
---|
41 | owl use: |
---|
42 | |
---|
43 | add ktools |
---|
44 | owl-beta |
---|
45 | |
---|
46 | instead. The beta release will often have newer features, but is not |
---|
47 | as tried and true as the production release. As a result it may be |
---|
48 | less stable. |
---|
49 | |
---|
50 | The Screen Layout |
---|
51 | ----------------- |
---|
52 | There are three main parts to the owl screen. The large top portion |
---|
53 | of the screen is where messages are displayed. The status bar |
---|
54 | separates this area from the one below and displays owl status |
---|
55 | information. The space below that is used to type messages and is |
---|
56 | also used by owl to give warnings and information to the user. |
---|
57 | |
---|
58 | On Line Help |
---|
59 | ------------ |
---|
60 | Owl has a full on line help system. Pressing the 'h' key will bring |
---|
61 | up the basic help screen. Further help can be obtained using the help |
---|
62 | command, described later. |
---|
63 | |
---|
64 | Sending a Zephyr |
---|
65 | ---------------- |
---|
66 | To send a zephyr press the 'z' key. This will start a zwrite command, |
---|
67 | which you can finish by typing the name of the user you wish to send |
---|
68 | to, followed by enter. Begin typing your message. You will notice |
---|
69 | that most emacs-style editing is available. When you are ready to |
---|
70 | send the message type Control-D or a dot ('.') on a line by itself. |
---|
71 | If instead you wish to cancel the message type Control-C. |
---|
72 | |
---|
73 | If you wish to send to a class/instance pair simply supply -c and -i |
---|
74 | arguments to the zwrite command as you normally would. |
---|
75 | |
---|
76 | Sending an AIM message |
---|
77 | ---------------------- |
---|
78 | |
---|
79 | Before sending an AIM message you must login to AOL Instant Messenger. |
---|
80 | Use the 'aimlogin' command, with your screenname as an argument: |
---|
81 | |
---|
82 | aimlogin <screenname> |
---|
83 | |
---|
84 | You will be prompted for your password, which you must enter. Once |
---|
85 | you are successfully logged in you can send an AIM message by pressing |
---|
86 | the 'a' key, which will bring up an 'aimwrite' command: |
---|
87 | |
---|
88 | aimwrite <screenname> |
---|
89 | |
---|
90 | Supply the screen name you wish to write to as an argument and then |
---|
91 | send the message just as you would send a zephyr, as described above. |
---|
92 | |
---|
93 | Manipulating Messages |
---|
94 | --------------------- |
---|
95 | When 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 |
---|
97 | that looks like this: -> The following keys will move you to different |
---|
98 | messages: |
---|
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 | |
---|
113 | When you are ready to delete a message you can mark it for deletion |
---|
114 | with the 'd' key, and a 'D' will appear to the left of the message. |
---|
115 | Messages will not actually be removed until you perform an expunge. |
---|
116 | The 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 | |
---|
125 | If you would like to respond to a message sent to you there is a reply |
---|
126 | shortcut: |
---|
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 | |
---|
136 | In the event that the current message is too large to fit on the |
---|
137 | screen, 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 | |
---|
144 | The message pointer will change to indicate that the message is not |
---|
145 | starting at the first line. |
---|
146 | |
---|
147 | Two 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 | |
---|
152 | Other Functions |
---|
153 | ---------------- |
---|
154 | Some 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 | |
---|
160 | Command Mode |
---|
161 | ------------ |
---|
162 | Owl has a command mode from which you can enter more detailed commands |
---|
163 | for Owl to process. To enter command mode press the colon (':') key: |
---|
164 | |
---|
165 | : begin command mode |
---|
166 | |
---|
167 | Owl will give you a command prompt and you can begin typing your |
---|
168 | command. Type Enter to execute the command, Control-C to cancel. |
---|
169 | There are many commands. The basic commands are listed on the basic |
---|
170 | help screen (by pressing 'h'). If you'd like a list of all commands |
---|
171 | you can use the command: |
---|
172 | |
---|
173 | show commands |
---|
174 | |
---|
175 | And for detailed information on the syntax and use of a command you |
---|
176 | can use: |
---|
177 | |
---|
178 | help <command> |
---|
179 | |
---|
180 | For example "help zwrite" will display all the options available when |
---|
181 | using the zwrite command. |
---|
182 | |
---|
183 | Variables |
---|
184 | --------- |
---|
185 | Owl has a number of internal variables that can be used to change the |
---|
186 | behavior the program. The 'print' command will let you view the value |
---|
187 | of a variable and the 'set' commmand will let you set the value of a |
---|
188 | variable. For example: |
---|
189 | |
---|
190 | set personalbell on |
---|
191 | |
---|
192 | will set the value of the variable 'personalbell' to 'on'. The |
---|
193 | command: |
---|
194 | |
---|
195 | print personalbell |
---|
196 | |
---|
197 | will show you the current value. The 'print' command with no |
---|
198 | arguments: |
---|
199 | |
---|
200 | print |
---|
201 | |
---|
202 | Owl will show you the value of all variables. You can also use |
---|
203 | |
---|
204 | show variables |
---|
205 | |
---|
206 | show variable <variable> |
---|
207 | |
---|
208 | To display further information on owl variables. |
---|
209 | |
---|
210 | |
---|
211 | ================ |
---|
212 | Section 3: VIEWS |
---|
213 | ================ |
---|
214 | |
---|
215 | Owl always displays a current "view" of messages. The view describes |
---|
216 | which set of messages should be included on the display. The default |
---|
217 | view is called "all" and includes every message. However, you can |
---|
218 | narrow 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 | |
---|
225 | If you press M-n while the pointer is on a personal message, the view |
---|
226 | will be narrowed to the conversation with that user only. If used on |
---|
227 | a group message the conversation will be narrowed to that group. |
---|
228 | |
---|
229 | There 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 | |
---|
234 | More information on views and how they work is included in the section |
---|
235 | on "FILTERS AND COLORS". |
---|
236 | |
---|
237 | ============================= |
---|
238 | Section 4: FILTERS AND COLORS |
---|
239 | ============================= |
---|
240 | |
---|
241 | Filters |
---|
242 | ------- |
---|
243 | Owl will allow you to create custom message filters. A message filter |
---|
244 | is an expression that matches a set of messages based on certain |
---|
245 | criteria. Owl comes with a number of build-in filters already. You can |
---|
246 | view a list of them with the command: |
---|
247 | |
---|
248 | show filters |
---|
249 | |
---|
250 | The 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 | |
---|
265 | If you wish to view the messages that match a particular filter, use |
---|
266 | the 'view' command. For example: |
---|
267 | |
---|
268 | view personal |
---|
269 | |
---|
270 | This will display only personal messages on the screen. You can |
---|
271 | change back to the 'all' view by pressing the 'V' key (capitalized). |
---|
272 | Note that the 'v' key (not capitalized) is a shortcut to bring up the |
---|
273 | 'view' command. |
---|
274 | |
---|
275 | You can also create your own filters. For more information on this, |
---|
276 | consult the Owl Advanced Users Guide. |
---|
277 | |
---|
278 | Colors |
---|
279 | ------ |
---|
280 | Every filter can have a color associated with it. Messages matching |
---|
281 | the filter will then be displayed in that color if your terminal |
---|
282 | supports it. The color for a filter can be set by using the '-c' |
---|
283 | option to the filter command. For example: |
---|
284 | |
---|
285 | filter personal -c white |
---|
286 | |
---|
287 | This cause all messages in the 'personal' filter to be displayed in |
---|
288 | white. You can produce a list of the colors available to Owl with the |
---|
289 | command: |
---|
290 | |
---|
291 | show colors |
---|
292 | |
---|
293 | If a message matches more than one filter it will be displayed in the |
---|
294 | color specified in the last filter listed in the 'show filters' |
---|
295 | command. |
---|
296 | |
---|
297 | If you would like your color settings to persist, such that they are |
---|
298 | preset every time you start Owl, please read the "Saving Your |
---|
299 | Settings" section below. |
---|
300 | |
---|
301 | =============================== |
---|
302 | Section 5: SAVING YOUR SETTINGS |
---|
303 | =============================== |
---|
304 | |
---|
305 | Any changes you make to Owl are lost when the program is terminated, |
---|
306 | unless you specify otherwise. If you would like a setting to persist |
---|
307 | such that it is available every time you start Owl you can use the |
---|
308 | word 'startup' before any command. For example: |
---|
309 | |
---|
310 | startup filter personal -c white |
---|
311 | |
---|
312 | Will instruct Owl to color personal messages white both in the current |
---|
313 | session and in any future Owl session. You may revert this behavior |
---|
314 | with the 'unstartup' command: |
---|
315 | |
---|
316 | unstartup filter personal -c white |
---|
317 | |
---|
318 | which will not affect the current session, but will cause future |
---|
319 | sessions not to take this action. |
---|
320 | |
---|
321 | Here is another example, this instructs Owl to display zephyr ping |
---|
322 | messages: |
---|
323 | |
---|
324 | startup set rxping on |
---|
325 | |
---|
326 | ========================== |
---|
327 | Section 6: THE CONFIG FILE |
---|
328 | ========================== |
---|
329 | |
---|
330 | *** WARNING: This interface may change substantially in the near future *** |
---|
331 | |
---|
332 | The ~/.owlconf file is interpreted by the perl interpreter. You may |
---|
333 | specify an alternate file by running owl with "owl -c <configfile>". |
---|
334 | |
---|
335 | If you wish to execute an owl command from .owlconf use the function |
---|
336 | owl::command(). i.e.: |
---|
337 | |
---|
338 | owl::command('set zsigproc "/mit/kretch/bin/getzsig foo"'); |
---|
339 | |
---|
340 | Subroutines created with the names below will be executed at the |
---|
341 | specified 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 | |
---|
353 | Both owl::format_msg and owl::receive_msg are passed perl owl::Message |
---|
354 | objects which contain attributes of the message. Please see the |
---|
355 | advanced.txt file for further documentation of the Perl extension API. |
---|
356 | |
---|
357 | The "appendtosepbar" variable may be set in owl::format_msg() to set |
---|
358 | text to be appended to sepbar that separates the received message list |
---|
359 | from the edit window. |
---|
360 | |
---|
361 | |
---|
362 | ========================================== |
---|
363 | Section 4: KEYBINDINGS AND COMMAND ALIASES |
---|
364 | ========================================== |
---|
365 | |
---|
366 | Aliases |
---|
367 | ------- |
---|
368 | |
---|
369 | Command aliases allow users to create shortcuts |
---|
370 | for commonly used commands. Aliases can be created wit |
---|
371 | the alias command: |
---|
372 | |
---|
373 | alias NAME VALUE |
---|
374 | |
---|
375 | For example: |
---|
376 | |
---|
377 | alias zw zwrite |
---|
378 | |
---|
379 | Will make "zw" an alias for the zwrite command. As such, "zw aphacker" |
---|
380 | will be expanded to "zwrite aphacker". If the value of an |
---|
381 | alias is multiple words, use of the alias will result in the alias |
---|
382 | command name being replaced by the sequence of words. |
---|
383 | Any arguments following the alias name will be appended |
---|
384 | after the expanded alias value. For example: |
---|
385 | |
---|
386 | alias vs view -s |
---|
387 | |
---|
388 | will result in "vs standard" being expanded to "view -s standard". |
---|
389 | There is not yet any way to allow an alias to take arguments |
---|
390 | that will be inserted in the middle of the expansion. |
---|
391 | |
---|
392 | |
---|
393 | Separating Commands |
---|
394 | ------------------- |
---|
395 | |
---|
396 | Multiple commands can be grouped together with parentheses |
---|
397 | and then separated by semicolons. For example: |
---|
398 | |
---|
399 | ( smartnarrow ; delete view ; expunge ; view all ) |
---|
400 | |
---|
401 | Will result in the four commands being executed |
---|
402 | in sequence. This is particularly useful with key bindings |
---|
403 | and coommands. For example: |
---|
404 | |
---|
405 | alias sn-delete ( smartnarrow ; delete view ) |
---|
406 | |
---|
407 | will create an "sn-delete" alias that will smartnarrow |
---|
408 | to a view and them mark the view for deletion. |
---|
409 | |
---|
410 | Using "show commands" will list all existing aliases. |
---|
411 | |
---|
412 | |
---|
413 | Key Bindings |
---|
414 | ------------ |
---|
415 | |
---|
416 | New key bindings may be created with the "bindkey" command. Each key |
---|
417 | binding is associated with a particular keymap which is applicable in |
---|
418 | a particular context/situation. When the key associated with a |
---|
419 | binding is pressed in the right context, it will result in an owl |
---|
420 | command being run. The syntax is: |
---|
421 | |
---|
422 | bindkey <keymap> <keyseq> command <command> |
---|
423 | |
---|
424 | For example: |
---|
425 | |
---|
426 | bindkey recv C-k command delete |
---|
427 | |
---|
428 | will bind Control-k to the delete command, but only in the |
---|
429 | recv window context. |
---|
430 | |
---|
431 | Some keymaps inherit their bindings from more |
---|
432 | general 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 | |
---|
443 | The existing key bindings can be shown with "show keymaps". |
---|
444 | The use of "show commands" will list all available commands. |
---|
445 | Note that not all commands may be used in all contexts. |
---|
446 | |
---|
447 | Key sequences may be surrounded by quotes and include |
---|
448 | a sequence of keys that must be pressed in order |
---|
449 | to execute the command. For example: |
---|
450 | |
---|
451 | bindkey recv "C-s v" command view -s vt |
---|
452 | |
---|
453 | will result in "Control-s" followed by "v" in the recv window |
---|
454 | causing the command "view -s vt" to be run. |
---|