Mercurial > emacs

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/man/rcirc.texi	Fri Jan 27 18:43:16 2006 +0000
@@ -0,0 +1,662 @@
+\input texinfo
+@c %**start of header
+@setfilename ../info/rcirc
+@settitle rcirc Manual
+@c %**end of header
+
+@copying
+Copyright (C) 2006 Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
+and with the Back-Cover Texts as in (a) below.  A copy of the license is
+included in the section entitled ``GNU Free Documentation License'' in
+the Emacs manual.
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software.  Copies published by the Free
+Software Foundation raise funds for GNU development.''
+
+This document is part of a collection distributed under the GNU Free
+Documentation License.  If you want to distribute this document
+separately from the collection, you can do so by adding a copy of the
+license to the document, as described in section 6 of the license.
+@end quotation
+@end copying
+
+@dircategory Emacs
+@direntry
+* rcirc: (rcirc).  Internet Relay Chat (IRC) client.
+@end direntry
+
+@titlepage
+@title rcirc Manual
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@ifnottex
+@node Top, Basics, (dir), (dir)
+@top rcirc Manual
+@end ifnottex
+
+@code{rcirc} is an Emacs IRC client.
+
+IRC (Internet Relay Chat) is a multi-user chat protocol.  Users
+communicate with each other in real-time.  Communication occurs both in
+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::
+
+@detailmenu
+ --- The Detailed Node Listing ---
+
+Basics
+
+* Internet Relay Chat::
+* Getting started with rcirc::
+
+Reference
+
+* rcirc commands::
+* Useful IRC commands::
+* Configuration::
+
+Hacking and Tweaking
+
+* 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 detailmenu
+@end menu
+
+@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::
+@end menu
+
+@node Internet Relay Chat, Getting started with rcirc, Basics, Basics
+@section Internet Relay Chat
+@cindex internet relay chat
+@cindex irc
+
+@cindex channel
+@dfn{Internet Relay Chat} (IRC) is a form of instant communication over the
+Internet.  It is mainly designed for group (many-to-many) communication
+in discussion forums called channels, but also allows one-to-one
+communication.
+
+@cindex instant messaging, comparison
+@cindex server
+@cindex network
+Contrary to most Instant Messenger (IM) systems, users usually don't
+connect to a central server.  Instead, users connect to a random server
+in a network, and the servers share information between them.
+
+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
+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 # 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
+network.  You might join the @code{#emacs} and the @code{#rcirc}
+channels, for example.  (Typically, channel names begin with a hash
+character.)
+
+Once you have joined a channel, anything you type will be broadcast to
+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:
+
+@example
+deego: fsbot rules!
+@end example
+
+@cindex nick completion
+@cindex completion of nicks
+@kindex TAB
+Since this is so common, you can use @key{TAB} to do nick completion.
+
+@node Getting started with rcirc, , Internet Relay Chat, Basics
+@section Getting started with rcirc
+@cindex getting started
+@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:
+
+@table @asis
+@cindex server, connecting
+@cindex Freenode network
+@item IRC server
+What server do you want to connect to? All the servers in a particular
+network are equivalent.  Some networks use a round-robin system where a
+single server redirects new connections to a random server in the
+network.  @code{irc.freenode.net} is such a server for the Freenode
+network.  Freenode provides the network ``for the Free and Open Source
+Software communities, for not-for-profit organisations and for related
+communities and organizations.''
+
+@cindex port, connecting
+@cindex 6667, default IRC port
+@item IRC port
+All network connections require a port.  Just as web servers and clients
+use port 80 per default, IRC uses port 6667 per default.  You rarely
+have to use a different port.
+
+@cindex nick, connecting
+@cindex changing nick
+@cindex name changes
+@item IRC nick
+@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
+in use, you might for example get assigned the nick @code{alex`}.
+
+@cindex channels, connecting
+@cindex initial channels
+@cindex startup channels
+@item Channels
+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.
+@end table
+
+@cindex server buffer
+When you have answered these questions, @code{rcirc} will create a server
+buffer, which will be named something like @code{*irc.freenode.net*},
+and a channel buffer for each of the channels you wanted to join.
+
+@kindex RET
+@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}.
+
+@kindex C-c C-c
+@cindex multiline messages
+@cindex messages, multiple lines
+@cindex pasting multiple lines
+@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,
+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
+
+This is the reference section of the manual.  It is not complete.  For
+complete listings of @code{rcirc} features, use Emacs built-in
+documentation.
+
+@menu
+* rcirc commands::
+* Useful IRC commands::
+* Configuration::
+@end menu
+
+@node rcirc commands, Useful IRC commands, Reference, Reference
+@section rcirc commands
+@cindex commands
+
+@kindex C-h m
+This is a list of commands that you may use in @code{rcirc}.  It is not
+complete.  For a complete listing, press @kbd{C-h m} in an @code{rcirc}
+buffer.
+
+In addition to using regular Emacs key bindings, you can call them by
+typing them into an @code{rcirc} buffer.
+
+@cindex call commands
+@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}:
+
+@example
+/join #emacs
+@end example
+
+@cindex / starts a command
+@cindex messages starting with a slash disappear
+@cindex disappearing messages if starting with a slash
+@cindex slash hides message
+This is why you cannot start a message with a slash.  You will have to
+precede the command with a space, or rewrite your message in order to
+send it to a channel.
+
+@cindex multiple words as parameters
+@cindex string delimiters
+@cindex quotes
+@cindex double-quotes
+Many commands take parameters.  IRC commands usually ignore string
+delimiters.  Neither quote nor double-quote have special meanings in
+IRC.
+
+@example
+/nick "alex schroeder"
+@end example
+
+This will try to change your nick to @code{"alex}.  Usually this will
+fail because the double quote character is not a legal character for
+nicks.
+
+@cindex case insensitive commands
+These commands are case insensitive.
+
+@cindex new command
+@cindex unknown command
+@cindex command unknown
+If a command isn't known by @code{rcirc}, it will simply be sent along to the
+server.  There is a list of some useful commands like that in the next
+section.
+
+@table @kbd
+@item C-c C-j
+@kindex C-c C-j
+@cindex /join
+@cindex join channels
+@cindex other channels
+@cindex rooms, joining
+@cindex discussion, joining
+This joins a channel such as @code{#rcirc} or @code{#emacs}.  On most
+networks, anybody can create new channels.  If you want to talk with
+some friends, for example, all you have to do is agree on a valid
+channel name and join that channel.  (Also @code{/join #emacs}.)
+
+@item C-c C-p
+@kindex C-c C-p
+@cindex /part
+@cindex part a channel
+@cindex leave a channel
+@cindex disconnect from a channel
+@cindex stop talking on a channel
+@cindex kill channel buffer
+This leaves the current channel.  You can optionally provide a reason
+for parting.  When you kill a channel buffer, you automatically part the
+corresponding channel.  (Also @code{/part you are too weird!}.)
+
+@item C-c C-r
+@kindex C-c C-r
+@cindex /nick
+@cindex change name
+@cindex nick changing
+@cindex rename yourself
+@cindex other name
+This changes your nick to some other name.  Your nick must be unique
+across the network.  Most networks don't allow too many nick changes in
+quick succession, and have restrictions on the valid characters in nick
+names.  (Also @code{/nick alex-test})
+
+@item C-c C-w
+@kindex C-c C-w
+@cindex /whois
+@cindex who are these people
+@cindex identifying people
+@cindex channels other people are on
+@cindex what channels people are on
+Gives you some basic information about a nick.  This often includes what
+other channels people are on.  (Also @code{/whois fsbot}.)
+
+@item C-c C-q
+@kindex C-c C-q
+@cindex /query
+@cindex starting a private conversation
+@cindex one-to-one conversation
+@cindex talk privately
+@cindex private conversation
+@cindex contact one person only
+@cindex query a person
+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
+@kindex C-c RET
+@cindex /msg
+@cindex single message
+@cindex message sending
+This sends a single message to a nick.  Like with @kbd{C-c C-q}, a new
+buffer is created, where the response from the other party will show
+up.  (Also @code{/msg nickserv identify secret}.)
+
+@item C-c C-x
+@kindex C-c C-x
+@cindex /quit
+@cindex quit
+@cindex disconnect
+@cindex kill connection
+@cindex connection end
+@cindex part all channels
+@cindex end connection
+@cindex server buffer killing
+@cindex reason for quitting
+This disconnects from the server and parts all channels.  You can
+optionally provide a reason for quitting.  When you kill the server
+buffer, you automatically quit the server and part all channels.  (Also
+@code{/quit ZZZzzz...}.)
+@end table
+
+Some commands may not have a key binding, but only be available as typed
+commands, such as:
+
+@table @code
+@item /ignore
+@cindex /ignore
+@cindex ignoring other people
+@cindex trolls, ignoring
+@cindex hide some posts
+@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
+ignore command is often the only way to deal with some of the more
+obnoxious fellows online.  Example: @code{/ignore xah}.
+@end table
+
+@node Useful IRC commands, Configuration, rcirc commands, Reference
+@section Useful IRC commands
+@cindex irc commands
+@cindex commands
+
+As mentioned, if a command isn't known by @code{rcirc}, it will simply be sent
+along to the server.  Some such commands are available on nearly all IRC
+servers, such as:
+
+@table @code
+@item /away
+@cindex /away
+@cindex away status
+@cindex pause status
+@cindex unavailable status
+@cindex set away status
+This sets your status as ``being away'' if you provide a reason, or sets
+your status as ``being back'' if you do not.  People can use the
+@kbd{C-c C-w} command to check your status.  Example: @code{/away food}.
+@end table
+
+@cindex irc resources
+@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.
+
+@node Configuration, , Useful IRC commands, Reference
+@section Configuration
+@cindex configuration
+
+These are some variables you can change to configure @code{rcirc} to your
+liking.
+
+@table @code
+@item rcirc-server
+@vindex rcirc-server
+the default server to connect to.
+
+@item rcirc-port
+@vindex rcirc-port
+the default port to connect to.
+
+@item rcirc-nick
+@vindex rcirc-nick
+the default nick to use.
+@end table
+
+@example
+(setq rcirc-server "irc.mozilla.org"
+      rcirc-port 6666
+      rcirc-nick "alx")
+@end example
+
+@vindex rcirc-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.
+
+@example
+(setq rcirc-user-full-name "Curious Minds Want To Know")
+@end example
+
+@vindex rcirc-startup-channels-alist
+@cindex channels, configuration
+@cindex initial channels, configuration
+@cindex startup channels, configuration
+@code{rcirc-startup-channels-alist} is the alist of channels to join
+when connecting to a particular network.  An alist is a list of lists.
+Each sublist starts with a regular expression that is compared to the
+server address you're connecting to.  The remaining sublist items are
+the channels to join.
+
+@example
+(setq rcirc-startup-channels-alist
+      '(("\\.freenode\\.net$" "#emacs" "#rcirc" "#wiki")))
+@end example
+
+Note the subtle problem, here --- IRC clients connect to servers, and
+there is no way of knowing which servers belong to a particular network.
+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.
+
+@node Hacking and Tweaking, Key Index, Reference, Top
+@chapter Hacking and Tweaking
+@cindex hacking and tweaking
+
+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::
+@end menu
+
+@node Skipping /away messages using handlers, Using fly spell mode, Hacking and Tweaking, Hacking and Tweaking
+@section Skipping @code{/away} messages using handlers
+@cindex /away messages
+
+@cindex handlers
+@cindex status codes
+The IRC protocol specifies how certain events are signalled 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}.
+
+Here's how to stop @code{rcirc} from printing @code{/away} messages.
+Since @code{rcirc} doesn't define a 301 handler, you don't need to
+require @code{rcirc} before defining the handler:
+
+@example
+(defun rcirc-handler-301 (process cmd sender args)
+  "/away message handler.")
+@end example
+
+@node Using fly spell mode, Scrolling conservatively, Skipping /away messages using handlers, Hacking and Tweaking
+@section Using fly spell mode
+@cindex fly spell
+@cindex spelling
+@cindex spell-checking as you type
+@cindex automatic spelling
+@vindex rcirc-mode-hook
+
+The following code activates Fly Spell Mode
+for @code{rcirc} buffers:
+
+@example
+(add-hook 'rcirc-mode-hook (lambda ()
+                             (flyspell-mode 1)))
+@end example
+
+@xref{Spelling, , Flyspell mode, emacs, The GNU Emacs Manual},
+for details.
+
+@node Scrolling conservatively, Changing the time stamp format, Using fly spell mode, Hacking and Tweaking
+@section Scrolling conservatively
+@cindex input line
+@cindex scrolling
+@vindex scroll-conservatively
+@vindex rcirc-mode-hook
+
+IRC buffers are constantly growing.  If you want to see as much as
+possible at all times, you would want the prompt at the bottom of the
+window when possible.  The following snippet uses a local value for
+@code{scroll-conservatively} to achieve this:
+
+@example
+(add-hook 'rcirc-mode-hook
+          (lambda ()
+            (set (make-local-variable 'scroll-conservatively)
+                 8192)))
+@end example
+
+@xref{Scrolling, , Scrolling convervatively, emacs, The GNU Emacs
+Manual}, for details.
+
+@node Changing the time stamp format, Defining a new command, Scrolling conservatively, Hacking and Tweaking
+@section Changing the time stamp format
+@cindex time stamp
+@cindex date time
+@cindex format time stamp
+@vindex rcirc-time-format
+
+@code{rcirc-time-format} is the format used for the time stamp.  Here's
+how to include the date in the time stamp:
+
+@example
+(setq rcirc-time-format "%Y-%m-%d %H:%M ")
+@end example
+
+@node Defining a new command, Reconnecting after you have lost the connection, Changing the time stamp format, Hacking and Tweaking
+@section Defining a new command
+@cindex defining commands
+@cindex commands, defining
+@cindex new commands, defining
+
+Here's a simple new command, @code{/sv}.  With it, you can boast about
+your IRC client.  It shows how you can use @code{defun-rcirc-command} to
+define new commands.
+
+We're waiting for the definition of this command until @code{rcirc} is loaded
+because @code{defun-rcirc-command} is not yet available, and without
+@code{rcirc} loaded, the command wouldn't do us much good anyway.
+
+@smallexample
+(eval-after-load 'rcirc
+  '(defun-rcirc-command sv (arg)
+     "Boast about rcirc."
+     (interactive "i")
+     (rcirc-send-message process target
+                         (concat "I use " rcirc-id-string))))
+@end smallexample
+
+@node Reconnecting after you have lost the connection, , Defining a new command, Hacking and Tweaking
+@section Reconnecting after you have lost the connection
+@cindex reconnecting
+@cindex disconnecting servers, reconnecting
+
+If you're chatting from a laptop, then you might be familiar with this
+problem: When your laptop falls asleep and wakes up later, your IRC
+client doesn't realise that it has been disconnected.  It takes several
+minutes until the client decides that the connection has in fact been
+lost.  The simple solution is to use @kbd{M-x rcirc}.  The problem is
+that this opens an @emph{additional} connection, so you'll have two
+copies of every channel buffer --- one dead and one live.
+
+The real answer, therefore, is a @code{/reconnect} command:
+
+@smallexample
+(eval-after-load 'rcirc
+  '(defun-rcirc-command reconnect (arg)
+     "Reconnect the server process."
+     (interactive "i")
+     (unless process
+       (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))
+            channels query-buffers)
+       (dolist (buf (buffer-list))
+         (with-current-buffer buf
+           (when (eq process rcirc-process)
+             (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)))))))
+@end smallexample
+
+@node Key Index, Variable Index, Hacking and Tweaking, Top
+@unnumbered Key Index
+@printindex ky
+
+@node Variable Index, Index, Key Index, Top
+@unnumbered Variable Index
+@printindex vr
+
+@node Index, , Variable Index, Top
+@unnumbered Index
+@printindex cp
+
+@bye