[bde7714] | 1 | ======================== |
---|
| 2 | Quick Guide To Using Owl |
---|
| 3 | ======================== |
---|
[61d27fb] | 4 | |
---|
[bde7714] | 5 | ======================= |
---|
| 6 | Section 1: INTRODUCTION |
---|
| 7 | ======================= |
---|
[61d27fb] | 8 | |
---|
[bde7714] | 9 | Owl is a tty, curses-based instant messaging client. This is a quick |
---|
[675ce49] | 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: |
---|
[7d4fbcd] | 13 | |
---|
[bde7714] | 14 | o) As a tty client it can be run over telnet, rlogin or text ssh |
---|
| 15 | sessions |
---|
[7d4fbcd] | 16 | |
---|
[bde7714] | 17 | o) It uses a perl configuration file for setting preferences and |
---|
| 18 | formatting messages |
---|
[7d4fbcd] | 19 | |
---|
[bde7714] | 20 | o) Emacs style editing of messages |
---|
[7d4fbcd] | 21 | |
---|
[bde7714] | 22 | o) It is easy to use and runs without a configfile. |
---|
[7d4fbcd] | 23 | |
---|
[bde7714] | 24 | o) Advanced sorting and coloring of messages |
---|
[7d4fbcd] | 25 | |
---|
[bde7714] | 26 | ========================== |
---|
| 27 | Section 2: GETTING STARTED |
---|
| 28 | ========================== |
---|
[7d4fbcd] | 29 | |
---|
[675ce49] | 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. |
---|
[bde7714] | 34 | |
---|
[3969e3a] | 35 | On Athena you can find owl in the ktools locker. To run it, type: |
---|
[bde7714] | 36 | |
---|
[675ce49] | 37 | add ktools |
---|
| 38 | owl |
---|
[bde7714] | 39 | |
---|
| 40 | at the Athena% prompt. If you wish to run the latest beta release of |
---|
[3969e3a] | 41 | owl use: |
---|
| 42 | |
---|
[675ce49] | 43 | add ktools |
---|
| 44 | owl-beta |
---|
[3969e3a] | 45 | |
---|
[675ce49] | 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. |
---|
[7d4fbcd] | 49 | |
---|
[bde7714] | 50 | The Screen Layout |
---|
| 51 | ----------------- |
---|
| 52 | There are three main parts to the owl screen. The large top portion |
---|
[675ce49] | 53 | of the screen is where messages are displayed. The status bar |
---|
[3969e3a] | 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 |
---|
[bde7714] | 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 |
---|
[3969e3a] | 62 | command, described later. |
---|
[7d4fbcd] | 63 | |
---|
| 64 | Sending a Zephyr |
---|
| 65 | ---------------- |
---|
[88736cb] | 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. |
---|
[7d4fbcd] | 72 | |
---|
[bde7714] | 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. |
---|
[7d4fbcd] | 75 | |
---|
[675ce49] | 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 | |
---|
[7d4fbcd] | 93 | Manipulating Messages |
---|
| 94 | --------------------- |
---|
[3969e3a] | 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: |
---|
[7d4fbcd] | 99 | |
---|
[675ce49] | 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 |
---|
[7d4fbcd] | 112 | |
---|
| 113 | When you are ready to delete a message you can mark it for deletion |
---|
[675ce49] | 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 |
---|
[3969e3a] | 126 | shortcut: |
---|
[7d4fbcd] | 127 | |
---|
[675ce49] | 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. |
---|
[7d4fbcd] | 135 | |
---|
[bde7714] | 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: |
---|
[7d4fbcd] | 138 | |
---|
[675ce49] | 139 | SPACE page down |
---|
| 140 | b page up |
---|
| 141 | RETURN line down |
---|
| 142 | BACKSPACE line up |
---|
[7d4fbcd] | 143 | |
---|
[bde7714] | 144 | The message pointer will change to indicate that the message is not |
---|
| 145 | starting at the first line. |
---|
[7d4fbcd] | 146 | |
---|
| 147 | Two other keys that relate to the current message: |
---|
| 148 | |
---|
[675ce49] | 149 | i print detailed information about the message |
---|
| 150 | w instruct netscape to visit a URL in the message |
---|
[7d4fbcd] | 151 | |
---|
| 152 | Other Functions |
---|
| 153 | ---------------- |
---|
[3969e3a] | 154 | Some other functions that can be performed with a single keystroke: |
---|
[7d4fbcd] | 155 | |
---|
[675ce49] | 156 | A toggle zephyr zaway on or off |
---|
| 157 | C-l refresh and resize the screen |
---|
| 158 | C-z suspend |
---|
[7d4fbcd] | 159 | |
---|
| 160 | Command Mode |
---|
| 161 | ------------ |
---|
[3969e3a] | 162 | Owl has a command mode from which you can enter more detailed commands |
---|
[675ce49] | 163 | for Owl to process. To enter command mode press the colon (':') key: |
---|
[7d4fbcd] | 164 | |
---|
[675ce49] | 165 | : begin command mode |
---|
[7d4fbcd] | 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. |
---|
[bde7714] | 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 |
---|
[3969e3a] | 171 | you can use the command: |
---|
| 172 | |
---|
[675ce49] | 173 | show commands |
---|
[bde7714] | 174 | |
---|
[3969e3a] | 175 | And for detailed information on the syntax and use of a command you |
---|
| 176 | can use: |
---|
| 177 | |
---|
[675ce49] | 178 | help <command> |
---|
[3969e3a] | 179 | |
---|
| 180 | For example "help zwrite" will display all the options available when |
---|
| 181 | using the zwrite command. |
---|
[7d4fbcd] | 182 | |
---|
| 183 | Variables |
---|
| 184 | --------- |
---|
[bde7714] | 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 | |
---|
[675ce49] | 190 | set personalbell on |
---|
[bde7714] | 191 | |
---|
[675ce49] | 192 | will set the value of the variable 'personalbell' to 'on'. The |
---|
| 193 | command: |
---|
[bde7714] | 194 | |
---|
[675ce49] | 195 | print personalbell |
---|
[bde7714] | 196 | |
---|
| 197 | will show you the current value. The 'print' command with no |
---|
[3969e3a] | 198 | arguments: |
---|
| 199 | |
---|
[675ce49] | 200 | print |
---|
[3969e3a] | 201 | |
---|
| 202 | Owl will show you the value of all variables. You can also use |
---|
| 203 | |
---|
[675ce49] | 204 | show variables |
---|
| 205 | |
---|
| 206 | show variable <variable> |
---|
[3969e3a] | 207 | |
---|
| 208 | To display further information on owl variables. |
---|
| 209 | |
---|
[675ce49] | 210 | |
---|
| 211 | ================ |
---|
| 212 | Section 3: VIEWS |
---|
| 213 | ================ |
---|
| 214 | |
---|
[3969e3a] | 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 |
---|
[675ce49] | 218 | narrow the view to a particular set of messages: |
---|
[3969e3a] | 219 | |
---|
[675ce49] | 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 |
---|
[3969e3a] | 224 | |
---|
[675ce49] | 225 | If you press M-n while the pointer is on a personal message, the view |
---|
[3969e3a] | 226 | will be narrowed to the conversation with that user only. If used on |
---|
[675ce49] | 227 | a group message the conversation will be narrowed to that group. |
---|
[3969e3a] | 228 | |
---|
[675ce49] | 229 | There are also some Owl commands related to views: |
---|
[3969e3a] | 230 | |
---|
[675ce49] | 231 | viewclass <class> Narrow the view to the named zephyr class |
---|
| 232 | viewuser <user> Narrow the view to the named user |
---|
[3969e3a] | 233 | |
---|
| 234 | More information on views and how they work is included in the section |
---|
| 235 | on "FILTERS AND COLORS". |
---|
| 236 | |
---|
[bde7714] | 237 | ============================= |
---|
[3969e3a] | 238 | Section 4: FILTERS AND COLORS |
---|
[bde7714] | 239 | ============================= |
---|
| 240 | |
---|
[675ce49] | 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. |
---|
[bde7714] | 274 | |
---|
[675ce49] | 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 |
---|
[bde7714] | 325 | |
---|
| 326 | ========================== |
---|
[675ce49] | 327 | Section 6: THE CONFIG FILE |
---|
[bde7714] | 328 | ========================== |
---|
[7d4fbcd] | 329 | |
---|
| 330 | *** WARNING: This interface may change substantially in the near future *** |
---|
| 331 | |
---|
[aa1bbf6] | 332 | The ~/.owlconf file is interpreted by the perl interpreter. You may |
---|
| 333 | specify an alternate file by running owl with "owl -c <configfile>". |
---|
[7d4fbcd] | 334 | |
---|
[aa1bbf6] | 335 | If you wish to execute an owl command from .owlconf use the function |
---|
| 336 | owl::command(). i.e.: |
---|
[7d4fbcd] | 337 | |
---|
[aa1bbf6] | 338 | owl::command('set zsigproc "/mit/kretch/bin/getzsig foo"'); |
---|
[7d4fbcd] | 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 |
---|
[c82b055] | 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. |
---|
[7d4fbcd] | 350 | owl::receive_msg() run when a message is received, and after |
---|
| 351 | it has been added to the message list |
---|
| 352 | |
---|
[aa1bbf6] | 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. |
---|
[7d4fbcd] | 356 | |
---|
[aa1bbf6] | 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. |
---|
[7d4fbcd] | 360 | |
---|
| 361 | |
---|
[675ce49] | 362 | ========================================== |
---|
| 363 | Section 4: KEYBINDINGS AND COMMAND ALIASES |
---|
| 364 | ========================================== |
---|
| 365 | |
---|
[c82b055] | 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. |
---|
| 455 | |
---|
| 456 | |
---|
[675ce49] | 457 | |
---|
[bde7714] | 458 | ============================== |
---|
[3969e3a] | 459 | Section 6: FURTHER INFORMATION |
---|
[bde7714] | 460 | ============================== |
---|
| 461 | |
---|
| 462 | $Id$ |
---|