@c %**end of header
@copying
-Copyright @copyright{} 2006, 2007 Free Software Foundation, Inc.
+Copyright @copyright{} 2006--2013 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
+under the terms of the GNU Free Documentation License, Version 1.3 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.
+included in the section entitled ``GNU Free Documentation License''.
-(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.
+(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
+modify this GNU manual.''
@end quotation
@end copying
-@dircategory Emacs
+@dircategory Emacs network features
@direntry
-* Rcirc: (rcirc). Internet Relay Chat (IRC) client.
+* Rcirc: (rcirc). Internet Relay Chat (IRC) client.
@end direntry
@titlepage
@insertcopying
@end titlepage
+@contents
+
@ifnottex
-@node Top, Basics, (dir), (dir)
+@node Top
@top rcirc Manual
-@end ifnottex
@code{rcirc} is an Emacs IRC client.
topic channels which are collections of many users, or privately, with
just one other user.
+@insertcopying
+
+@end ifnottex
+
@menu
* Basics::
* Reference::
+* Fighting Information Overload::
* Hacking and Tweaking::
* GNU Free Documentation License::
* Key Index::
* Useful IRC commands::
* Configuration::
+Fighting Information Overload
+
+* Channels::
+* People::
+* Keywords::
+* Notices::
+
Hacking and Tweaking
* Skipping /away messages using handlers::
@end detailmenu
@end menu
-@node Basics, Reference, Top, Top
+@node Basics
@chapter Basics
This chapter contains a brief introduction to IRC (Internet Relay Chat),
* Getting started with rcirc::
@end menu
-@node Internet Relay Chat, Getting started with rcirc, Basics, Basics
+@node Internet Relay Chat
@section Internet Relay Chat
@cindex internet relay chat
@cindex irc
@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.
+connect to a central server. Instead, users connect to a random
+server in a network, and servers relay messages from one to the next.
Here's a typical example:
@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
+@node Getting started with rcirc
@section Getting started with rcirc
@cindex getting started
@cindex connecting to a server
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
+Use @kbd{C-u M-x irc} if you don't want to use the defaults, e.g., 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
@cindex Freenode network
-@item IRC server
+@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
+Software communities, for not-for-profit organizations and for related
communities and organizations.''
@cindex port, connecting
@cindex 6667, default IRC port
-@item 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
+@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
@cindex channels, connecting
@cindex initial channels
@cindex startup channels
-@item Channels
+@item IRC 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
@kindex RET
@cindex talking
@cindex communicating
-To talk in a channel, just type in what you want to say in a channel
+To talk in a channel, just type what you want to say in a channel
buffer, and press @key{RET}.
@kindex C-c C-c
though. Generally, IRC users don't like people pasting more than around
four lines of code, so use with care.
-@node Reference, Hacking and Tweaking, Basics, Top
+@comment This section copied from the Channels section.
+@comment All index markers should point to the original!
+Once you are connected to multiple channels, or once you've turned you
+attention to other buffers in Emacs, you probably want to be notified
+of any activity in channels not currently visible. All you need to do
+is switch channel tracking 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
+
+Use @kbd{C-c C-@key{SPC}} to switch to these buffers.
+
+@node Reference
@chapter Reference
@cindex reference
* Configuration::
@end menu
-@node rcirc commands, Useful IRC commands, Reference, Reference
+@node rcirc commands
@section rcirc commands
@cindex rcirc commands
@cindex commands
@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
+fail because the double quote character is not a valid character for
nicks.
@cindex case insensitive commands
@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
+@node Useful IRC commands
@section Useful IRC commands
@cindex irc commands
@cindex commands
@uref{http://www.irchelp.org/, the Internet Relay Chat (IRC) help
archive}.
-@node Configuration, , Useful IRC commands, Reference
+@node Configuration
@section Configuration
@cindex configuring rcirc
liking.
@table @code
-@item rcirc-default-server
-@vindex rcirc-default-server
-the default server to connect to.
+@item rcirc-server-alist
+@vindex rcirc-server-alist
+@cindex channels, configuration
+@cindex initial channels, configuration
+@cindex startup channels, configuration
+@cindex servers, configuration
+@cindex initial servers, configuration
+@cindex startup servers, configuration
+This variable contains an alist of servers to connect to by default
+and the keywords parameters to use. The keyword parameters are
+optional. If you don't provide any, the defaults as documented below
+will be used.
-@item rcirc-default-port
-@vindex rcirc-default-port
-the default port to connect to.
+The most important parameter is the @code{:channels} parameter. It
+controls which channels you will join by default as soon as you are
+connected to the server.
+
+Here's an example of how to set it:
+
+@example
+(add-to-list 'rcirc-server-alist
+ '("otherworlders.org"
+ :channels ("#FUDGE" "#game-design")))
+@end example
+
+By default you will be connected to the @code{rcirc} support channel:
+@code{#rcirc} on @code{irc.freenode.net}.
+
+@table @code
+@item :nick
+This overrides @code{rcirc-default-nick}.
+
+@item :port
+This overrides @code{rcirc-default-port}.
+
+@item :user-name
+This overrides @code{rcirc-default-user-name}.
+
+@item :full-name
+This overrides @code{rcirc-default-full-name}.
+
+@item :channels
+This describes which channels to join when connecting to the server.
+If absent, no channels will be connected to automatically.
+
+@end table
@item rcirc-default-nick
@vindex rcirc-default-nick
-the default nick to use.
-@end table
+This variable is used for the default nick. It defaults to the login
+name returned by @code{user-login-name}.
@example
-(setq rcirc-default-server "irc.mozilla.org"
- rcirc-default-port 6666
- rcirc-default-nick "alx")
+(setq rcirc-default-nick "kensanata")
@end example
-@vindex rcirc-default-user-full-name
+@item rcirc-default-port
+@vindex rcirc-default-port
+@cindex port
+This variable contains the default port to connect to. It is 6667 by
+default and rarely needs changing.
+
+@item rcirc-default-user-name
+@vindex rcirc-default-user-name
+@cindex user name
+This variable contains the default user name to report to the server.
+It defaults to the login name returned by @code{user-login-name}, just
+like @code{rcirc-default-nick}.
+
+@item rcirc-default-full-name
+@vindex rcirc-default-full-name
@cindex full name
@cindex real name
@cindex surname
-@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-default-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.
+This variable is used to set your ``real name'' on IRC@. It defaults
+to the name returned by @code{user-full-name}. If you want to hide
+your full name, you might want to set it to some pseudonym.
@example
-(setq rcirc-startup-channels-alist
- '(("\\.freenode\\.net$" "#emacs" "#rcirc" "#wiki")))
+(setq rcirc-default-full-name "Curious Minds Want To Know")
@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.
-
+@item rcirc-authinfo
@vindex rcirc-authinfo
-@cindex authentification
+@cindex authentication
@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.
+This variable 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:
@table @code
@item nickserv
-@cindex nickserv authentification
+@cindex nickserv authentication
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
details. (Using @code{/msg nickserv help}, for example.)
@item chanserv
-@cindex chanserv authentification
+@cindex chanserv authentication
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
(Using @code{/msg chanserv help}, for example.)
@item bitlbee
-@cindex bitlbee authentification
+@cindex bitlbee authentication
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.
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.
+provide for the bitlbee authentication 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
+
@end table
+@node Fighting Information Overload
+@chapter Fighting Information Overload
+@cindex information overload
+
+This is the section of the manual that caters to the busy person
+online. There are support channels with several hundred people in
+them. Trying to follow a conversation in these channels can be a
+daunting task. This chapters tells you how @code{rcirc} can help.
+
+@menu
+* Channels::
+* People::
+* Keywords::
+* Notices::
+@end menu
+
+@node Channels
+@section Channels
+@cindex channels
+@cindex modeline
+
+@comment This section copied to the Getting started with rcirc section
@kindex C-c C-SPC
@vindex rcirc-track-minor-mode
@cindex switching channels
(rcirc-track-minor-mode 1)))
@end example
-@node Hacking and Tweaking, GNU Free Documentation License, Reference, Top
+@cindex busy channels
+If you've joined a very active support channel, tracking activity is
+no longer useful. The channel will be always active. Switching to
+active channels using @kbd{C-c C-@key{SPC}} no longer works as
+expected.
+
+@kindex C-c C-l
+@cindex low priority channels
+The solution is to mark this channel as a low priority channel.
+Use @kbd{C-c C-l} to make the current channel a low-priority channel.
+Low priority channels have the modeline indicator ``LowPri''.
+@kbd{C-c C-@key{SPC}} will not switch to low priority channels unless
+you use the @kbd{C-u} prefix.
+
+@kindex C-c TAB
+@cindex ignored channels
+If you prefer a channel to never show up in the modeline, then you
+have to ignore it. Use @kbd{C-c @key{TAB}} to ignore the current
+channel.
+
+@node People
+@section People
+@cindex people, how to ignore
+@cindex nicks, how to ignore
+@cindex friends
+@cindex buddies
+@cindex trolls
+
+The most important command available to the discerning IRC user is
+@code{/ignore}. It's the big equalizer online: If people aggravate
+you, just ignore them.
+
+This is of course a crude all-or-nothing solution. Fear not,
+@code{rcirc} offers alternatives: You can ``brighten'' your buddies
+and ``dim'' certain other nicks that you don't want to ignore
+altogether.
+
+@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 rudybot}.
+
+@item /bright
+@cindex /bright
+@cindex highlight other people
+@cindex friends, highlight
+@cindex buddies, highlight
+@cindex nicks, highlight
+@cindex brighten nicks
+This command toggles the bright status of a nick, if you provide one.
+If you don't provide a nick, the command lists all the ``brightened''
+nicks. All messages by brightened nicks are---you guessed
+it---brightened. Use this for your friends. Example: @code{/bright
+rcy}.
+
+@item /dim
+@cindex /dim
+@cindex soft-ignore other people
+@cindex obnoxious people online
+@cindex rabble online
+This command toggles the dim status of a nick, if you provide one. If
+you don't provide a nick, the command lists all the ``dimmed'' nicks.
+All messages by dimmed nicks are---you guessed it---dimmed. Use this
+for boring people and bots. If you are tracking channel activity,
+messages by dimmed nicks will not register as activity. Example:
+@code{/dim fsbot}.
+@end table
+
+
+@node Keywords
+@section Keywords
+@cindex keywords
+
+On a busy channel, you might want to ignore all activity (using
+@kbd{C-c @key{TAB}}) and just watch for certain keywords. The
+following command allows you to highlight certain keywords:
+
+@table @code
+@item /keyword
+@cindex /keyword
+This command toggles the highlighting of a keyword, if you provide
+one. If you don't provide a keyword, the current keywords are
+listed. Example: @code{/keyword manual}.
+@end table
+
+@node Notices
+@section Notices
+@cindex part notices, how to omit
+@cindex join notices, how to omit
+@cindex quit notices, how to omit
+@cindex nick notices, how to omit
+
+@kindex C-c C-o
+@cindex low priority channels
+In busy channels you might not be interested in all the joining,
+parting, quitting, and renaming that goes on. You can omit those
+notices using @kbd{C-c C-o}.
+
+@vindex rcirc-omit-responses
+@cindex away notices, how to omit
+You can control which notices get omitted via the
+@code{rcirc-omit-responses} variable. Here's an example of how to
+omit away messages:
+
+@example
+(setq rcirc-omit-responses '("JOIN" "PART" "QUIT" "NICK" "AWAY"))
+@end example
+
+@vindex rcirc-omit-threshold
+Notice that these messages will not be omitted if the nick in question
+has recently been active. After all, you don't want to continue a
+conversation with somebody who just left. That's why @code{rcirc}
+checks recent lines in the buffer to figure out if a nick has been
+active and only omits a message if the nick has not been active. The
+window @code{rcirc} considers is controlled by the
+@code{rcirc-omit-threshold} variable.
+
+@node Hacking and Tweaking
@chapter Hacking and Tweaking
@cindex hacking and tweaking
* 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
+@node Skipping /away messages using handlers
@section Skipping @code{/away} messages using handlers
@cindex /away messages
"/away message handler.")
@end example
-@node Using fly spell mode, Scrolling conservatively, Skipping /away messages using handlers, Hacking and Tweaking
+@node Using fly spell mode
@section Using fly spell mode
@cindex fly spell
@cindex spelling
@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
+@node Scrolling conservatively
@section Scrolling conservatively
@cindex input line
@cindex scrolling
@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
+@node Changing the time stamp format
@section Changing the time stamp format
@cindex time stamp
@cindex date time
(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
+@node Defining a new command
@section Defining a new command
@cindex defining commands
@cindex commands, defining
(concat "I use " rcirc-id-string))))
@end smallexample
-@node Reconnecting after you have lost the connection, , Defining a new command, Hacking and Tweaking
+@node Reconnecting after you have lost the connection
@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
+client doesn't realize 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.
+copies of every channel buffer, one dead and one live.
The real answer, therefore, is a @code{/reconnect} command:
(delete-process process)
(rcirc-connect server port nick
rcirc-default-user-name
- rcirc-default-user-full-name
+ rcirc-default-full-name
channels))))
@end smallexample
-@node GNU Free Documentation License, Key Index, Hacking and Tweaking, Top
+@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include doclicense.texi
-@node Key Index, Variable Index, GNU Free Documentation License, Top
+@node Key Index
@unnumbered Key Index
@printindex ky
-@node Variable Index, Index, Key Index, Top
+@node Variable Index
@unnumbered Variable Index
@printindex vr
-@node Index, , Variable Index, Top
+@node Index
@unnumbered Index
@printindex cp
@bye
-
-@ignore
- arch-tag: 2589e562-3843-4ffc-8c2f-477cbad57c01
-@end ignore
HCoop / bpt / emacs.git / blobdiff