1
Ri.\" Copyright (c) 2000, Dennis Ristuccia <dennis@dennisr.net>
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.
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.
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.
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., 51 Franklin Street, Fifth Floor,
21
.\" Boston, MA 02111-1301 USA.
22
.TH pidgin 1 "" "Pidgin v@VERSION@"
24
pidgin \- Instant Messaging client
27
\fBpidgin \fI[options]\fR
31
\fBpidgin\fR is a graphical modular messaging client based on libpurple
32
which is capable of connecting to AIM, MSN, Yahoo!, XMPP, ICQ, IRC, SILC,
33
Novell GroupWise, Lotus Sametime, Zephyr, Gadu-Gadu, and QQ all at once. It has
34
many common features found in other clients, as well as many unique features.
35
Pidgin is not endorsed by or affiliated with America Online, ICQ, Microsoft, or
38
Pidgin can be extended by plugins written in multiple programming languages and
39
controlled through DBus or \fBpurple-remote\fR.
42
The following options are provided by Pidgin using the standard GNU
45
.B \-c, \-\-config=\fIDIR\fB
46
Use \fIDIR\fR as the directory for config files instead of \fI~/.purple\fR.
49
Print debugging messages to stdout. These are the same debugging messages
50
that are displayed in the \fBDebug Window\fR.
52
.B \-f, \-\-force-online
53
Try to be online even if the network is reported (by Windows, or NetworkManager
54
on Linux) to be unavailable.
57
Print a summary of command line options and exit.
60
Allow multiple instances of Pidgin to run.
63
Don't automatically login when Pidgin starts. Sets the global status to
66
.B \-l, \-\-login[=\fINAME\fR,\fINAME\fR,...]
67
Enable the comma-separated list of accounts provided, disabling all other
68
accounts. If the user does not specify such a comma-separated list, the
69
first account in accounts.xml will be enabled.
72
Print the current version and exit.
75
Pidgin uses a few terms differently from other applications. For convenience
76
they are defined here:
79
The list of other users who the user wants to see status information for
80
and have quick access to for messaging.
83
A user who has been added to the Buddy List.
86
A grouping of more than one buddy who are all the same person. A contact may
87
contain buddies from any protocol and may contain as many buddies as the user
88
desires. Contact arrangements are stored locally only.
91
A private "nickname" that may be set for Buddies or the user himself. On some
92
protocols, aliases are saved on the server but not visible to other users. On
93
other protocols, aliases are saved only locally.
96
A messaging service. AIM, XMPP, MSN, Zephyr, etc. are protocols. Others may
97
call these "service types," "account types," "services," and so on.
100
The \fBBuddy List\fR window is Pidgin's main interface window. Using
101
this window a user can see which of his/her buddies is online, away, idle,
102
etc. The user can also add buddies to and remove buddies from the buddy list.
104
The \fBBuddy List\fR window contains a list of the user's buddies who are
105
online and have allowed the user to be notified of their presence. The icon
106
to the left of each buddy indicates the buddy's current status. Double
107
clicking a buddy will open a new \fBConversation\fR window. Right clicking
111
Retrieves and displays information about the buddy. This information is
112
also known as a Profile.
115
Opens a new \fBConversation\fR window to the selected buddy.
118
Sends a file to the selected buddy (only available on protocols that support
122
A Buddy Pounce is a configurable automated action to be performed when the
123
buddy's state changes. This will open the \fBBuddy Pounce\fR dialog, which
124
will be discussed later.
127
Pidgin is capable of automatically logging messages. These logs are
128
either plain text files (with a .txt extension) or html files (with a
129
\&.html extension) located under the \fI~/.purple/logs\fR directory. This
130
menu command will display Pidgin's log viewer with logs loaded for that
134
Create an alias for this buddy. This will show an editable text field where
135
the buddy's name was displayed. In this field one can give this
136
buddy an alternate, more friendly name to appear on the buddy list and in
139
For example, if a buddy's name was jsmith1281xx and his real
140
name was 'John Q. Smith,' one could create an alias as to identify the
141
buddy by his common name.
143
The remainder of the menu will consist of protocol specific commands.
144
These commands vary depending on the protocol.
147
At the bottom of the \fBBuddy List\fR is a status selector which allows one to
148
change his/her status. This will be discussed further in the \fBSTATUS
149
MESSAGES\fR section below.
152
The account editor consists of a list of accounts and information about
153
them. It can be accessed by selecting \fBManage\fR from the Accounts menu.
154
Clicking \fIDelete\fR will delete the currently selected account.
155
Clicking \fIAdd\fR or \fIModify\fR will invoke a \fBModify Account\fR
156
window. Here, the user can add or alter account information. When creating
157
a new account, the user will submit a username and password. The user will
158
also choose the protocol for the account.
160
If \fIRemember Password\fR is chosen, the password will be saved in
161
Pidgin's \fI~/.purple/accounts.xml\fR configuration file.
163
If \fIEnabled\fR is checked in the accounts dialog, this account will
164
follow the status currently selected in the status selector. If it is
165
not checked, the account will always be offline.
167
Each protocol has its own specific options that can be found in the
172
All options take effect immediately.
177
.B Show system tray icon
178
Specifies when to show a Pidgin icon in the notification area of the user's
179
panel (commonly referred to as the System Tray).
182
.B Hide new IM conversations
183
Specifies when to hide new IM messages. Messages will queue under the
184
specified condition until shown. Clicking the Pidgin icon in the
185
notification area or system tray will display the queued messages. An
186
icon also appears in the buddy list's menu bar; this icon may also be
187
used to display queued messages.
190
.B Show IMs and chats in tabbed windows
191
When checked, this option will cause IM and chat sessions to appear in
192
windows with multiple tabs. One tab will represent one conversation or
193
chat. Where tabs are placed will be dictated by the preferences below.
196
.B Show close buttons on tabs
197
When checked, this option will cause a clickable "U+2715 MULTIPLICATION X"
198
unicode character to appear at the right edge of each tab. Clicking this
199
will cause the tab to be closed.
203
Specifies where to place tabs in the window. Some tab orientations may
204
allow some users to fit more tabs into a single window comfortably.
208
Specifies under which conditions tabs are placed into existing windows or
209
into new windows. For a single window, select \fILast created window\fR here.
214
.B Enable buddy icon animation
215
If a buddy's icon happens to be animated, this option will enable the
216
animation, otherwise only the first frame will be displayed.
219
.B Notify buddies that you are typing to them
220
Some protocols allow clients to tell their buddies when they are typing.
221
This option enables this feature for protocols that supports it.
224
.B Default Formatting
225
Allows specifying the default formatting to apply to all outgoing messages
226
(only applicable to protocols that support formatting in messages).
229
Allows the user to choose between different smiley themes. The "none" theme
230
will disable graphical emoticons - they will be displayed as text instead.
231
The \fBAdd\fR and \fBRemove\fR buttons may be used to install or uninstall
232
smiley themes. Themes may also be installed by dragging and dropping them
233
onto the list of themes.
239
Lets the user choose between different playback methods. The user can also
240
manually enter a command to be executed when a sound is to be played\
241
(\fI%s\fR expands to the full path to the file name).
244
.B Sounds when conversation has focus
245
When checked, sounds will play for events in the active conversation if
246
the window is focused. When unchecked, sounds will not play for the
247
active conversation when the window is focused.
251
Determines when to play sounds.
255
Lets the user choose when and what sounds are to be played.
261
This allows specifying a server which uses the STUN protocol to determine
262
a host's public IP address. This can be particularly useful for some
266
.B Autodetect IP address
267
When checked, causes Pidign to attempt to determine the public IP address
268
of the host on which Pidgin is running and disables the \fBPublic IP\fR
269
text field listed below.
273
If \fBAutodetect IP address\fR is disabled, this field allows manually
274
specifying the public IP address for the host on which Pidgin is running.
275
This is mainly useful for users with multiple network interfaces or behind
279
.B Manually specify range of ports to listen on
280
Specify a range ports to listen on, overriding any defaults. This is
281
sometimes useful for file transfers and Direct IM.
285
The configuration section to enable Pidgin to operate through a proxy
286
server. Pidgin currently supports SOCKS 4/5 and HTTP proxies.
292
Allows the user to select Pidgin's default web browser. Firefox, Galeon,
293
Konqueror, Mozilla, Netscape and Opera are supported natively. The user
294
can also manually enter a command to be executed when a link is clicked
295
(\fI%s\fR expands to the URL). For example, \fIxterm -e lynx "%s"\fR will
296
open the link with lynx.
300
Allows the user to specify whether to use an existing window, a new tab, a
301
new window, or to let the browser to decide what to do when calling the
302
browser to open a link. Which options are available will depend on which
309
Specifies how to log. Pidgin supports HTML and plain text, but plugins can
310
provide other logging methods.
313
.B Log all instant messages
314
When enabled, all IM conversations are logged. This can be overridden on a
315
per-conversation basis in the conversation window.
319
When enabled, all chat conversations are logged. This can be overridden on a
320
per-conversation basis in the conversation window.
323
.B Log all status changes to system log
324
When enabled, status changes are logged.
330
Determines under which conditions to report idle time. \fBBased on keyboard
331
and mouse use\fR uses keyboard and mouse activity to determine idle time.
332
\fBFrom last sent message\fR uses the time at which the user last sent a
333
message in Pidgin to determine idle. \fBNever\fR disables idle reporting.
337
Determines when to send an auto-reply on protocols which support it
338
(currently only AIM).
341
.B Change status when idle
342
When enabled, this uses the \fBMinutes before becoming idle\fR and \fBChange
343
status to\fR preferences described below to set status on idle.
346
.B Minutes before becoming idle
347
Specifies how many minutes of inactivity are required before considering the
352
Specifies which "primitive" or "saved" status to use when setting status on
356
.B Use status from last exit at startup
357
If this is checked, Pidgin will remember what status was active when the
358
user closed Pidgin and restore it at the next run. When disabled, Pidgin
359
will always set the status selected in \fBStatus to apply at startup\fR
363
.B Status to apply at startup
364
When \fBUse status from last exit at startup\fR is disabled, this specifies
365
which "primitive" or "saved" status to use at startup.
368
When starting a new conversation, the user is presented with the
369
\fBConversation\fR window. The conversation appears in the upper text box
370
and the user types his/her message in the lower text box. Between the two
371
is a row of options, represented by icons. Some or all buttons may not be
372
active if the protocol does not support the specific formatting. From left
376
This menu provides font control options for the current conversation. Size,
377
style, and face may be configured here.
380
This menu provides the ability to insert images, horizontal rules, and links
381
where the protocol supports each of these features.
384
Allows the insertion of graphical smileys via the mouse. This button shows
385
the user a dialog with the available smileys for the current conversation.
388
For protocols that allow it, \fBChats\fR can be entered through the
391
Additional features available in chat, depending on the protocol are:
394
The text will appear in the chat conversation, but it will only be visible
395
to the sender and the receiver.
398
Invite other people to join the chat room.
401
Ignore anything said by the chosen person
404
Set the topic of the chat room. This is usually a brief sentence
405
describing the nature of the chat--an explanation of the chat room's name.
407
.B Private Message (IM)
408
Send a message to a specific person in the chat. Messages sent this way will
409
not appear in the chat window, but instead open a new IM conversation.
412
Most protocols allow for status messages. By using status messages, a user
413
can leave an informative message for others to see. Status and status
414
messages are configured via the status selector at the bottom of the Buddy
415
List window. By default the menu shown here is divided into sections for
416
"primitive" status types, such as \fIAvailable\fR, \fIAway\fR, etc.; a few
417
"popular" statuses (including "transient" statuses) which have been
418
recently used, and a section which shows \fBNew Status...\fR and \fBSaved
419
Statuses...\fR options for more advanced status manipulation.
422
.B Primitive Statuses
423
A primitive status is a basic status supported by the protocol. Examples of
424
primitive statuses would be Available, Away, Invisible, etc. A primitive
425
status can be used to create a \fBTransient Status\fB or a \fBSaved Status\fR,
426
both explained below. Essentially, primitive statuses are building blocks
427
of more complicated statuses.
430
.B Transient Statuses
431
When one of the statuses from the topmost section of the status selector's
432
menu is selected, this creates a transient, or temporary, status. The status
433
will show in the "popular statuses" section in the menu until it has not been
434
used for a sufficiently long time. A transient status may also be created by
435
selecting \fINew Status...\fR from the status selector's menu, then clicking
436
\fIUse\fR once the user has entered the message.
440
Saved statuses are permanent--once created, they will exist until deleted.
441
Saved statuses are useful for statuses and status messages that will be used
442
on a regular basis. They are also useful for creating complex statuses in
443
which some accounts should always have a different status from others. For
444
example, one might wish to create a status called "Sleeping" that has all
445
accounts set to "Away", then create another status called "Working" that
446
has three accounts set to "Away" and another account set to "Available."
450
When the user selects \fINew Status...\fR from the status selector menu,
451
Pidgin presents the user with a dialog asking for status-related information.
452
That information is discussed below:
454
\fITitle\fR - The name of the status that will appear in the status selctor's
455
menu. If the user clicks the \fISave\fR or \fISave & Use\fR button, this
456
name will also be shown in the \fBSaved Status Window\fR. The title should
457
be a short description of the status.
459
\fIStatus\fR - The type of status being created, such as Available, Away, etc.
461
\fIMessage\fR - The content of the status message. This is what is visible
462
to other users. Some protocols will allow formatting in some status messages;
463
where formatting is not supported it will be stripped to the bare text entered.
465
\fIUse a different status for some accounts\fR - This allows the creation of
466
complex statuses in which some accounts' status differs from that of other
467
accounts. To use this, the user will click the expander to the left of the
468
text, then select individual accounts which will have a different status
469
and/or status message. When the user selects an account, Pidgin will present
470
another status dialog asking for a status and a message just for the selected
474
.B Saved Status Window
475
When the user selects \fISaved Statuses...\fR from the status selector's menu,
476
Pidgin presents a dialog that lists all saved statuses. "Transient" statuses,
477
discussed above, are \fB\fINOT\fR\fR shown here. This window provides the
478
ability to manage saved statuses by allowing the creation, modification, and
479
deletion of saved statuses. The \fIUse\fR, \fIModify\fR, and \fIDelete\fR
480
buttons here allow operation on the status selected from the list; the \fAdd\fR
481
button allows creation of a new saved status, and the \fIClose\fR button closes
485
A Buddy Pounce is an automated trigger that occurs when a buddy returns to
486
a normal state from an away state. The \fBBuddy Pounce\fR dialog box
487
can be activated by selecting the \fIBuddy Pounce\fR option from the
488
\fBTools\fR menu. From this dialog, new pounces can be created with the
489
\fBAdd\fR button and existing pounces can be removed with the \fBDelete\fR
490
button. A pounce can be set to occur on any combination of the
491
events listed, and any combination of actions can result. If \fIPounce
492
only when my status is not Available\fR is checked, the pounce will occur
493
only if the user is set to a non-available status, such as invisible, do not
494
disturb, away, etc. If \fIRecurring\fR is checked, the pounce will remain
495
until removed by the \fBDelete\fR button.
498
Pidgin 2.5.0 introduced support for custom smilies on those protocols for which
499
interested contributors have developed support. The custom smiley manager can
500
be accessed by selecting \fISmiley\fR from the \fITools\fR menu. From here,
501
custom smilies may be added, edited, or deleted by clicking the \fIAdd\fR,
502
\fIEdit\fR, or \fIDelete\fR buttons, respectively.
504
During a conversation with another user, that user's custom smileys may be
505
added to the user's own custom smiley list directly from the conversation
506
window by right-clicking the new custom smiley and selecting \fIAdd Custom
510
Pidgin allows for dynamic loading of plugins to add extra functionality
511
to Pidgin. See \fIplugins/HOWTO\fR or
512
\fIhttp://developer.pidgin.im/wiki/CHowTo\fR for information on writing
515
The plugins dialog can be accessed by selecting \fIPlugins\fR from the
516
\fITools\fR menu. Each plugin available appears in this dialog with its name,
517
version, and a short summary of its functionality. Plugins can be enabled
518
with the checkbox beside the name and short description. More information on
519
the currently selected plugin is available by clicking the expander beside the
520
text \fIPlugin Details\fR. If the selected plugin has preferences or
521
configuration options, the \fIConfigure Plugin\fR button will present the
522
plugin's preferences dialog.
525
Pidgin allows for plugins to be written in the perl scripting language. See
526
\fIPerl Scripting HOWTO\fR in the Pidgin documentation for more information
527
about perl scripting.
530
Pidgin allows for plugins to be written in the Tcl scripting language. See
531
\fIplugins/tcl/TCL-HOWTO\fR for more information about Tcl scripting.
534
Pidgin allows for interaction via D-Bus. Currently very little documentation
535
about this interaction exists.
538
\fI@prefix@/bin/pidgin\fR: Pidgin's location.
540
\fI~/.purple/blist.xml\fR: the buddy list.
542
\fI~/.purple/accounts.xml\fR: information about the user's accounts.
544
\fI~/.purple/pounces.xml\fR: stores the user's buddy pounces.
546
\fI~/.purple/prefs.xml\fR: Pidgin's configuration file.
548
\fI~/.purple/status.xml\fR: stores the user's away messages.
550
\fI~/.purple/logs/PROTOCOL/ACCOUNT/BUDDYNAME/DATE.{html,txt}\fR: conversation logs.
553
\fI@prefix@/lib/pidgin/\fR: Pidgin's plugins directory.
555
\fI@prefix@/lib/purple-2/\fR: libpurple's plugins directory.
557
\fI~/.purple\fR: users' local settings
559
\fI~/.purple/plugins/\fR: users' local plugins
562
The bug tracker can be reached by visiting \fIhttp://developer.pidgin.im/query\fR
564
Before sending a bug report, please verify that you have the latest
565
version of Pidgin. Many bugs (major and minor) are fixed
566
at each release, and if yours is out of date, the problem may already
570
If you fix a bug in Pidgin (or otherwise enhance it), please submit a
571
patch (using \fBmtn diff > my.diff\fR against the latest version from the
572
Monotone repository) at \fIhttp://developer.pidgin.im/simpleticket\fR
574
You are also encouraged to drop by at \fB#pidgin\fR on \fIirc.freenode.net\fR
575
to discuss development.
579
\fIhttp://pidgin.im/\fR
581
\fIhttp://developer.pidgin.im/\fR
583
\fBpurple-remote\fR(1)
588
This program is free software; you can redistribute it and/or modify
589
it under the terms of the GNU General Public License as published by
590
the Free Software Foundation; either version 2 of the License, or
591
(at your option) any later version.
593
This program is distributed in the hope that it will be useful, but
594
\fBWITHOUT ANY WARRANTY\fR; without even the implied warranty of
595
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
596
General Public License for more details.
598
You should have received a copy of the GNU General Public License
599
along with this program; if not, write to the Free Software
600
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
603
Pidgin's active developers are:
605
Daniel 'datallah' Atallah (developer)
607
Paul 'darkrain42' Aurich (developer)
609
John 'rekkanoryo' Bailey (developer and bugmaster)
611
Ethan 'Paco-Paco' Blanton (developer)
613
Thomas Butter (developer)
615
Ka-Hing Cheung (developer)
617
Sadrul Habib Chowdhury (developer)
619
Mark 'KingAnt' Doliner (developer) <\fIthekingant@users.sourceforge.net\fR>
621
Sean Egan (developer) <\fIseanegan@gmail.com\fR>
623
Casey Harkins (developer)
627
Gary 'grim' Kramlich (developer)
629
Richard 'rlaager' Laager (developer) <\fIrlaager@pidgin.im\fR>
631
Sulabh 'sulabh_m' Mahajan (developer)
633
Richard 'wabz' Nelson (developer)
635
Christopher 'siege' O'Brien (developer)
637
Bartosz Oler (developer)
639
Etan 'deryni' Reisner (developer)
641
Tim 'marv' Ringenbach (developer) <\fImarv_sf@users.sf.net\fR>
643
Michael 'Maiku' Ruprecht (developer, voice and video)
645
Elliott 'QuLogic' Sales de Andrade (developer)
647
Luke 'LSchiere' Schierer (support)
649
Megan 'Cae' Schneider (support/QA)
651
Evan Schoenberg (developer)
653
Kevin 'SimGuy' Stange (developer and webmaster)
655
Will 'resiak' Thompson (developer)
657
Stu 'nosnilmot' Tomlinson (developer)
659
Nathan 'faceprint' Walp (developer)
663
Our crazy patch writers include:
665
Marcus 'malu' Lundblad
667
Dennis 'EvilDennisR' Ristuccia
671
Gabriel 'Nix' Schulhof
673
Jorge 'Masca' Villaseñor
679
Hylke Bons <\fIh.bons@student.rug.nl\fR>
683
Our retired developers are:
685
Herman Bloggs (win32 port) <\fIherman@bluedigits.com\fR>
687
Jim Duchek <\fIjim@linuxpimps.com\fR> (maintainer)
689
Rob Flynn <\fIgaim@robflynn.com\fR> (maintainer)
691
Adam Fritzler (libfaim maintainer)
693
Christian 'ChipX86' Hammond (developer & webmaster) <\fIchipx86@chipx86.com\fR>
695
Syd Logan (hacker and designated driver [lazy bum])
697
Jim Seymour (XMPP developer)
699
Mark Spencer (original author) <\fImarkster@marko.net\fR>
701
Eric Warmenhoven (former lead developer) <\fIeric@warmenhoven.org\fR>
705
Our retired crazy patch writers include:
707
Felipe 'shx' Contreras
711
Peter 'Bleeter' Lawler
713
Robert 'Robot101' McQueen
719
This manpage was originally written by Dennis Ristuccia
720
<\fIdennis@dennisr.net\fR>. It has been updated and largely rewritten by
721
Sean Egan <\fIseanegan@gmail.com\fR>,
722
Ben Tegarden <\fItegarden@uclink.berkeley.edu\fR>,
723
and John Bailey <\fIrekkanoryo@pidgin.im\fR>.
added
removed
doc/pidgin.1.in
