doc/finch.1.in

   1 .\" Copyright (c) 2006, Sadrul Habib Chowdhury <sadrul@users.sf.net>
   2 .\"
   3 .\" This is free documentation; you can redistribute it and/or
   4 .\" modify it under the terms of the GNU General Public License as
   5 .\" published by the Free Software Foundation; either version 2 of
   6 .\" the License, or (at your option) any later version.
   7 .\"
   8 .\" The GNU General Public License's references to "object code"
   9 .\" and "executables" are to be interpreted as the output of any
  10 .\" document formatting or typesetting system, including
  11 .\" intermediate and printed output.
  12 .\"
  13 .\" This manual is distributed in the hope that it will be useful,
  14 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16 .\" GNU General Public License for more details.
  17 .\"
  18 .\" You should have received a copy of the GNU General Public
  19 .\" License along with this manual; if not, write to the Free
  20 .\" Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139,
  21 .\" USA.
  22 .TH finch 1
  23 .SH NAME
  24 Finch \- A Pimpin' Penguin console frontend to libpurple. Instant
  25 Messaging client.
  26 .SH SYNOPSIS
  27 .TP 5
  28 \fBfinch \fI[options]\fR
  29
  30 .SH DESCRIPTION
  31 .PP
  32 \fBfinch\fR is a console-based modular messaging client based on libpurple
  33 which is capable of connecting to AIM, MSN, Yahoo!, XMPP, ICQ, IRC, SILC,
  34 Novell GroupWise, Lotus Sametime, Zephyr, Gadu-Gadu, and QQ all at once. It has
  35 many common features found in other clients, as well as many unique features.
  36 Finch is not endorsed by or affiliated with America Online, ICQ, Microsoft, or
  37 Yahoo.
  38
  39 .SH OPTIONS
  40 The following options are provided by \fBfinch\fR using the standard GNU
  41 command line syntax:
  42 .TP
  43 .B \-c, \-\-config=\fIDIR\fB
  44 Use \fIDIR\fR as the directory for config files instead of \fI~/.purple\fR.
  45 .TP
  46 .B \-d, \-\-debug
  47 Print debugging messages to stderr and start with the \fBDebug\fR window. The
  48 messages shown in the \fBDebug\fR window are the same as the ones printed in
  49 stderr.
  50 .TP
  51 .B \-h, \-\-help
  52 Print this help and exit.
  53 .TP
  54 .B \-n, \-\-nologin
  55 Don't automatically login when \fBfinch\fR starts.  Sets all accounts to
  56 Offline.
  57 .TP
  58 .B \-v, \-\-version
  59 Display the version information window.
  60
  61 .SH GNT Shortcuts
  62 You can use the following shortcuts (see the "Widget Actions" section for a more complete list):
  63 .TP
  64 .B Alt \+ a
  65 Bring up a list of available actions. You can use this list to access the
  66 accounts window, plugins window, preference window etc.
  67 .TP
  68 .B Alt \+ n
  69 Go to the next window.
  70 .TP
  71 .B Alt \+ p
  72 Go to the previous window.
  73 .TP
  74 .B Alt \+ w
  75 Show the list of windows. You can select and jump to any window from the list.
  76 .TP
  77 .B Alt \+ c
  78 Close the current window.
  79 .TP
  80 .B Alt \+ q
  81 Quit.
  82 .TP
  83 .B Alt \+ m
  84 Start moving a window. Press the cursor keys to move the window. When you are
  85 done, press \fBEnter\fR or \fBEscape\fR.
  86 .TP
  87 .B Alt \+ r
  88 Start resizing a window. Press the cursor keys to resize the window. When you
  89 are done, press \fBEnter\fR or \fBEscape\fR.
  90 .TP
  91 .B Alt \+ D
  92 Dump the contents of the screen in HTML format.
  93 .TP
  94 .B Alt \+ .
  95 Move the position of the current window in the window list one place to the
  96 right.
  97 .TP
  98 .B Alt \+ ,
  99 Move the position of the current window in the window list one place to the
 100 left.
 101 .TP
 102 .B Alt \+ l
 103 Refresh the windows. This is useful after resizing the terminal window.
 104 .TP
 105 .B Alt \+ 1 2 ... 0
 106 Jump to the 1st, 2nd ... 10th window.
 107 .TP
 108 .B Alt \+ Tab
 109 Jump to the next URGENT (highlighted) window.
 110 .TP
 111 .B Alt \+ Shift \+ Tab
 112 Jump to the previous URGENT (highlighted) window.
 113 .TP
 114 .B Ctrl \+ o \fR or \fB F10
 115 Bring up the menu (if there is one) for a window.
 116 .TP
 117 .B F11 \fR or \fB Ctrl \+ x
 118 Popup the context menu (if there is one) for the selected widget.
 119 .TP
 120 .B Alt \+ /
 121 Show a list of available key-bindings for the current widget in focus.
 122 .TP
 123 .B Alt \+ \>
 124 Switch to the next workspace
 125 .TP
 126 .B Alt \+ \<
 127 Switch to the previous workspace
 128 .TP
 129 .B Alt \+ t
 130 Tag (or untag) the current window
 131 .TP
 132 .B Alt \+ T
 133 Attached all the tagged windows to the current workspace
 134 .TP
 135 .B Alt \+ s
 136 Show the workspace list
 137 .TP
 138 .B F9
 139 Create a new workspace and switch to it
 140
 141 .SH FILES
 142 \fI~/.gntrc\fR: configuration file for gnt applications.
 143 .br
 144 .TP
 145 A sample file looks like:
 146 .br
 147 [Finch]
 148 .br
 149 color-available = green; black
 150 .br
 151 color-away = blue; black
 152 .br
 153 color-idle = gray; black
 154 .br
 155 color-offline = red; black
 156 .br
 157 color-message-sent = cyan; default
 158 .br
 159 color-message-received = red; default
 160 .br
 161 color-message-highlight = black; green
 162 .br
 163 color-message-action = yellow; default
 164 .br
 165 color-timestamp = blue; default
 166 .br
 167 #See below for details on color
 168 .br
 169
 170 [general]
 171 .br
 172 shadow = 0
 173 .br
 174 # There is experimental mouse support
 175 .br
 176 mouse = 1
 177 .br
 178 # To use some custom window-manager
 179 .br
 180 wm = /usr/local/lib/gnt/s.so
 181 .br
 182 # There's also a custom window manager called irssi.so
 183 .br
 184 # Remember window-positions based on the titles (on by default)
 185 .br
 186 remember_position = 1
 187 .br
 188 # Use borderless one-line high buttons
 189 .br
 190 small-button = true
 191
 192 .br
 193 # Workspaces are created simply by adding Workspace-X groups as follows:
 194 .br
 195 [Workspace-1]
 196 .br
 197 name = blist
 198 .br
 199 # window-names specifies that windows with these semi-colon separated names are placed
 200 into this workspace
 201 .br
 202 window-names = buddylist;debug-window
 203 .br
 204
 205 .br
 206 [Workspace-2]
 207 .br
 208 name = IM
 209 .br
 210 window-names = conversation-window
 211 .br
 212 # window-titles specifies that windows with these semi-colon separated titles are placed
 213 into this workspace. These are matched as substrings. Window titles take precedence over
 214 names.
 215 .br
 216 window-titles = Preferences;Pounce
 217 .br
 218
 219 .br
 220 [colors]
 221 .br
 222 # The RGB values range in [0, 1000]
 223 .br
 224 black = 0; 0; 0
 225 .br
 226 red = 1000; 0; 0
 227 .br
 228 green = 0; 1000; 0
 229 .br
 230 blue = 250; 250; 700
 231 .br
 232 white = 1000; 1000; 1000
 233 .br
 234 gray = 700; 700; 700
 235 .br
 236 darkgray = 256; 256; 256
 237 .br
 238
 239 .br
 240 [colorpairs]
 241 .br
 242 normal = white; black
 243 .br
 244 highlight = white; blue
 245 .br
 246 highlightd = black; gray
 247 .br
 248 shadow = black; darkgray
 249 .br
 250 title = white; blue
 251 .br
 252 titled = white; gray
 253 .br
 254 text = white; blue
 255 .br
 256 disabled = gray; black
 257 .br
 258 urgent = green; black
 259 .br
 260
 261 .br
 262 # Remap some keys for GntEntry
 263 .br
 264 [GntEntry::remap]
 265 .br
 266 # Remap the up-arrow to the left-arrow
 267 .br
 268 ^[[A = ^[[D
 269 .br
 270 # Remap the down-arrow to the right-arrow
 271 .br
 272 ^[[B = ^[[C
 273 .br
 274 # Remap 'a' to 'bcd'
 275 .br
 276 a = bcd
 277 .br
 278 # Completely ignore the key 'q'
 279 .br
 280 q =
 281 .br
 282 # But the following will NOT work
 283 .br
 284 #abc = bcd
 285 .br
 286
 287 # Hitting 'space' will activate a button
 288 .br
 289 [GntButton::remap]
 290 .br
 291 \\  = \\r
 292 .br
 293
 294 .SH Widget Actions
 295 You can specifiy key-bindings for specific widgets. The following entries in
 296 \fI~/.gntrc\fR correspond to the default keybindings for the actions:
 297
 298 .br
 299 [GntBox::binding]
 300 .br
 301 tab = focus-next
 302 .br
 303 right = focus-next
 304 .br
 305 left = focus-prev
 306
 307 .br
 308 [GntComboBox::binding]
 309 .br
 310 down = dropdown
 311 .br
 312 up = dropdown
 313
 314 .br
 315 [GntEntry::binding]
 316 .br
 317 c-a = cursor-home
 318 .br
 319 home = cursor-home
 320 .br
 321 c-e = cursor-end
 322 .br
 323 end = cursor-end
 324 .br
 325 backspace = delete-prev
 326 .br
 327 del = delete-next
 328 .br
 329 c-d = delete-next
 330 .br
 331 c-u = delete-start
 332 .br
 333 c-k = delete-end
 334 .br
 335 c-b = cursor-prev
 336 .br
 337 left = cursor-prev
 338 .br
 339 c-f = cursor-next
 340 .br
 341 right = cursor-next
 342 .br
 343 tab = suggest-show
 344 .br
 345 down = suggest-next
 346 .br
 347 up = suggest-prev
 348 .br
 349 page-down = suggest-next-page
 350 .br
 351 page-up = suggest-prev-page
 352 .br
 353 c-w = delete-prev-word
 354 .br
 355 a-b = cursor-prev-word
 356 .br
 357 a-f = cursor-next-word
 358 .br
 359 a-d = delete-next-word
 360 .br
 361 c-v = clipboard-paste
 362 .br
 363 c-p = history-prev
 364 .br
 365 c-n = history-next
 366 .br
 367 c-r = history-search
 368 .br
 369 c-up = history-prev
 370 .br
 371 c-down = history-next
 372
 373 .br
 374 [GntTree::binding]
 375 .br
 376 up = move-up
 377 .br
 378 down = move-down
 379 .br
 380 c-n = move-down
 381 .br
 382 c-p = move-up
 383 .br
 384 pageup = page-up
 385 .br
 386 pagedown = page-down
 387 .br
 388 backspace = move-parent
 389 .br
 390 home = move-first
 391 .br
 392 end = move-last
 393 .br
 394 # Following is the default binding for the context-menu
 395 .br
 396 menu = context-menu
 397 .br
 398 # The following will let you open the context-menu in the buddylist with c-b
 399 .br
 400 # c-b = context-menu
 401
 402 .br
 403 [GntWidget::binding]
 404 .br
 405 f11 = context-menu
 406 .br
 407 c-x = context-menu
 408
 409 [GntWindow::binding]
 410 .br
 411 c-o = show-menu
 412 .br
 413 f10 = show-menu
 414
 415 The \fBc-\fR corresponds to the \fBControl\fR key. You can also use \fBctrl-\fR
 416 or \fBctr-\fR or \fBctl-\fR to indicate a combination. For alt-keys, you can use
 417 one of \fBa-\fR, \fBalt-\fR, \fBm-\fR or \fBmeta-\fR. You can also use
 418 \fBhome\fR, \fBend\fR, \fBleft\fR, \fBright\fR etc. keys.
 419
 420 To unbind a key which has a default binding, you simply bind it to the empty string.  For example, to unbind \fBAlt + q\fR from the Quit function, you would use:
 421
 422 [GntWM::binding]
 423 .br
 424 a-q =
 425
 426 .SH Menus
 427 You can also specify key-bindings to trigger specific menuitems in windows. For example, the following entry in \fI~/.gntrc\fR will bind \fBCtrl + t\fR to the 'Send IM...' item in the buddylist:
 428
 429 [buddylist::menu]
 430 .br
 431 c-t = send-im
 432
 433 The following is the list of IDs of the current menuitems in the buddylist:
 434
 435 send-im
 436 .br
 437 join-chat
 438 .br
 439 show-empty-groups
 440 .br
 441 show-offline-buddies
 442 .br
 443 sort-status
 444 .br
 445 sort-alpha
 446 .br
 447 sort-log
 448 .br
 449 add-buddy
 450 .br
 451 add-chat
 452 .br
 453 add-group
 454
 455 .SH Mouse Support
 456 There is experimental mouse support. You can focus windows, activate buttons,
 457 select rows in a list, scroll using the wheel-scroll etc. Selecting text in a
 458 text-view copies it to the gnt clipboard. Mouse support is disabled by default,
 459 so you need to enable it in \fI~/.gntrc\fR (see the sample above).
 460
 461 .SH Window Management
 462 The default window management is very limited. But it is possible to write
 463 custom window managers to suit your needs. There is a sample window-manager
 464 included (named \fIs.so\fR) which adds a little 'close-button' for the windows,
 465 removes the borders from the buddylist and pops up new windows in the middle of
 466 the screen, instead of at the upper-left corder. It is provided as a sample
 467 simple manager, but it should be possible to write more complex managers, and
 468 it's very possible that the window-manager API will need to be enhanced. Look at
 469 the sample \fI~/.gntrc\fR file above to see how to select a window-manager.
 470
 471 It is also possible to rebind the window-manager actions in \fI~/.gntrc\fR, eg:
 472
 473 .br
 474 [GntWM::binding]
 475 .br
 476 a-n = window-next
 477 .br
 478 a-p = window-prev
 479 .br
 480 a-c = window-close
 481 .br
 482 a-w = window-list
 483 .br
 484 a-d = dump-screen
 485 .br
 486 a-, = shift-left
 487 .br
 488 a-. = shift-right
 489 .br
 490 a-a = action-list
 491 .br
 492 a-m = start-move
 493 .br
 494 a-r = start-resize
 495 .br
 496 a-q = wm-quit
 497 .br
 498 a-l = refresh-screen
 499 .br
 500 a-s = workspace-list
 501 .br
 502 a-t = window-tag
 503 .br
 504 a-T = place-tagged
 505 .br
 506 a-C = toggle-clipboard
 507 .br
 508 a-/ = help-for-widget
 509 .br
 510 a-c-j = window-scroll-down
 511 .br
 512 a-c-k = window-scroll-up
 513 .br
 514 # The following action is still incomplete, and doesn't have a default binding
 515 .br
 516 # switch-window-n
 517 .br
 518 # Other actions: window-next-urgent, window-prev-urgent
 519
 520 # For the sample custom window manager
 521 .br
 522 [GntS::binding]
 523 .br
 524 a-b = toggle-buddylist
 525
 526 # For the irssi window manager
 527 .br
 528 [Irssi::binding]
 529 .br
 530 a-L = move-right
 531 .br
 532 a-H = move-left
 533 .br
 534 a-J = move-down
 535 .br
 536 a-K = move-up
 537
 538 .SH Conversation Commands
 539 There are a few helpful commands in addition to the regular commands. You can
 540 use these from any conversation to access other windows.
 541
 542 .TP
 543 .B accounts
 544 for the accounts window.
 545
 546 .TP
 547 .B buddylist
 548 for the buddylist.
 549
 550 .TP
 551 .B debugwin
 552 for the debug window.
 553
 554 .TP
 555 .B plugins
 556 for the plugins window.
 557
 558 .TP
 559 .B prefs
 560 for the preferences window.
 561
 562 .TP
 563 .B status
 564 for the status window.
 565
 566 .SH FAQ
 567 FAQ for \fBfinch\fR is located at
 568 .br
 569 \fIhttp://developer.pidgin.im/wiki/Using%20Finch\fR
 570
 571 .SH BUGS
 572 Known bugs are listed at
 573 .br
 574 \fIhttp://developer.pidgin.im/query?status=new&status=assigned&status=reopened&component=finch+%28gnt%2Fncurses%29&order=priority\fR
 575
 576 Before sending a bug report, please verify that you have the latest
 577 version of \fBfinch\fR and libpurple.  Many bugs (major and minor) are
 578 fixed at each release, and if yours is out of date, the problem may already have
 579 been solved.
 580
 581 .SH PATCHES
 582 If you fix a bug in \fBfinch\fR (or otherwise enhance it), please submit a
 583 patch (using \fBmtn diff > my.diff\fR against the latest version from the
 584 Monotone repository) at \fIhttp://developer.pidgin.im/simpleticket\fR
 585
 586 You are also encouraged to drop by at \fB#pidgin\fR on \fIirc.freenode.net\fR
 587 to discuss development.
 588
 589 .SH SEE ALSO
 590 \fIhttp://pidgin.im/\fR
 591 .br
 592 \fIhttp://developer.pidgin.im/\fR
 593 .br
 594 \fBpurple-remote\fR(1)
 595 .br
 596 \fBpidgin\fR(1)
 597
 598 .SH LICENSE
 599 This program is free software; you can redistribute it and/or modify
 600 it under the terms of the GNU General Public License as published by
 601 the Free Software Foundation; either version 2 of the License, or
 602 (at your option) any later version.
 603
 604 This program is distributed in the hope that it will be useful, but
 605 \fBWITHOUT ANY WARRANTY\fR; without even the implied warranty of
 606 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 607 General Public License for more details.
 608
 609 You should have received a copy of the GNU General Public License
 610 along with this program; if not, write to the Free Software
 611 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
 612
 613 .SH AUTHORS
 614 Sadrul Habib Chowdhury <\fIsadrul@users.sourceforge.net\fR>
 615 .br
 616
 617 This manpage was written by Sadrul Habib Chowdhury
 618 <\fIsadrul@users.sourceforge.net\fR> and Dennis Ristuccia
 619 <\fIdennis@dennisr.net\fR>.
 620