diff options
Diffstat (limited to 'jabber.texi')
| -rw-r--r-- | jabber.texi | 254 |
1 files changed, 168 insertions, 86 deletions
diff --git a/jabber.texi b/jabber.texi index 7f141e8..ae8315a 100644 --- a/jabber.texi +++ b/jabber.texi @@ -118,7 +118,7 @@ jabber-groupchat-join} and entering the address. This chapter is intended as an introduction to basic usage of jabber.el. If you have used Jabber before and are familiar with the -terminology, you might find it a bit too basic --- in that case, just +terminology, you might find it a bit too basic---in that case, just skim it, making sure to pick up the commands mentioned. I'll assume that you have already successfully installed jabber.el; if @@ -154,7 +154,7 @@ a Jabber ID. @xref{Account settings}, for Google-specific configuration. @item LJ Talk (of Livejournal) uses Jabber. Your Jabber ID is -@code{@samp{ljusername}@@livejournal.com}. +@samp{@var{ljusername}@@livejournal.com}. @end itemize @node Registering an account, Connecting, Do you have a Jabber account?, Basic operation @@ -162,15 +162,16 @@ LJ Talk (of Livejournal) uses Jabber. Your Jabber ID is @cindex Registering an account -TBD +If you do not yet have a Jabber account, you can register one. The +registration processes for various servers differ, but many servers +support so-called ``in-band registration'', which is described in this +section. -If you do not yet have a Jabber account, you can register one. Enter -your desired username and the server you wish -to use in @code{jabber-account-list}, save, and type @kbd{C-u M-x -jabber-connect}. If the server supports -in-band registration, you will be presented with a registration form to -fill out and send. There the username you chose will be prefilled. -Don't change it, otherwise jabber.el will be confused. +To register an account, type @kbd{C-u M-x jabber-connect} and enter your +desired JID in the form @samp{@var{username}@@@var{server}}. You will +be presented with a registration form to fill out and send. There the +username you chose will be prefilled. After registration, you can +connect to the server as usual. @node Connecting, Chatting, Registering an account, Basic operation @section Connecting @@ -198,7 +199,8 @@ it in the variable @code{jabber-account-list}. @xref{Account settings}. If you configure more than one account, all of them will be connected when you type @kbd{C-x C-j C-c}, as that key is bound to @code{jabber-connect-all}. To connect only one account, possibly one -that's not in your list, type @kbd{M-x jabber-connect}. +that's not in your list, type @kbd{M-x jabber-connect} or @kbd{C-u C-x +C-j C-c}. @node Chatting, Presence, Connecting, Basic operation @section Chatting @@ -210,6 +212,12 @@ There are several ways to open a chat buffer. The shortest way is to put point over the person you want to chat with in the roster display and hit RET. +You can also use the function @code{jabber-chat-with}. This function is +bound to @kbd{C-x C-j C-j} in the global keymap. You will be asked to +enter a JID in the minibuffer. You can also enter the roster name of +one of your contacts. All JIDs and names in your roster can be +tab-completed. + You can also use menus to access commands. In the roster display, you can access several menus through keystrokes or mouse clicks. You can bring one big menu up by pressing the second mouse button, or you can @@ -217,18 +225,15 @@ bring up the ``chat menu'' by typing @kbd{C-c C-c}. If you do the latter while point is on a roster entry, that entry will be the default value when you are asked for whom to chat with. -You can also use the function @code{jabber-chat-with}, which is what the -menu item is bound to. This function is bound to @kbd{C-x C-j C-j} in -the global keymap. - Now, try opening a chat with someone. A buffer named @code{*-jabber-chat-:-@var{person}-*} will be created and selected. Type your message at the end of the buffer, and hit @kbd{RET} to send it. To include a newline in your message, use @kbd{C-j}. When you receive a message from someone, you will see a red indicator in -the mode line. You can click this indicator or type @kbd{C-x C-j C-l} -to switch to the relevant buffer. +the mode line. You can click this indicator with the mouse, or type +@kbd{C-x C-j C-l} to switch to the relevant buffer. @xref{Tracking +activity}. @node Presence, Presence subscription, Chatting, Basic operation @section Presence @@ -241,12 +246,12 @@ to switch to the relevant buffer. @vindex jabber-default-status @vindex jabber-default-priority -``Presence'' is the Jabber term for letting other people know that you +@dfn{Presence} is the Jabber term for letting other people know that you are online, and additionally how ``available'' you are. There are -three elements to presence: availability status (called ``show''), +three elements to presence: availability state (called ``show''), status message, and priority. -Your show status may either be empty (meaning simply ``online''), or +Your show state may either be empty (meaning simply ``online''), or one of @code{away}, @code{xa}, @code{dnd} and @code{chat}, meaning ``away'', ``extended away'' (i.e. away for an extended period), ``do not disturb'', and ``free for chat'', respectively. This information @@ -259,25 +264,77 @@ such as ``at home'', ``working'', ``phone'', ``playing games'' or whatever you want. It is sent to everyone subscribing to your presence, but not all clients prominently display it to the user. -The priority is only interesting if you are running more than one -Jabber client at a time accessing the same account. In that case, -messages sent to you without an indication of which client to send to -are sent to the client with the highest priority. +The priority is only interesting if you are running more than one Jabber +client at a time accessing the same account. @xref{Resources and +priority}. -To set your presence, use the function @code{jabber-send-presence}. +To set your presence, use the function @code{jabber-send-presence} +(bound to @kbd{C-x C-j C-p}). It can be called both interactively and in Lisp code. For the latter case, use something like @code{(jabber-send-presence "away" "idle for -10 minutes" 10)}. +10 minutes" 10)}. There are a few shortcuts: +@table @kbd +@item C-x C-j C-a +Send ``away'' presence (with prefix argument, specify status text) +@item C-x C-j C-x +Send ``extended away'' presence (with prefix argument, specify status +text) +@item C-x C-j C-o +Send default presence (see below) +@end table By default, jabber.el sets your presence when you connect. If you -want it not to do that, remove @code{jabber-send-default-presence} -from @code{jabber-post-connect-hook}. If you want to change the +want it not to do that, remove @code{jabber-send-current-presence} +from @code{jabber-post-connect-hooks}. If you want to change the presence that is sent, change the variables @code{jabber-default-show}, @code{jabber-default-status} and @code{jabber-default-priority}. With jabber.el, you can set your presence remotely. @xref{Ad-Hoc Commands}. +@menu +* Resources and priority:: +* Directed presence:: +@end menu + +@node Resources and priority, Directed presence, Presence, Presence +@subsection Resources and priority + +@cindex Resource +@cindex Priority + +Every connection to an account has a specific name, a @dfn{resource}. +The account itself has a JID of the form +@samp{@var{username}@@@var{server}} (a @dfn{bare JID}), but the +connections have JIDs of the form +@samp{@var{username}@@@var{server}/@var{resource}} (a @dfn{full JID}). +You can choose the resource name yourself by entering a JID of the +latter form at the connection prompt (@pxref{Connecting}), or by +configuring it in @code{jabber-account-list} (@pxref{Account settings}) + +Each session has a @dfn{priority}. The priority determines what happens +when a message is sent to the bare JID (i.e. without specifying what +connection should receive message). Such messages are delivered to the +connection with the highest non-negative priority value. If there are +no connections, or if all connections have negative priority, the +message is either stored on the server for later delivery or bounced to +the sender, depending on the server configuration. + +If there are several connections with the same priority, the behaviour +depends on the server. Some server implementations deliver the message +to all such connections, while others choose one connection depending on +certain rules. + +Note that these rules do not apply when a message is sent to a full +JID. Such messages are sent to the specified resource, if it is still +connected, and otherwise treated as messages to the bare JID. In the +chat buffers of jabber.el, messages are sent to whatever JID the last +message came from (usually a full JID), or to the bare JID if no message +has been received yet. Other clients may have different behaviour. + +@node Directed presence, , Resources and priority, Presence +@subsection Directed presence + @cindex directed presence @cindex send directed presence @findex jabber-send-directed-presence @@ -298,11 +355,21 @@ presence update. Having permission to view the presence status of a person is called @dfn{subscribing to his presence}. Presence subscription between two -persons can be asymmetric. +persons can be asymmetric. Subscription state is shown in the roster +display by arrows (@pxref{Customizing the roster buffer}). A +left-pointing arrow means that the contact can see your presence +(``from''). A right-pointing arrow means that you can see the contact's +presence (``to''). The most common case is mutual subscription, a +double-ended arrow (``both''). When jabber.el receives a presence subscription request, it will present -it to you in an chat buffer, and offer you to choose subscription mode -and send a subscription request back to that person. +it to you in a chat buffer, and offer you to choose subscription mode +and send a subscription request back to that person. The ``Mutual'' +button accepts the request and sends a reciprocal request.@footnote{If this +request is superfluous, the server will drop it without bothering the +contact.} The ``One-way'' button accepts the request, but doesn't ask +for a subscription in return. The ``Decline'' button declines the +request. To request subscription to someone, type @kbd{M-x jabber-send-subscription-request}. You will be prompted for the JID @@ -319,36 +386,41 @@ roster buffer. @cindex Roster buffer, basics @cindex Menus @cindex Key bindings -@findex jabber-display-roster The roster buffer is called @code{*-jabber-*}. It simply contains a -list of the contacts on your roster. +list of the contacts on your roster. If you have several accounts +connected, contacts will be grouped by account. In the roster buffer, any command which requires a JID will default to the JID under point when called. These commands can be called through either keyboard menus or mouse menus. To open a menu with the mouse, simply press the second mouse button over the JID in question.@footnote{For some reason, mouse menus don't work in XEmacs. -Patches welcome.} This will bring up a menu with all available +Patches are welcome.} This will bring up a menu with all available actions. The keyboard menus are split into categories: Chat, Roster, Information, MUC (Multi-User Chat, or groupchat) and Services, opened by @kbd{C-c C-c}, @kbd{C-c C-r}, @kbd{C-c C-i}, @kbd{C-c C-m} and @kbd{C-c C-s}, respectively. +@vindex jabber-roster-show-bindings A list of keybindings is displayed at the top of the roster buffer. You can turn it off by setting @code{jabber-roster-show-bindings} to nil. -You can call @code{jabber-display-roster} to redisplay your roster -according to changed preferences (@pxref{Customizing the roster -buffer}). This will not refetch your roster from the server. -Refetching the roster is usually not needed, since updates are pushed -to clients automatically. +@findex jabber-display-roster +You can call @code{jabber-display-roster} (bound to @kbd{g}) to +redisplay your roster according to changed preferences +(@pxref{Customizing the roster buffer}). This will not refetch your +roster from the server. Refetching the roster is usually not needed, +since updates are pushed to clients automatically. You can choose not to have the roster updated automatically on presence changes (@pxref{Presence alerts}). In that case, you need to call @code{jabber-display-roster} manually. +@vindex jabber-show-offline-contacts +@cindex Hiding offline contacts +@cindex Offline contacts, hiding Please note, that by default offline contacts showed in roster as any others. To hide them, you can use @kbd{o} in roster buffer. To permanently hide them, customize @code{jabber-show-offline-contacts} @@ -365,14 +437,6 @@ The groupchat menu can be accessed by typing @kbd{C-c C-m} in the roster buffer. You can also type the commands directly, as will be shown here. -Also, to save from repeating unnesesary typing you can press @kbd{Tab} -key to complete nick of groupchat member, you a talking with. You can -customize your form of personal talking in MUC -(@code{jabber-muc-completion-delimiter}) and form of personal talking -to you (@code{jabber-muc-looks-personaling-symbols}) - see -``jabber-chat'' customization group. Defaults are sane, so unlikely -you could change this, but... it is Emacs! - @findex jabber-groupchat-join @cindex Joining a groupchat @cindex Changing nickname @@ -382,10 +446,10 @@ be prompted for the groupchat to join, and your nickname in the groupchat. This nickname doesn't need to have any correlation to your JID; in fact, groupchats are usually (but not always) configured such that only moderators can see your JID. You can change your nickname -with @kbd{M-x jabber-muc-nick}. @xref{Automation}, for setting default +with @kbd{M-x jabber-muc-nick}. @xref{Configuration}, for setting default nicknames. -@cindex query groupchat +@cindex Query groupchat @vindex jabber-muc-disable-disco-check When trying to join a room, jabber.el first sends a service discovery info request to the room, to find out whether it exists and what @@ -393,12 +457,29 @@ features are enabled (in particular whether the room is password-protected). However, this can cause problems with some buggy MUC services (or services that respond in a way that jabber.el doesn't expect). A workaround for that is to set -@code{jabber-muc-disable-disco-check} to t; however, the bug should be +@code{jabber-muc-disable-disco-check} to @code{t}; however, the bug should be unearthed and fixed. Groupchat messages will be displayed in a buffer called -@code{*-jabber-groupchat-:-@var{groupchat}-*}. It works much like the -chat buffer. +@code{*-jabber-groupchat-:-@var{groupchat}-*}. By default, the buffer +name is based on the JID of the chat room. If you want a shorter name, +you can add the chat room to your roster and give it a name, using the +command @kbd{M-x jabber-roster-change}. The groupchat buffer works much +like the chat buffer. It has its own class of alerts +(@pxref{Customizing alerts}), and uses activity tracking +(@pxref{Tracking activity}). + +@vindex jabber-muc-completion-delimiter +@vindex jabber-muc-looks-personaling-symbols +@cindex Groupchat completion +@cindex Nick completion in groupchat +Also, to save from repeating unnesesary typing you can press @kbd{Tab} +key to complete nick of a groupchat member that you are talking with. +You can customize your form of personal talking in MUC +(@code{jabber-muc-completion-delimiter}) and form of personal talking to +you (@code{jabber-muc-looks-personaling-symbols})---see ``jabber-chat'' +customization group. Defaults are sane, so it is unlikely that you would +want to change this, but... it is Emacs! @cindex Topic, MUC @findex jabber-muc-set-topic @@ -421,49 +502,50 @@ the meaning of roles and affiliations. @menu -* Automation:: -* Bookmarks:: +* Configuration:: * Invitations:: * Private messages:: * MUC Administration:: @end menu -@node Automation, Bookmarks, Groupchat, Groupchat -@section Automation +@node Configuration, Invitations, Groupchat, Groupchat +@section Configuration @vindex jabber-muc-default-nicknames @vindex jabber-muc-autojoin @findex jabber-muc-autojoin @cindex Default MUC nickname @cindex Autojoin chat rooms +@cindex Bookmarks, MUC +@findex jabber-edit-bookmarks -You can select a default nickname by setting -@code{jabber-account-list} (part of JID before @code{@@}). -Additionally, you can set different nicknames for different groups, by -customizing @code{jabber-muc-default-nicknames}. There you specify -the JID of the group, and your preferred nickname. - -If you want to automatically join certain rooms when connecting, you -can set @code{jabber-muc-autojoin} to a list containing the JIDs of -the rooms you want to enter. To disable this feature, remove -@code{jabber-muc-autojoin} from @code{jabber-post-connect-hook}. +You can configure jabber.el to use a certain nickname for a certain +room, or to automatically join a certain room when you connect. You can +do this either by storing bookmarks on the server or by setting Emacs +variables. -Please note, that @code{jabber-muc-default-nicknames} and -@code{jabber-muc-autojoin} are machine-local. To make them available -to any client on any machine, import them in your bookmarks. See -@xref{Bookmarks}. +Type @kbd{M-x jabber-edit-bookmarks} to add bookmarks. You can specify +the JID of the conference, the name of the conference (not used by +jabber.el), whether to automatically join the room, your desired +nickname (or leave empty), and the room password (or leave empty). -@node Bookmarks, Invitations, Automation, Groupchat -@section Bookmarks +The default nickname for groupchats is the username part of your JID. +If you don't use bookmarks, you can set different nicknames for +different groups by customizing @code{jabber-muc-default-nicknames}. +There you specify the JID of the group, and your preferred nickname. -@cindex Bookmarks -@findex jabber-edit-bookmarks +Automatically joining certain rooms when connecting can be accomplished +by setting @code{jabber-muc-autojoin} to a list containing the JIDs of +the rooms you want to enter. To disable this feature, remove +@code{jabber-muc-autojoin} from @code{jabber-post-connect-hooks}. -You can store your conference settings on server-side to make them -available from any machine and client. Use @code{M-x -jabber-edit-bookmarks} to edit server-side bookmarks. +Please note, that @code{jabber-muc-default-nicknames} and +@code{jabber-muc-autojoin} are machine-local, but apply to @emph{all} +accounts---if you connect several accounts, both will try to connect to +the same chat rooms, or use the same nickname. This will lead to +confusion. -@node Invitations, Private messages, Bookmarks, Groupchat +@node Invitations, Private messages, Configuration, Groupchat @section Invitations @cindex Invitations @@ -471,7 +553,7 @@ jabber-edit-bookmarks} to edit server-side bookmarks. You can invite someone to a groupchat with @kbd{M-x jabber-muc-invite} (also available in the MUC menu). Pay attention to the order of the -arguments --- as both users and rooms are just JIDs, it is technically +arguments---as both users and rooms are just JIDs, it is technically possible to invite a room to a user, but that's probably not what you want. @@ -562,7 +644,7 @@ Rights depend on room configuration. The room might be members-only, or grant voice only to members. @item outcast -Banned from the room +Banned from the room. @end table @@ -928,9 +1010,9 @@ haven't used your computer for a while. This lets your contacts know that you might not answer immediately. To activate this feature, add @code{jabber-autoaway-start} to -@code{jabber-post-connect-hook}, e.g: +@code{jabber-post-connect-hooks}, e.g: @example -(add-hook 'jabber-post-connect-hook 'jabber-autoaway-start) +(add-hook 'jabber-post-connect-hooks 'jabber-autoaway-start) @end example There are different methods to find how long you have been ``idle''. @@ -1357,7 +1439,6 @@ this is Emacs. To open a customization buffer for jabber.el, type @cindex Resource @cindex Password @cindex JID -@cindex Resource @cindex Network server All account settings reside in @code{jabber-account-list} variable. @@ -1811,11 +1892,12 @@ jabber.el provides various hooks that you can use for whatever purpose. @table @code -@vindex jabber-post-connect-hook -@item jabber-post-connect-hook +@vindex jabber-post-connect-hooks +@item jabber-post-connect-hooks This hook is called after successful connection and authentication. By default it contains @code{jabber-send-default-presence} -(@pxref{Presence}). +(@pxref{Presence}). The hook functions get the connection object as +argument. @vindex jabber-lost-connection-hook @item jabber-lost-connection-hook |