annotate doc/pidgin.1.in @ 21160:45e550db32ab

merge of '656ddea68cc0419829183e2676970ed21efb838f' and '9825a5529451f2000418ac3fb9c586502380a2c6'

.\" Copyright (c) 2000, Dennis Ristuccia <[e-mail]>
.\"
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
.\"
.\" The GNU General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
.\" License along with this manual; if not, write to the Free
.\" Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139,
.\" USA.
.TH pidgin 1
.SH NAME
Pidgin v@VERSION@ \- Instant Messaging client
.SH SYNOPSIS
.TP 5
\fBpidgin \fI[options]\fR

.SH DESCRIPTION
.PP
\fBpidgin\fR is a graphical modular messaging client based on libpurple
which is capable of connecting to AIM, MSN, Yahoo!, XMPP, ICQ, IRC, SILC,
Novell GroupWise, Lotus Sametime, Zephyr, Gadu-Gadu, and QQ all at once. It has
many common features found in other clients, as well as many unique features.
Pidgin is not endorsed by or affiliated with America Online, ICQ, Microsoft, or
Yahoo.

.SH OPTIONS
The following options are provided by Pidgin using the standard GNU
command line syntax:
.TP
.B \-c, \-\-config=\fIDIR\fB
Use \fIDIR\fR as the directory for config files instead of \fI~/.purple\fR.
.TP
.B \-d, \-\-debug
Print debugging messages to stdout.  These are the same debugging messages
that are displayed in the \fBDebug Window\fR.
.TP
.B \-h, \-\-help
Print a summary of command line options and exit.
.TP
.B \-m, \-\-multiple
Allow multiple instances of Pidgin to run.
.TP
.B \-n, \-\-nologin
Don't automatically login when Pidgin starts.  Sets the global status to
\fBOffline\fR.
.TP
.B \-l, \-\-login[=\fINAME\fR,\fINAME\fR,...]
Sign in the comma-separated list of accounts provided, in addition to the
accounts that would be logged in anyway.  If you do not specify such a
comma-separated list, your first account will be signed in.
.TP
.B \-v, \-\-version
Print the current version and exit.

.SH BUDDY LIST
The \fBBuddy List\fR window is Pidgin's main interface window.  Using
this window you can see which of your buddies is online, away, idle, etc.
You can also add and remove buddies from your buddy list.

The \fBBuddy List\fR window contains a list of your buddies who are online
and have allowed you to be notified of their presence.  The icon to the
left of each buddy indicates the buddy's current status.  Double clicking
a buddy will open a new \fBConversation\fR window.  Right clicking will
pop up a menu:
.TP
.B Get Info
Retrieves and displays information about the buddy.  This information is
also known as a Profile.
.TP
.B IM
Opens a new \fBConversation\fR window to the selected buddy.
.TP
.B Send File
Sends a file to the selected buddy (only available on protocols that support
file transfer).
.TP
.B Add Buddy Pounce
A Buddy Pounce is a configurable automated action to be performed when the
buddy's state changes.  This will open the \fBBuddy Pounce\fR dialog to be
discussed later.
.TP
.B View Log
Pidgin is capable of automatically logging messages.  These logs are
either plain text files (with a .txt extension) or html files (with a
\&.html extension) located under the \fI~/.purple/logs\fR directory.  This
menu command will display Pidgin's log viewer with logs loaded for that
buddy or chat.
.TP
.B Alias
Create an alias for this buddy.  This will show an editable text field where
the buddy's screen name was displayed.  In this field one can give this
buddy an alternate, more friendly name to appear on the buddy list and in
conversations.

For example, if a buddy's name screen name was jsmith1281xx and his real
name was 'John Q. Smith,' one could create an alias as to identify the
buddy by his common name.
.LP
The remainder of the menu will consist of protocol specific commands.
These commands vary depending on the protocol.
.TP
.B Status Selector
At the bottom of the \fBBuddy List\fR is a status selector which allows
one to change his/her status.  This will be discussed further below.
.T

.SH ACCOUNT EDITOR
The account editor consists of a list of accounts and information about
them.  It can be accessed by selecting \fBManage\fR from the Tools menu.
Clicking \fIDelete\fR will delete the currently selected account.
Clicking \fIAdd\fR or \fIModify\fR will invoke a \fBModify Account\fR
window.  Here, you can add or alter account information.  When creating a
new account, you will submit your screen name and password.  You will also
choose your protocol.

If \fIRemember Password\fR is chosen, the password will be saved in
Pidgin's \fI~/.purple/accounts.xml\fR configuration file.

If \fIEnabled\fR is checked in the accounts dialog, this account will
follow the status currently selected in the status selector.  If it is
not checked, the account will always be offline.

Each protocol has its own specific options that can be found in the
modify screen.

.SH PREFERENCES

All options take effect immediately.

.SH Interface

.TP
.B Show system tray icon
Specifies when to show a Pidgin icon in the notification area of your
panel (commonly referred to as the System Tray).

.TP
.B Hide new IM conversations
Specifies when to hide new IM messages.  Messages will queue under the
specified condition until shown.  Clicking the Pidgin icon in the
notification area or system tray will display the queued messages.  An
icon also appears in the buddy list's menu bar; this icon may also be
used to display queued messages.

.TP
.B Show IMs and chats in tabbed windows
When checked, this option will cause IM and chat sessions to appear in
windows with multiple tabs.  One tab will represent one conversation or
chat.  Where tabs are placed will be dictated by the preferences below.

.TP
.B Show close buttons on tabs
When checked, this option will cause a clickable "U+2715 MULTIPLICATION X"
unicode character to appear at the right edge of each tab.  Clicking this
will cause the tab to be closed.

.TP
.B Placement
Specifies where to place tabs in the window.  Some tab orientations may
allow some users to fit more tabs into a single window comfortably.

.TP
.B New conversations
Specifies under which conditions tabs are placed into existing windows or
into new windows.  For a single window, select \fILast created window\fR here.

.SH Conversations

.TP
.B Enable buddy icon animation
If a buddy's icon happens to be animated, this option will enable the
animation, otherwise only the first frame will be displayed.

.TP
.B Notify buddies that you are typing to them
Some protocols allow clients to tell their buddies when they are typing.
This option enables this feature for protocols that supports it.  For XMPP,
this also enables sending the "User has left the conversation" message
when ending the conversation.

.TP
.B Default Formatting
Allows specifying the default formatting to apply to all outgoing messages
(only applicable to protocols that support formatting in messages).

.SH Smiley Themes
Allows the user to choose between different smiley themes. The "none" theme
will disable graphical emoticons - they will be displayed as text instead.
The \fBAdd\fR and \fBRemove\fR buttons may be used to install or uninstall
smiley themes.  Themes may also be installed by dragging and dropping them
onto the list of themes.

.SH Sounds

.TP
.B Method
Lets the user choose between different playback methods. The user can also
manually enter a command to be executed when a sound is to be played\
(\fI%s\fR expands to the full path to the file name).

.TP
.B Sounds when conversation has focus
When checked, sounds will play for events in the active conversation if
the window is focused.  When unchecked, sounds will not play for the
active conversation when the window is focused.

.TP
.B Enable Sounds
Determines when to play sounds.

.TP
.B Sound Events
Lets the user choose when and what sounds are to be played.

.SH Network

.TP
.B IP Address
\fIAutodetect IP Address\fR: Pidgin will attempt to automatically determine
your IP address for use in file transfers and Direct IMs.

\fIPublic IP\fR: What IP address to use for file transfer and Direct IMs. This
is mainly useful for users with multiple network interfaces or behind NAT.

.TP
.B Ports
\fIManually specify range of ports to listen on\fR: Specify specific ports to
listen on, overriding any defaults.

.TP
.B Proxy Server
The configuration section to enable Pidgin to operate through a proxy
server.  Pidgin currently supports SOCKS 4/5 and HTTP proxies.

.SH Browser

Allows the user to select Pidgin's default web browser.  Firefox, Galeon,
Konqueror, Mozilla, Netscape and Opera are supported natively.  The user
can also manually enter a command to be executed when a link is clicked
(\fI%s\fR expands to the URL).  For example, \fIxterm -e lynx "%s"\fR will
open the link with lynx.  \fIOpen new window by default\fR makes the
browser use a new window instead of using the current window (or spawning a
new tab).

.SH Logging

\fIMessage Logs\fR lets the user choose whether \fBConversations\fR and/or
\fBBuddy Chats\fR will be logged as well as whether logs will be in HTML or
plain text format.  \fISystem Logs\fR describes the types of events to be
logged.

.SH Away / Idle

\fIQueue new messages when away\fR: Messages received since going Away will
not be shown until away status is removed.

\fISend auto-response\fR: If someone messages you while away, your
auto-response will be sent.

\fIOnly send auto-response when idle\fR: If someone messages you while
away, your auto-response will only be sent if Pidgin decides that the
connection is idle.

\fIIdle time reporting\fR: If \fINone\fR is selected, account idle time
will not be reported.  \fIPidgin usage\fR infers your idle time from your
usage of Pidgin.  \fIX usage\fR infers your idle time from \fBX\fR
(this option may not be universally available).

\fIAuto-away\fR: Determines if and under what conditions Pidgin will
automatically turn on the Away status.

.TP
.B Away Messages
Lets the user add/edit/remove available \fBAway Messages\fR.

.SH Plugins

Allows the user to enable add-on plugins for Pidgin.  Several of these
come with Pidgin, while others must be downloaded separately.  The
\fIDescription\fR field gives the plugin author's description of the
plugin, while the \fIDetails\fR field gives the plugin's authorship, URL,
and file name/location information.

Some plugins can be configured.  If you load such a plugin, its
configuration preferences will appear as a submenu to \fBPlugins\fR, with
the submenu title determined by the plugin's name.

.SH CONVERSATIONS
When starting a new conversation, the user is presented with the
\fBConversation\fR window.  The conversation appears in the upper text box
and the user types his/her message in the lower text box.  Between the two
is a row of options, represented by icons.  Some or all buttons may not be
active if the protocol does not support the specific formatting. From left
to right:
.TP
.B Font
This menu provides font control options for the current conversation.  Size,
style, and face may be configured here.
.TP
.B Insert
This menu provides the ability to insert images, horizontal rules, and links
where the protocol supports each of these features.
.TP
.B Smile!
Allows the insertion of graphical smileys via the mouse.  This button shows
the user a dialog with the available smileys for the current conversation.

.SH CHATS
For protocols that allow it, \fBChats\fR can be entered through the
\fIBuddies\fR menu.


Additional commands available in chat, depending on the protocol are:
.TP
.B Whisper
The text will appear in the chat conversation, but it will only be visible
to the sender and the receiver.
.TP
.B Invite
Invite other people to join the chat room.
.TP
.B Ignore
Ignore anything said by the chosen person
.TP
.B Set Topic
Set the topic of the chat room.  This is usually a brief sentence
describing the nature of the chat--an explanation of the chat room's name.

.SH STATUS MESSAGES
Most protocols allow for status messages.  By using status messages, a user
can leave an informative message for others to see.  Status and status
messages are configured via the status selector at the bottom of the Buddy
List window.  By default the menu shown here is divided into sections for
"primitive" status types, such as \fIAvailable\fR, \fIAway\fR, etc.; a few
"popular" statuses which have been recently used, and a section which shows
\fBNew...\fR and \fBSaved...\fR options for more advanced status manipulation.

.SH BUDDY POUNCE
A Buddy Pounce is an automated trigger that occurs when a buddy returns to
a normal state from an away state.  The \fBBuddy Pounce\fR dialog box
can be activated by selecting the \fIBuddy Pounce\fR option from the
\fBTools\fR menu. From this dialog, new pounces can be created with the
\fBAdd\fR button and existing pounces can be removed with the \fBDelete\fR
button.  A pounce can be set to occur on any combination of the
events listed, and any combination of actions can result.  If \fIPounce
only when my status is not Available\fR is checked, the pounce will occur
only if you are set to a non-available status, such as invisible, do not
disturb, away, etc.  If \fIRecurring\fR is checked, the pounce will remain
until removed by the \fBDelete\fR button.

.SH PLUGINS
Pidgin allows for dynamic loading of plugins to add extra functionality
to Pidgin.  Plugins can be enabled and configured from the
\fBPreferences\fR window.  See \fIplugins/HOWTO\fR or
\fIhttp://developer.pidgin.im/wiki/CHowTo\fR for more information on
writing plugins.

.SH PERL
Pidgin allows for perl scripting.  See \fIPerl Scripting HOWTO\fR in
the Pidgin documentation for more information about perl scripting.

.SH TCL
Pidgin allows for Tcl scripting. See \fIplugins/tcl/TCL-HOWTO\fR for
more information about Tcl scripting.

.SH FILES
  \fI@prefix@/bin/pidgin\fR: Pidgin's location.
.br
  \fI@prefix@/lib/pidgin/\fR: Pidgin's plugins directory.
.br
  \fI@prefix@/lib/purple-2/\fR: libpurple's plugins directory.
.br
  \fI~/.purple/prefs.xml\fR: Pidgin's configuration file.
.br
  \fI~/.purple/accounts.xml\fR: information about your accounts.
.br
  \fI~/.purple/status.xml\fR: stores your away messages.
.br
  \fI~/.purple/pounces.xml\fR: stores your buddy pounces.
.br
  \fI~/.purple/logs/PROTOCOL/ACCOUNT/SCREENNAME/DATE.{html,txt}\fR: conversation logs.
.br
  \fI~/.purple/blist.xml\fR: the buddy list.
.br
  \fI~/.purple/plugins/\fR: users' local plugins

.SH BUGS
The bug tracker can be reached by visiting \fIhttp://developer.pidgin.im/query\fR

.SH PATCHES
If you fix a bug in Pidgin (or otherwise enhance it), please submit a
patch (using \fImtn diff > my.diff\fR against the latest version from the
Monotone repository) at \fIhttp://developer.pidgin.im/simpleticket\fR

Before sending a bug report, please verify that you have the latest
version of Pidgin.  Many bugs (major and minor) are fixed
at each release, and if yours is out of date, the problem may already
have been solved.

.SH SEE ALSO
\fIhttp://pidgin.im/\fR

.SH LICENSE
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful, but
\fBWITHOUT ANY WARRANTY\fR; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA

.SH AUTHORS
Pidgin's active developers are:
.br
  Sean Egan (lead developer) <\[e-mail]\fR>
.br
  Daniel 'datallah' Atallah (developer)
.br
  John 'rekkanoryo' Bailey (developer)
.br
  Ethan 'Paco-Paco' Blanton (developer)
.br
  Thomas Butter (developer)
.br
  Ka-Hing Cheung (developer)
.br
  Sadrul Habib Chowdhury (developer)
.br
  Mark 'KingAnt' Doliner (developer) <\[e-mail]\fR>
.br
  Casey Harkins (developer)
.br
  Gary 'grim' Kramlich (developer)
.br
  Richard 'rlaager' Laager (developer) <\[e-mail]\fR>
.br
  Richard 'wabz' Nelson (developer)
.br
  Christopher 'siege' O'Brien (developer)
.br
  Bartosz Oler (developer)
.br
  Etan 'deryni' Reisner (developer)
.br
  Tim 'marv' Ringenbach (developer) <\[e-mail]\fR>
.br
  Luke 'LSchiere' Schierer (support)
.br
  Megan 'Cae' Schneider (support/QA)
.br
  Evan Schoenberg (developer)
.br
  Kevin 'SimGuy' Stange (developer and webmaster)
.br
  Stu 'nosnilmot' Tomlinson (developer)
.br
  Nathan 'faceprint' Walp (developer)
.br


Our crazy patch writers include:
.br
  Dennis 'EvilDennisR' Ristuccia
.br
  Peter 'fmoo' Ruibal
.br
  Gabriel 'Nix' Schulhof
.br
  Will 'resiak' Thompson
.br


Our artists are:
.br
  Hylke Bons <\[e-mail]\fR>
.br


Our retired developers are:
.br
  Herman Bloggs (win32 port) <\[e-mail]\fR>
.br
  Jim Duchek <\[e-mail]\fR> (maintainer)
.br
  Rob Flynn <\[e-mail]\fR> (maintainer)
.br
  Adam Fritzler (libfaim maintainer)
.br
  Christian 'ChipX86' Hammond (developer & webmaster) <\[e-mail]\fR>
.br
  Syd Logan (hacker and designated driver [lazy bum])
.br
  Jim Seymour (XMPP developer)
.br
  Mark Spencer (original author) <\[e-mail]\fR>
.br
  Eric Warmenhoven (former lead developer) <\[e-mail]\fR>
.br


Our retired crazy patch writers include:
.br
  Felipe 'shx' Contreras
.br
  Decklin Foster
.br
  Peter 'Bleeter' Lawler
.br
  Robert 'Robot101' McQueen
.br
  Benjamin Miller
.br


This manpage was originally written by Dennis Ristuccia <\[e-mail]\fR>.  It has been updated and largely rewritten by Sean Egan <\[e-mail]\fR> and Ben Tegarden <\[e-mail]\fR>.