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