X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/97ed0ac33e56158d8da7e7037119fccb0a8ffe3e..9705fb379eac387ad4a45550a8a43f171b91afaa:/man/rcirc.texi diff --git a/man/rcirc.texi b/man/rcirc.texi index cf02a477ab..15744e6642 100644 --- a/man/rcirc.texi +++ b/man/rcirc.texi @@ -5,7 +5,7 @@ @c %**end of header @copying -Copyright (C) 2006 Free Software Foundation, Inc. +Copyright @copyright{} 2006 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -29,7 +29,7 @@ license to the document, as described in section 6 of the license. @dircategory Emacs @direntry -* rcirc: (rcirc). Internet Relay Chat (IRC) client. +* Rcirc: (rcirc). Internet Relay Chat (IRC) client. @end direntry @titlepage @@ -52,12 +52,12 @@ topic channels which are collections of many users, or privately, with just one other user. @menu -* Basics:: -* Reference:: -* Hacking and Tweaking:: -* Key Index:: -* Variable Index:: -* Index:: +* Basics:: +* Reference:: +* Hacking and Tweaking:: +* Key Index:: +* Variable Index:: +* Index:: @detailmenu --- The Detailed Node Listing --- @@ -87,14 +87,13 @@ Hacking and Tweaking @node Basics, Reference, Top, Top @chapter Basics -@cindex basic usage This chapter contains a brief introduction to IRC (Internet Relay Chat), and a quick tutorial on @code{rcirc}. @menu -* Internet Relay Chat:: -* Getting started with rcirc:: +* Internet Relay Chat:: +* Getting started with rcirc:: @end menu @node Internet Relay Chat, Getting started with rcirc, Basics, Basics @@ -119,11 +118,11 @@ Here's a typical example: @cindex redirection to random servers When you connect to the Freenode network -(@indicateurl{http://freenode.net/}), you point your IRC client at the +(@code{http://freenode.net/}), you point your IRC client at the server @code{irc.freenode.net}. That server will redirect your client to a random server on the network, such as @code{zelazny.freenode.net}. -@cindex channel names +@cindex channel name @cindex # starts a channel name Once you're connected, you can send messages to all other users connected to the same network, and you can join all channels on the same @@ -137,9 +136,9 @@ all the other users on the same channel. @cindex addressing other people @cindex other people, addressing them @cindex talk to other people -If you want to address someone specifically, for example as an answer -to a question, it is custom to prefix the message with the nick -followed by a colon, like this: +If you want to address someone specifically, for example as an answer to +a question, it is customary to prefix the message with the nick followed +by a colon, like this: @example deego: fsbot rules! @@ -156,8 +155,12 @@ Since this is so common, you can use @key{TAB} to do nick completion. @cindex connecting to a server @cindex irc command -Use the command @kbd{M-x irc} to connect to a server. You will be asked -for four things: +Use the command @kbd{M-x irc} to connect using the defaults. +@xref{Configuration}, if you want to change the defaults. + +Use @kbd{C-u M-x irc} if you don't want to use the defaults, eg. if you +want to connect to a different network, or connect to the same network +using a different nick. This will prompt you for four things: @table @asis @cindex server, connecting @@ -185,7 +188,7 @@ have to use a different port. @vindex user-login-name Every users needs a handle on-line. You will automatically be assigned a slightly different nick if your chosen nick is already in use. If -your @code{user-login-name} is @code{"alex"}, and this nick is already +your @code{user-login-name} is @code{alex}, and this nick is already in use, you might for example get assigned the nick @code{alex`}. @cindex channels, connecting @@ -195,7 +198,8 @@ in use, you might for example get assigned the nick @code{alex`}. A space separated list of channels you want to join when connecting. You don't need to join any channels, if you just want to have one-to-one conversations with friends on the same network. If you're new to the -Freenode network, join @code{#emacs}, the about all things Emacs. +Freenode network, join @code{#emacs}, the channel about all things +Emacs, or join @code{#rcirc}, the channel about @code{rcirc}. @end table @cindex server buffer @@ -207,7 +211,7 @@ and a channel buffer for each of the channels you wanted to join. @cindex talking @cindex communicating To talk in a channel, just type in what you want to say in a channel -buffer, and press @kbd{RET}. +buffer, and press @key{RET}. @kindex C-c C-c @cindex multiline messages @@ -216,21 +220,10 @@ buffer, and press @kbd{RET}. @cindex edit message before sending If you want to paste multiple lines, such as source code, you can use @kbd{C-c C-c} to edit your message in a separate buffer. Use @kbd{C-c -C-c} to finish editing. You still need to press @kbd{RET} to send it, +C-c} to finish editing. You still need to press @key{RET} to send it, though. Generally, IRC users don't like people pasting more than around four lines of code, so use with care. -@kindex C-c C-SPC -@cindex switching channels -@cindex tracking activity -@cindex active channel -@cindex abbreviated channel names -@cindex modeline tracks activity -You will note that when other people say things in buffers that are -currently buried (no window is showing them), the mode line will show -you the abbreviated channel or nick name. Use @kbd{C-c C-SPC} to switch -to these buffers. - @node Reference, Hacking and Tweaking, Basics, Top @chapter Reference @cindex reference @@ -240,13 +233,14 @@ complete listings of @code{rcirc} features, use Emacs built-in documentation. @menu -* rcirc commands:: -* Useful IRC commands:: -* Configuration:: +* rcirc commands:: +* Useful IRC commands:: +* Configuration:: @end menu @node rcirc commands, Useful IRC commands, Reference, Reference @section rcirc commands +@cindex rcirc commands @cindex commands @kindex C-h m @@ -261,7 +255,7 @@ typing them into an @code{rcirc} buffer. @cindex typing commands @cindex commands For instance, instead of using the command @kbd{C-c C-j} to join a new -channel, you may type this in an @code{rcirc} buffer, and press @kbd{RET}: +channel, you may type this in an @code{rcirc} buffer, and press @key{RET}: @example /join #emacs @@ -361,7 +355,7 @@ Starts a one-to-one conversation with another person on the same network. A new buffer will be created for this conversation. It works like a channel with only two members. (Also @code{/query fsbot}.) -@item C-c RET +@item C-c @key{RET} @kindex C-c RET @cindex /msg @cindex single message @@ -399,8 +393,8 @@ commands, such as: @cindex idiots online This command toggles the ignore status of a nick, if you provide one. If you don't provide a nick, the command lists all the nicks you are -ignoring. All messages by ignored nicks are -- you guessed it -- -ignored. Since only ``operators'' can kick people from channels, the +ignoring. All messages by ignored nicks are---you guessed it---ignored. +Since only ``operators'' can kick people from channels, the ignore command is often the only way to deal with some of the more obnoxious fellows online. Example: @code{/ignore xah}. @end table @@ -430,46 +424,46 @@ your status as ``being back'' if you do not. People can use the @cindex help about irc Typical IRC servers implement many more commands. You can read more about the fantastic world of IRC online at -@indicateurl{http://www.irchelp.org/}, the Internet Relay Chat (IRC) -help archive. +@uref{http://www.irchelp.org/, the Internet Relay Chat (IRC) help +archive}. @node Configuration, , Useful IRC commands, Reference @section Configuration -@cindex configuration +@cindex configuring rcirc These are some variables you can change to configure @code{rcirc} to your liking. @table @code -@item rcirc-server -@vindex rcirc-server +@item rcirc-default-server +@vindex rcirc-default-server the default server to connect to. -@item rcirc-port -@vindex rcirc-port +@item rcirc-default-port +@vindex rcirc-default-port the default port to connect to. -@item rcirc-nick -@vindex rcirc-nick +@item rcirc-default-nick +@vindex rcirc-default-nick the default nick to use. @end table @example -(setq rcirc-server "irc.mozilla.org" - rcirc-port 6666 - rcirc-nick "alx") +(setq rcirc-default-server "irc.mozilla.org" + rcirc-default-port 6666 + rcirc-default-nick "alx") @end example -@vindex rcirc-user-full-name +@vindex rcirc-default-user-full-name @cindex full name @cindex real name @cindex surname -@code{rcirc-user-full-name} is used to set your ``real name'' on IRC. -It defaults to @code{user-full-name}. If you want to hide your full -name, you might want to set it to some pseudonym. +@code{rcirc-default-user-full-name} is used to set your ``real name'' on +IRC. It defaults to @code{user-full-name}. If you want to hide your +full name, you might want to set it to some pseudonym. @example -(setq rcirc-user-full-name "Curious Minds Want To Know") +(setq rcirc-default-user-full-name "Curious Minds Want To Know") @end example @vindex rcirc-startup-channels-alist @@ -493,6 +487,108 @@ In the example above we're exploiting a naming convention used by within the Freenode network --- all servers within the network have a host in the @code{freenode.net} domain. +@vindex rcirc-authinfo +@cindex authentification +@cindex identification +@cindex nickserv +@cindex login +@code{rcirc-authinfo} is an alist used to automatically identify +yourself on networks. Each sublist starts with a regular expression +that is compared to the server address you're connecting to. The second +element in the list is a symbol representing the method to use, followed +by the arguments this method requires. + +Here is an example to illustrate how you would set it: + +@example +(setq rcirc-authinfo + '(("freenode" nickserv "bob" "p455w0rd") + ("freenode" chanserv "bob" "#bobland" "passwd99") + ("bitlbee" bitlbee "robert" "sekrit"))) +@end example + +And here are the valid method symbols and the arguments they require: + +@table @code +@item nickserv +@cindex nickserv authentification +Use this symbol if you need to identify yourself as follows when +connecting to a network: @code{/msg nickserv identify secret}. The +necessary arguments are the nickname you want to use this for, and the +password to use. + +Before you can use this method, you will have to register your nick and +pick a password for it. Contact @code{nickserv} and check out the +details. (Using @code{/msg nickserv help}, for example.) + +@item chanserv +@cindex chanserv authentification +Use this symbol if you need to identify yourself as follows if you want +to join a particular channel: @code{/msg chanserv identify #underground +secret}. The necessary arguments are the nickname and channel you want +to use this for, and the password to use. + +Before you can use this method, a channel contact must tell you about +the password to use. Contact @code{chanserv} and check out the details. +(Using @code{/msg chanserv help}, for example.) + +@item bitlbee +@cindex bitlbee authentification +Use this symbol if you need to identify yourself in the Bitlbee channel +as follows: @code{identify secret}. The necessary arguments are the +nickname you want to use this for, and the password to use. + +@cindex gateway to other IM services +@cindex instant messaging, other services +@cindex Jabber +@cindex AIM +@cindex ICQ +@cindex MSN +@cindex Yahoo! +Bitlbee acts like an IRC server, but in fact it is a gateway to a lot of +other instant messaging services. You can either install Bitlbee +locally or use a public Bitlbee server. There, you need to create an +account with a password. This is the nick and password you need to +provide for the bitlbee authentification method. + +Later, you will tell Bitlbee about your accounts and passwords on all +the other instant messaging services, and Bitlbee will log you in. All +@code{rcirc} needs to know, is the login to your Bitlbee account. Don't +confuse the Bitlbee account with all the other accounts. +@end table + +@kindex C-c C-SPC +@vindex rcirc-track-minor-mode +@cindex switching channels +@cindex tracking activity +@cindex active channel +@cindex abbreviated channel names +@cindex modeline tracks activity +Most people want a notification when something is said on a channel they +have joined, particularly if they have been addressed directly. There +is a global minor mode that will do this kind of tracking for you. All +you need to do is switch it on using @kbd{M-x rcirc-track-minor-mode}. +To make this permanent, add the following to your init file: + +@example +(rcirc-track-minor-mode 1) +@end example + +When other people say things in buffers that are currently buried (no +window is showing them), the mode line will now show you the abbreviated +channel or nick name. Use @kbd{C-c C-@key{SPC}} to switch to these +buffers. + +@vindex rcirc-mode-hook +If you prefer not to load @code{rcirc} immediately, you can delay the +activation of this mode: + +@example +(add-hook 'rcirc-mode-hook + (lambda () + (rcirc-track-minor-mode 1))) +@end example + @node Hacking and Tweaking, Key Index, Reference, Top @chapter Hacking and Tweaking @cindex hacking and tweaking @@ -500,12 +596,12 @@ the @code{freenode.net} domain. Here are some examples of stuff you can do to configure @code{rcirc}. @menu -* Skipping /away messages using handlers:: -* Using fly spell mode:: -* Scrolling conservatively:: -* Changing the time stamp format:: -* Defining a new command:: -* Reconnecting after you have lost the connection:: +* Skipping /away messages using handlers:: +* Using fly spell mode:: +* Scrolling conservatively:: +* Changing the time stamp format:: +* Defining a new command:: +* Reconnecting after you have lost the connection:: @end menu @node Skipping /away messages using handlers, Using fly spell mode, Hacking and Tweaking, Hacking and Tweaking @@ -514,7 +610,7 @@ Here are some examples of stuff you can do to configure @code{rcirc}. @cindex handlers @cindex status codes -The IRC protocol specifies how certain events are signalled from server +The IRC protocol specifies how certain events are signaled from server to client. These events have numbers and are dealt with using so-called handlers. You can override existing handlers by exploiting the naming convention adopted for @code{rcirc}. @@ -566,7 +662,7 @@ window when possible. The following snippet uses a local value for 8192))) @end example -@xref{Scrolling, , Scrolling convervatively, emacs, The GNU Emacs +@xref{Scrolling, , Scrolling conservatively, emacs, The GNU Emacs Manual}, for details. @node Changing the time stamp format, Defining a new command, Scrolling conservatively, Hacking and Tweaking @@ -630,21 +726,21 @@ The real answer, therefore, is a @code{/reconnect} command: (error "There's no process for this target")) (let* ((server (car (process-contact process))) (port (process-contact process :service)) - (nick (with-rcirc-process-buffer process rcirc-nick)) + (nick (rcirc-nick process)) channels query-buffers) (dolist (buf (buffer-list)) (with-current-buffer buf - (when (eq process rcirc-process) + (when (eq process (rcirc-buffer-process)) + (remove-hook 'change-major-mode-hook + 'rcirc-change-major-mode-hook) (if (rcirc-channel-p rcirc-target) (setq channels (cons rcirc-target channels)) (setq query-buffers (cons buf query-buffers)))))) (delete-process process) - (let ((new-process (rcirc-connect server port nick - rcirc-user-name user-full-name - channels))) - (dolist (buf query-buffers) - (with-current-buffer buf - (setq rcirc-process new-process))))))) + (rcirc-connect server port nick + rcirc-default-user-name + rcirc-default-user-full-name + channels)))) @end smallexample @node Key Index, Variable Index, Hacking and Tweaking, Top @@ -660,3 +756,7 @@ The real answer, therefore, is a @code{/reconnect} command: @printindex cp @bye + +@ignore + arch-tag: 2589e562-3843-4ffc-8c2f-477cbad57c01 +@end ignore