2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
3 "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
4 <!ENTITY legal SYSTEM "legal.xml">
5 <!ENTITY appversion "2.28">
6 <!ENTITY manrevision "2.2">
7 <!ENTITY date "May 2009">
8 <!ENTITY app "<application>Empathy</application>">
9 <!ENTITY appname "Empathy">
10 <!ENTITY gtalk "http://www.google.com/talk/">
11 <!ENTITY icq "https://www.icq.com/register/">
12 <!ENTITY aim "http://dashboard.aim.com/aim">
13 <!ENTITY msn "https://accountservices.passport.net">
14 <!ENTITY yahoo "https://login.yahoo.com/config/login">
16 "http://account2.freeworlddialup.com/index.php?section_id=94">
17 <!ENTITY ekiga "https://www.ekiga.net/index.php?page=register">
19 "https://signup.sipphone.com/new-users/app?class=NewUser;proc=start">
20 <!ENTITY jabber "http://www.jabber.org/web/Jabber.org">
22 <?db.chunk.max_depth 2?>
23 <article id="index" lang="en">
24 <!-- please do not change the id; for translations, change lang to -->
25 <!-- appropriate code -->
27 <title>&app; Manual V&manrevision;</title>
30 <year>2008, 2009</year>
31 <holder>Ubuntu Documentation Project</holder>
35 <holder>GNOME Documentation Project</holder>
38 <!-- An address can be added to the publisher information. If a role is
39 not specified, the publisher/author is the same for all versions of the
42 <publishername>GNOME Documentation Project</publishername>
45 <!-- licence stuff -->
49 <author role="maintainer">
50 <firstname>Milo</firstname>
51 <surname>Casagrande</surname>
53 <orgname>GNOME Documentation Project</orgname>
54 <address><email>milo@ubuntu.com</email></address>
57 <orgname>Ubuntu Documentation Project</orgname>
58 <address><email>milo@ubuntu.com</email></address>
62 <firstname>Seth</firstname>
63 <surname>Dudenhofer</surname>
65 <orgname>Ubuntu Documentation Project</orgname>
66 <address><email>sdudenhofer@gmail.com</email></address>
71 <releaseinfo revision="2.28" role="incomplete">
72 <ulink type="bug" url="http://bugzilla.gnome.org/show_bug.cgi?id=561033" />
73 <ulink type="planning" url="http://live.gnome.org/Empathy/Documentation" />
76 <!-- According to GNU FDL, revision history is mandatory if you are -->
77 <!-- modifying/reusing someone else's document. If not, you can omit it. -->
78 <!-- Remember to remove the &manrevision; entity from the revision -->
79 <!-- entries other than the current revision. -->
80 <!-- The revision numbering system for GNOME manuals is as follows: -->
81 <!-- * the revision number consists of two components -->
82 <!-- * the first component of the revision number reflects the release version of the GNOME desktop. -->
83 <!-- * the second component of the revision number is a decimal unit that is incremented with each revision of the manual. -->
84 <!-- For example, if the GNOME desktop release is V2.x, the first version of the manual that -->
85 <!-- is written in that desktop timeframe is V2.0, the second version of the manual is V2.1, etc. -->
86 <!-- When the desktop release version changes to V3.x, the revision number of the manual changes -->
87 <!-- to V3.0, and so on. -->
90 <revnumber>Empathy Manual V&manrevision;</revnumber>
93 <para role="author">Milo Casagrande
94 <email>milo@ubuntu.com</email>
96 <para role="publisher">GNOME Documentation Project</para>
101 <revnumber>Empathy Manual V2.1</revnumber>
102 <date>January 2009</date>
104 <para role="author">Milo Casagrande
105 <email>milo@ubuntu.com</email>
107 <para role="publisher">Ubuntu Documentation Project</para>
112 <revnumber>Empathy Manual V2.0</revnumber>
113 <date>April 2008</date>
115 <para role="author">Milo Casagrande
116 <email>milo@ubuntu.com</email>
118 <para role="author">Seth Dudenhofer
119 <email>sdudenhofer@gmail.com</email>
121 <para role="publisher">Ubuntu Documentation Project</para>
127 This manual describes version &appversion; of &appname;.
130 <title>Feedback</title>
132 To report a bug or make a suggestion regarding the &app; application or
133 this manual, follow the directions in the <ulink url="ghelp:user-guide?feedback" type="help">GNOME Feedback Page</ulink>.
137 <abstract role="description">
139 &appname; is an application for instant messaging.
145 <indexterm zone="index">
146 <primary>Empathy</primary>
148 <indexterm zone="index">
149 <primary>empathy</primary>
150 <secondary>istant messaging</secondary>
153 <sect1 id="empathy-intro">
154 <title>Introduction</title>
156 &app; is a multi-protocol instant messaging program for the
157 GNOME Desktop. With &app; you can keep in touch with all of your
158 friends through lots of supported instant messaging services.
161 &app; supports the following services:
165 <acronym>AIM</acronym>
180 <acronym>IRC</acronym>
185 Jabber (or <acronym>XMPP</acronym>)
190 <acronym>MSN</acronym>
200 <acronym>SIP</acronym>
217 <sect1 id="empathy-getting-started">
218 <title>Getting Started</title>
220 <sect2 id="empathy-starting">
221 <title>Starting &appname;</title>
222 <para>You can start &app; in the following ways:
226 <term><guimenu>Applications</guimenu> menu</term>
230 <guisubmenu>Internet</guisubmenu>
231 <guimenuitem>Empathy IM Client</guimenuitem>
237 <term>Command line</term>
239 <para>Type <command>empathy</command> and then press
240 <keycap>Enter</keycap>.
247 <sect2 id="emphaty-when-start">
248 <title>When You Start &appname;</title>
250 When you start &app; the following window is shown.
252 <figure id="empathy-FIG-mainwindow">
253 <title>&app; Main Window</title>
257 <imagedata fileref="figures/empathy-main-window.png" format="PNG"/>
261 Shows &app; main window. Contains the titlebar, the
262 menubar, contact list, status icon and status arrow
269 <!-- End of Figure -->
272 <xref linkend="empathy-TBL-1"/> describes the components of
274 <table frame="topbot" id="empathy-TBL-1">
275 <title>&app; Main Components</title>
276 <tgroup cols="2" colsep="0" rowsep="0">
277 <colspec colname="colspec0" colwidth="29.39*"/>
278 <colspec colname="colspec1" colwidth="70.61*"/>
282 <para>Component</para>
285 <para>Description</para>
296 Contains menus used to perform actions in &app;.
302 <para>Status Drop-Down List</para>
306 Allows to update the status.
312 <para>Account Button</para>
316 Opens the <guilabel>Accounts</guilabel> dialog.
322 <para>Contact List</para>
326 Shows all the available contacts and their
338 <sect1 id="empathy-accounts">
339 <title>Accounts</title>
341 To use &app; you need at least one account of the supported services.
344 If you don't already have an account and you don't have your <emphasis>user
345 name</emphasis> and <emphasis>password</emphasis>, you need to
346 register a new account (see <xref linkend="empathy-register-account" />).
349 In order to talk with other users, also called
350 <emphasis>contacts</emphasis>, you need to use the same service
351 they are using. If, for example, one contact is using the <emphasis
352 role="strong">Jabber</emphasis> service, you need to have an
353 account registered with that service.
356 &app; can handle as many accounts on any supported services as you want and
357 you can have them all open at the same time.
360 <sect2 id="empathy-register-account">
361 <title>Registering an Account</title>
363 You can freely register an account on any of the following
364 services. Follow the instructions reported on each website on
365 how to register your new account. At the end of the
366 registration process you should have a <emphasis>user
367 name</emphasis> (or an <emphasis>account ID</emphasis>) and
368 a <emphasis>password</emphasis> that you will use to
369 create the account in &app;.
372 Click on the name of the service to visit its website:
373 <!-- Need to do like that, if using only
374 <ulink>SERVICE</ulink> it wouldn't be possibile to
375 localize the links -->
378 <!-- Translators: try to find a localized version of the
379 registration service website -->
381 The <ulink type="http" url="&aim;">AIM</ulink> service.
385 <!-- Translators: try to find a localized version of the
386 registration service website -->
388 The <ulink type="http" url=">alk;">Google
389 Talk</ulink> service.
393 <!-- Translators: try to find a localized version of the
394 registration service website -->
396 The <ulink type="http" url="&icq;">ICQ</ulink> service.
400 <!-- Translators: try to find a localized version of the
401 registration service website -->
403 The <ulink type="http" url="&msn;">MSN</ulink> service.
407 <!-- Translators: try to find a localized version of the
408 registration service website -->
410 The <ulink type="http" url="&yahoo;">Yahoo</ulink> service.
416 For registering a <acronym>SIP</acronym> account, you can use one of the
422 <!-- Translators: try to find a localized version of the
423 registration service website -->
425 The <ulink type="http" url="&ekiga;">Ekiga</ulink> service.
429 <!-- Translators: try to find a localized version of the
430 registration service website -->
432 The <ulink type="http" url="&fwd;"><acronym>FWD</acronym></ulink> (Free
433 World Dialup) service.
437 <!-- Translators: try to find a localized version of the
438 registration service website -->
440 The <ulink type="http" url="&sipphone;">Sipphone</ulink> service.
446 For registering a <emphasis role="strong">Jabber</emphasis>
447 account, you can use the automatic
448 account creation of &app;. Not all Jabber service
449 providers support the automatic creation of accounts, one
450 service provider known to work with &app; is <ulink
451 type="http" url="&jabber;">jabber.org</ulink>.
454 If you already have a <emphasis
455 role="strong">Jabber</emphasis> account, you can use one of
456 the following services:
469 <sect2 id="empathy-create-account">
470 <title>Adding your Account to &app;</title>
472 To add your account to &app;, proceed as follows:
476 From the <link linkend="empathy-FIG-mainwindow">main window
477 </link> (<guilabel>Contact List</guilabel>)
478 click on the account button or press <keycap>F4</keycap> to open the
479 <guilabel>Accounts</guilabel> dialog.
484 If it is the first time you launch &app;:
488 From the <guilabel>Type</guilabel> drop-down list choose
489 the service you wish to add an account for, then click
490 on the <guibutton>Create</guibutton> button.
500 Click on the <guilabel>Add</guilabel> button.
505 From the <guilabel>Type</guilabel> drop-down list choose
506 the service you wish to add an account for, then click
507 on the <guibutton>Create</guibutton> button.
515 Fill the required fields with your <emphasis>user
517 <emphasis>password</emphasis>. Optionally, you can
518 modify some advanced options. For more information,
519 see <xref linkend="empathy-advanced-options"/>.
524 To enable the new account, select the
525 <guilabel>Enabled</guilabel> check-box next to
526 the name of the account in the box on the left.
532 <sect3 id="empathy-importing-accounts">
533 <title>Importing Accounts</title>
535 If you use another instant messaging program, you can import
536 the accounts from that program into &app;
541 At the moment &app; can import the accounts only from
542 the instant messaging program
543 <application>Pidgin</application>. For more information
544 about <application>Pidgin</application>, see the <ulink
545 type="http" url="http://www.pidgin.im/">Pidgin website</ulink>.
550 To import the accounts into &app;, proceed as follows:
554 From the <link linkend="empathy-FIG-mainwindow">main window
555 </link> (<guilabel>Contact List</guilabel>)
556 click on the account button or press <keycap>F4</keycap> to open the
557 <guilabel>Accounts</guilabel> dialog.
562 Click on the <guibutton>Import Accounts...</guibutton>
563 button to open the <guilabel>Import
564 Accounts</guilabel> dialog.
569 Select the accounts you would like to import by
570 clicking on the <guilabel>Import</guilabel> check-box.
575 When you have selected all the desired accounts, click
576 <guibutton>OK</guibutton> to import them. If you don't
577 want to import the accounts, click
578 <guibutton>Cancel</guibutton>.
583 When you import a new account into &app;, it will not be
587 To enable the new account, select the
588 <guilabel>Enabled</guilabel> check-box next to
589 the name of the account in the box on the left.
597 <sect2 id="empathy-edit-account">
598 <title>Editing an Account</title>
600 To edit one of your accounts, i.e. to change the
601 <emphasis>password</emphasis> or your <emphasis>user
602 name</emphasis>, proceed as follows:
606 From the <link linkend="empathy-FIG-mainwindow">main window
607 </link> (<guilabel>Contact List</guilabel>)
608 click on the account button or press <keycap>F4</keycap> to open the
609 <guilabel>Accounts</guilabel> dialog.
614 Select the account you wish to edit in the box on the
620 Modify the desired data.
628 Based on the type of the account, it is possibile to edit
634 To modify the identifier of an account, how &app; identifies
635 an account, proceed as follows:
639 From the <link linkend="empathy-FIG-mainwindow">main window
640 </link> (<guilabel>Contact List</guilabel>)
641 click on the account button or press <keycap>F4</keycap> to open the
642 <guilabel>Accounts</guilabel> dialog.
647 Select the account you wish to edit in the box on the
648 left and double-click on its name.
653 Change the name of the account as you desire.
660 <sect2 id="empathy-disabling-removing-account">
661 <title>Disabling and Removing an Account</title>
663 To disable an account, proceed as follows:
669 From the <link linkend="empathy-FIG-mainwindow">main window
670 </link> (<guilabel>Contact List</guilabel>)
671 click on the account button or press <keycap>F4</keycap>
673 <guilabel>Accounts</guilabel> dialog.
678 Select the account you wish to disable in the box on the
679 left of the dialog and deselect the
680 <guilabel>Enabled</guilabel> check-box.
686 To remove an account, proceed as follows:
692 From the <link linkend="empathy-FIG-mainwindow">main window
693 </link> (<guilabel>Contact List</guilabel>)
694 click on the account button or press <keycap>F4</keycap>
696 <guilabel>Accounts</guilabel> dialog.
701 Select the account you wish to disable in the box on the
707 Click on the <guibutton>Remove</guibutton> button.
712 A dialog will be shown asking for confirmation. Click on
713 the <guibutton>Remove</guibutton> button to remove the account.
720 <sect2 id="empathy-edit-personal-information">
721 <title>Editing Personal Information</title>
723 To change your personal information, your alias and your
724 icon (the image that other contacts will see of you), for each
725 of your accounts, proceed as follows:
731 From the <link linkend="empathy-FIG-mainwindow">main
732 window</link>, select <menuchoice>
733 <guimenu>Edit</guimenu>
734 <guimenuitem>Personal Information</guimenuitem>
740 From the <guilabel>Account</guilabel> drop-down list, choose
741 the account you want to edit.
746 In the <guilabel>Alias</guilabel> text box, write your new
752 To change your icon, click on the person-looking button and
753 choose an image file.
758 When done, click <guibutton>Close</guibutton>.
766 An <emphasis>alias</emphasis> is an alternative way you
767 can identify yourself. You can use your real
774 <sect2 id="empathy-advanced-options">
775 <title>Advanced Options</title>
777 Based on the service you are using, it is possible to
778 configure more advanced options to modify the normal behavior of
782 To configure these options, when you are <link
783 linkend="empathy-create-account">adding a new
784 account</link>, click on the drop-down section
785 <guilabel>Advanced</guilabel>.
788 <sect3 id="empathy-xmpp-advanced">
790 Jabber (or <acronym>XMPP</acronym>) and Google Talk
796 <guilabel>Encryption required (TLS/SSL)</guilabel>
800 Select this option in order to use some sort of
801 encryption during your conversations.
807 <guilabel>Ignore SSL certificate errors</guilabel>
811 Select this option in order to ignore the errors
812 that can be generated by some types of security
813 certificates. Usually these certificates are called
819 Select this option only if you are sure the
820 certificate is secure and you can trust it.
828 <guilabel>Resource</guilabel>
832 Use this text box to set a name with which you can
833 identify the running program based on where you are
834 running it. With this option, and the
835 <guilabel>Priority</guilabel> one, you can
836 use your account simultaneously in two different
837 devices. For example, if you set one device to
838 <replaceable>desktop</replaceable> and the other
839 one to <replaceable>mobile</replaceable>, you can
840 connect with both of them and based on the
841 <guilabel>Priority</guilabel> value you will receive
842 messages on one of the two devices or both.
845 This can be useful if you have two devices, a main
846 one and a portable one, and you move away from the
847 main one bringing with you the other: you can still
848 receive messages from your account with the portable
849 device even if you do not disconnet from the main one.
854 If you set the same value for this text box on
855 both the devices, when you connect with one of
856 them, the other one will be disconnected, even
857 if you set a different value with the
858 <guilabel>Priority</guilabel> spin box.
866 <guilabel>Priority</guilabel>
870 Use this spin box to indicate wich device, set in
871 the <guilabel>Resource</guilabel> text box, will
872 receive the new messages. The higher the number, the
873 higher the priority: you will receive the new
874 messages on the device with the highest number.
877 You can set values in the range from
878 <literal>-128</literal> to <literal>127</literal>.
883 If you set the same value of this spin box in
884 both the devices, you will receive messages on
894 In the <guilabel>Override server settings</guilabel> section
895 you can set options that take precedence over the default settings.
899 <guilabel>Server</guilabel>
903 Use this text box to write the name of the
904 server you want to use for this service.
910 <guilabel>Port</guilabel>
914 Use this spin box to set the number of the port of
918 You can set values in the range from
919 <literal>0</literal> to <literal>65,555</literal>.
925 <guilabel>Use old SSL</guilabel>
929 Select this option to use the old version of the
930 secure protocol for encrypting your connection.
938 <sect3 id="empathy-yahoo-advanced">
944 <guilabel>Ignore conference and chatrooms
945 invitations</guilabel>
949 Select this option to ignore the invitations that
950 other people may send you.
956 <guilabel>Room List locale</guilabel>
960 The value of this text box identifies the language
961 used to retrieve the room list when connecting to
965 If you need to change this value, use the two letter
966 code of your language.
972 <guilabel>Charset</guilabel>
976 The value of this text box identifies the set of the
977 characters used by &app;.
982 It is advise to leave this value to
983 <literal>UTF-8</literal>. Change it only
984 if that charset does not cover your language.
992 <guilabel>Server</guilabel>
996 Use this text box to write the name of the
997 server you want to use for this service.
1003 <guilabel>Port</guilabel>
1007 Use this spin box to set the number of the port of
1011 You can set values in the range from
1012 <literal>0</literal> to <literal>65,555</literal>.
1018 <guilabel>Use Yahoo Japan</guilabel>
1022 Select this option only if you have a Yahoo! Japan
1023 account. With the Yahoo! Japan service you can only
1024 use a Yahoo! Japan account: if you have registered
1025 an account with the English version of the service,
1026 that account will not work.
1034 <sect3 id="empathy-msn-advanced">
1035 <title><acronym>AIM</acronym>, GroupWise and <acronym>MSN</acronym></title>
1040 <guilabel>Server</guilabel>
1044 Use this text box to write the name of the
1045 server you want to use for this service.
1051 <guilabel>Port</guilabel>
1055 Use this spin box to set the number of the port of
1059 You can set values in the range from
1060 <literal>0</literal> to <literal>65,555</literal>.
1068 <sect3 id="empathy-salut-advanced">
1069 <title>Salut</title>
1074 <guilabel>Published Name</guilabel>
1078 Use this text box to write the name that will be
1079 visible to the other users of the network.
1085 <guilabel>Email</guilabel>
1089 Use this text box to write your email.
1095 <guilabel>Jabber ID</guilabel>
1099 Use this text box to write your Jabber ID, if you
1108 <sect3 id="empathy-icq-advanced">
1114 <guilabel>Charset</guilabel>
1118 The value of this text box identifies the set of the
1119 characters used by &app;.
1124 It is advise to leave this value to
1125 <literal>UTF-8</literal>. Change it only
1126 if that charset does not cover your language.
1134 <guilabel>Server</guilabel>
1138 Use this text box to write the name of the
1139 server you want to use for this service.
1145 <guilabel>Port</guilabel>
1149 Use this spin box to set the number of the port of
1153 You can set values in the range from
1154 <literal>0</literal> to <literal>65,555</literal>.
1162 <sect3 id="empathy-gadugadu-advanced">
1163 <title>Gadu Gadu</title>
1167 <term><guilabel>Nick</guilabel></term>
1170 Use this text box to write an alternative name to
1171 use with this service.
1183 <sect1 id="empathy-contacts-groups">
1184 <title>Contacts and Groups</title>
1186 All the contacts are handled within &app;'s <link
1187 linkend="empathy-FIG-mainwindow">main window</link>.
1190 You can add or remove a contact or you can edit the information
1191 of a particular contact. It is also possibile to arrange
1192 contacts in groups. You can have a group for your work contacts,
1193 one for you family contacts, and so on.
1195 <sect2 id="empathy-add-contact">
1196 <title>Adding and Removing a Contact</title>
1198 To add a new contact, proceed as follows:
1204 From the <link linkend="empathy-FIG-mainwindow">main
1205 window</link> choose <menuchoice>
1206 <guimenu>Chat</guimenu>
1207 <guimenuitem>Add Contact...</guimenuitem>
1208 </menuchoice>. The <guilabel>New Contact</guilabel>
1209 dialog will be shown.
1214 From the <guilabel>Account</guilabel> drop-down list,
1215 choose the service used by the contact you are adding.
1220 In the <guilabel>Identifier</guilabel> text box type the
1221 <emphasis>address</emphasis> of the contact in the form
1223 <userinput><replaceable>user name</replaceable>@<replaceable>service
1224 domain</replaceable></userinput>.
1229 In the <guilabel>Alias</guilabel> text box type the name
1230 you want to give at the the new contact.
1235 Click on <guibutton>Add</guibutton> to add the new contact.
1241 To remove a contact, proceed as follows:
1247 From the <link linkend="empathy-FIG-mainwindow">main
1248 window</link>, select the contact you would like
1249 to remove and right-click on it.
1254 From the popup menu, choose <guilabel>Remove</guilabel> to
1263 An <emphasis>alias</emphasis> is an alternative way you
1264 can identify that particular contact. You can use the real
1265 name or the nickname of that person.
1270 <sect2 id="empathy-edit-contact">
1271 <title>Editing a Contact</title>
1273 To edit a contact, proceed as follows:
1279 From the <link linkend="empathy-FIG-mainwindow">main
1280 window</link>, select the contact you would like
1281 to modify and choose <menuchoice>
1282 <guimenu>Edit</guimenu>
1283 <guisubmenu>Contact</guisubmenu>
1284 <guimenuitem>Edit</guimenuitem>
1285 </menuchoice>, or right-click on it
1286 and choose <guilabel>Edit</guilabel>.
1292 From the <guilabel>Edit Contact Information</guilabel> dialog,
1293 you can modify the <emphasis>alias</emphasis>
1294 and the <emphasis>group</emphasis> of the contact.
1299 An <emphasis>alias</emphasis> is an alternative way you
1300 can identify that particular contact. You can use the real
1301 name or the nickname of that person.
1306 For more information about groups, see <xref
1307 linkend="empathy-add-contact-group"/> and <xref
1308 linkend="empathy-add-group"/>.
1312 <sect2 id="empathy-add-contact-group">
1313 <title>Adding a Contact to a Group</title>
1315 To add a contact to one or more groups, proceed as follows:
1321 From the <link linkend="empathy-FIG-mainwindow">main
1322 window</link>, select the contact you would like
1323 to modify and choose <menuchoice>
1324 <guimenu>Edit</guimenu>
1325 <guisubmenu>Contact</guisubmenu>
1326 <guimenuitem>Edit</guimenuitem>
1327 </menuchoice>, or right-click on it
1328 and choose <guilabel>Edit</guilabel>.
1333 From the <guilabel>Groups</guilabel> section, select the
1334 group, or groups, you want to add the contact to.
1339 When done, click <guibutton>Close</guibutton>.
1346 <sect2 id="empathy-add-group">
1347 <title>Adding a New Group</title>
1349 To add a new group, proceed as follows:
1355 From the <link linkend="empathy-FIG-mainwindow">main
1356 window</link>, select one contact and choose <menuchoice>
1357 <guimenu>Edit</guimenu>
1358 <guisubmenu>Contact</guisubmenu>
1359 <guimenuitem>Edit</guimenuitem>
1360 </menuchoice>, or right-click on it
1361 and choose <guilabel>Edit</guilabel>.
1366 In the <guilabel>Groups</guilabel> section, write the
1367 name of the group you want to add and then click on
1368 <guibutton>Add Group</guibutton>.
1373 When done, click <guibutton>Close</guibutton>.
1382 <sect1 id="empathy-send-receive-message">
1383 <title>Sending and Receiving Messages</title>
1388 <sect1 id="empathy-preferences">
1389 <title>Preferences</title>