@syncodeindex fn cp
@copying
-This manual is for ERC version 5.1.4.
+This manual is for ERC version 5.2.
-Copyright @copyright{} 2005, 2006 Free Software Foundation, Inc.
+Copyright @copyright{} 2005, 2006, 2007 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, Front-Cover texts, or Back-Cover Texts.
+Invariant Sections, Front-Cover texts, or Back-Cover Texts. A copy of
+the license is included in the section entitled ``GNU Free
+Documentation License'' in the Emacs manual.
+
+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.
+
+All Emacs Lisp code contained in this document may be used, distributed,
+and modified without restriction.
@end quotation
@end copying
* Advanced Usage:: Cool ways of using ERC.
* Getting Help and Reporting Bugs::
* History:: The history of ERC.
+* GNU Free Documentation License:: The license for this documentation.
* Concept Index:: Search for terms.
@detailmenu
* Releases:: Released versions of ERC.
* Development:: Latest unreleased development changes.
+Getting Started
+
+* Sample Session:: Example of connecting to the #emacs channel
+* Special Features:: Differences from standalone IRC clients
+
Advanced Usage
* Connecting:: Ways of connecting to an IRC server.
-* Options:: Options that are available for ERC.
-* Tips and Tricks:: Ways of enhancing your ERC experience.
* Sample Configuration:: An example configuration file.
+* Options:: Options that are available for ERC.
@end detailmenu
@end menu
* Development:: Latest unreleased development changes.
@end menu
-These sections may be skipped if you are using the version of ERC that
-comes with Emacs.
+Note that some ERC files are not included with Emacs due to copyright or
+dependency issues. If desired, they may be found at the following
+locations, or from your local GNU mirror.
+
+@itemize @bullet
+@item @uref{http://ftp.gnu.org/gnu/erc/erc-5.2-extras.tar.gz}
+@item @uref{http://ftp.gnu.org/gnu/erc/erc-5.2-extras.zip}
+@end itemize
+
+The rest of this chapter may be skipped if you are using the version of
+ERC that comes with Emacs.
@node Releases, Development, Obtaining ERC, Obtaining ERC
@comment node-name, next, previous, up
@cindex releases, from source
Alternatively, you can download the latest release from
-@uref{http://ftp.gnu.org/gnu/erc}.
+@uref{http://ftp.gnu.org/gnu/erc}, or your local GNU mirror.
@node Development, , Releases, Obtaining ERC
@comment node-name, next, previous, up
@end enumerate
-If you are new to Arch and want to learn more about developing with it,
-you might find this tutorial helpful:
-@uref{http://www.mwolson.org/projects/ArchTutorial.html}.
+If you are new to Arch and want to learn more about developing ERC with
+it, visit @uref{http://emacswiki.org/cgi-bin/wiki/ErcDevelopment} for
+full instructions.
@subheading Development snapshots
@chapter Getting Started
@cindex settings
-@c PRE5_2: Mention .ercrc.el
-
To use ERC, add the directory containing its files to your
@code{load-path} variable, in your @file{.emacs} file. Then, load ERC
itself. An example follows.
(require 'erc)
@end lisp
-Once ERC is loaded, the command @kbd{M-x erc-select} will start ERC and
+Once ERC is loaded, the command @kbd{M-x erc} will start ERC and
prompt for the server to connect to.
-@c PRE5_2: Sample session, including:
-@c - connect to Freenode
-@c - /join #emacs
-@c - see messages flying past, point out topic lines, messages, channel
-@c members
-@c - identifying your nick with NickServ (most IRC servers have this)
-@c - talking to the channel
-@c - open a /query buffer to talk to someone (must identify first in
-@c FreeNode)
+If you want to place ERC settings in their own file, you can place them
+in @file{~/.emacs.d/.ercrc.el}, creating it if necessary.
+
+If you would rather use the Customize interface to change how ERC works,
+do @kbd{M-x customize-group RET erc RET}. In particular, ERC comes with
+lots of modules that may be enabled or disabled; to select which ones
+you want, do @kbd{M-x customize-variable RET erc-modules RET}.
+
+@menu
+* Sample Session:: Example of connecting to the #emacs channel
+* Special Features:: Differences from standalone IRC clients
+@end menu
+
+@node Sample Session, Special Features, Getting Started, Getting Started
+@comment node-name, next, previous, up
+@section Sample Session
+
+This is an example ERC session which shows how to connect to the #emacs
+channel on Freenode. Another IRC channel on Freenode that may be of
+interest is #erc, which is a channel where ERC users and developers hang
+out.
+
+@itemize @bullet
+
+@item Connect to Freenode
+
+Run @kbd{M-x erc}. Use ``irc.freenode.net'' as the IRC server, ``6667''
+as the port, and choose a nickname.
+
+@item Get used to the interface
+
+Switch to the ``irc.freenode.net:6667'' buffer, if you're not already
+there. You will see first some messages about checking for ident, and
+then a bunch of other messages that describe the current IRC server.
+
+@item Join the #emacs channel
+
+In that buffer, type ``/join SPC #emacs'' and hit @kbd{RET}. Depending
+on how you've set up ERC, either a new buffer for ``#emacs'' will be
+displayed, or a new buffer called ``#emacs'' will be created in the
+background. If the latter, switch to the ``#emacs'' buffer. You will
+see the channel topic and a list of the people who are currently on the
+channel.
+
+@item Register your nickname with Freenode
+
+If you would like to be able to talk with people privately on the
+Freenode network, you will have to ``register'' your nickname. To do
+so, switch to the ``irc.freenode.net:6667'' buffer and type ``/msg
+NickServ register <password>'', replacing ``<password>'' with your
+desired password. It should tell you that the operation was successful.
+
+@item Talk to people in the channel
+
+If you switch back to the ``#emacs'' buffer, you can type a message, and
+everyone on the channel will see it.
+
+@item Open a query buffer to talk to someone
+
+If you want to talk with someone in private (this should usually not be
+done for technical help, only for personal questions), type ``/query
+<nick>'', replacing ``<nick>'' with the nickname of the person you would
+like to talk to. Depending on how ERC is set up, you will either see a
+new buffer with the name of the person, or such a buffer will be created
+in the background and you will have to switch to it. Begin typing
+messages, and you will be able to have a conversation.
+
+Note that if the other person is not registered, you will not be able to
+talk with them.
+
+@end itemize
+
+@node Special Features, , Sample Session, Getting Started
+@comment node-name, next, previous, up
+@section Special Features
+
+ERC has some features that distinguish it from some IRC clients.
+
+@itemize @bullet
+
+@item multiple channels and multiple servers
+
+Every channel is put in a separate buffer. Several IRC servers may be
+connected to at the same time.
+
+@cindex query buffers
+@item private message separation
+
+Private conversations are treated as channels, and are put into separate
+buffers in Emacs. We call these ``query buffers''.
+
+@item highlighting
+
+Some occurences of words can be highlighted, which makes it easier to
+track different kinds of conversations.
+
+@item notification
+
+ERC can notify you that certain users are online.
+
+@item channel tracking
+
+Channels can be hidden and conversation continue in the background. You
+are notified when something is said in such a channel that is not
+currently visible. This makes it easy to get Real Work done while still
+maintaining an IRC presence.
+
+@item nick completion
+
+ERC can complete words upon hitting @kbd{TAB}, which eases the writing
+of nicknames in messages.
+
+@cindex history ring
+@item history
+
+Past actions are kept in history rings for future use. To navigate a
+history ring, hit @kbd{M-p} to go backwards and @kbd{M-n} to go
+forwards.
+
+@item multiple languages
+
+Different channels and servers may have different language encodings.
+
+In addition, it is possible to translate the messages that ERC uses into
+multiple languages. Please contact the developers of ERC at
+@email{erc-discuss@@gnu.org} if you are interested in helping with the
+translation effort.
+
+@item user scripting
+
+Users can load scripts (e.g. auto greeting scripts) when ERC starts up.
+
+It is also possible to make custom IRC commands, if you know a little
+Emacs Lisp. Just make an Emacs Lisp function and call it
+@code{erc-cmd-NEWCOMMAND}, where @code{NEWCOMMAND} is the name of the
+new command in capital letters.
+
+@item auto reconnect
+
+If the connection goes away at some point, ERC will try to reconnect
+automatically. If it fails to reconnect, and you want to try to
+manually reestablish the connection at some later point, switch to an
+ERC buffer and run the @code{/RECONNECT} command.
+
+@end itemize
@node Keystroke Summary, Modules, Getting Started, Top
@item button
Buttonize URLs, nicknames, and other text
+@cindex modules, capab-identify
+@item capab-identify
+Mark unidentified users on freenode and other servers supporting CAPAB.
+
@cindex modules, completion
-@item pcomplete
+@cindex modules, pcomplete
+@item completion (aka pcomplete)
Complete nicknames and commands (programmable)
@cindex modules, fill
Wrap long lines
@cindex modules, hecomplete
-@item completion
+@item hecomplete
Complete nicknames and commands (old). This is the old module---you
might prefer the ``completion'' module instead.
@item irccontrols
Highlight or remove IRC control characters
-@cindex modules, list
-@item list
-List channels nicely in a separate buffer
-
@cindex modules, log
@item log
Save buffers in logs
@item match
Highlight pals, fools, and other keywords
+@cindex modules, menu
+@item menu
+Display a menu in ERC buffers
+
@cindex modules, netsplit
@item netsplit
Detect netsplits
@end table
-@c PRE5_2: Document every option of every module in its own subnode
+@c PRE5_3: Document every option of every module in its own subnode
@node Advanced Usage, Getting Help and Reporting Bugs, Modules, Top
@menu
* Connecting:: Ways of connecting to an IRC server.
-* Options:: Options that are available for ERC.
-* Tips and Tricks:: Ways of enhancing your ERC experience.
* Sample Configuration:: An example configuration file.
+* Options:: Options that are available for ERC.
@end menu
-@node Connecting, Options, Advanced Usage, Advanced Usage
+@node Connecting, Sample Configuration, Advanced Usage, Advanced Usage
@comment node-name, next, previous, up
@section Connecting to an IRC Server
@cindex connecting
-The easiest way to connect to an IRC server is to call
-@kbd{M-x erc-select}. If you want to assign this function to a
-keystroke, the following will help you figure out its parameters.
+The easiest way to connect to an IRC server is to call @kbd{M-x erc}.
+If you want to assign this function to a keystroke, the following will
+help you figure out its parameters.
-@defun erc-select
+@defun erc
Select connection parameters and run ERC.
Non-interactively, it takes the following keyword arguments.
parameters.
@example
-(erc-select :server "irc.freenode.net" :full-name "Harry S Truman")
+(erc :server "irc.freenode.net" :full-name "Harry S Truman")
@end example
@end defun
This can be either a string or a function to call.
@end defopt
-@node Options, Tips and Tricks, Connecting, Advanced Usage
+@node Sample Configuration, Options, Connecting, Advanced Usage
@comment node-name, next, previous, up
-@section Options
-@cindex options
+@section Sample Configuration
+@cindex configuration, sample
-@c PRE5_2: (Node) Document every ERC option (module options go in
-@c previous chapter)
+Here is an example of configuration settings for ERC. This can go into
+your Emacs configuration file. Everything after the @code{(require
+'erc)} command can optionally go into @file{~/.emacs.d/.ercrc.el}.
-This section has not yet been written.
+@lisp
+;;; Sample ERC configuration
-@node Tips and Tricks, Sample Configuration, Options, Advanced Usage
-@comment node-name, next, previous, up
-@section Tips and Tricks
-@cindex tips and tricks
+;; Add the ERC directory to load path -- you don't need this if you are
+;; using the version of ERC that comes with Emacs
+(add-to-list 'load-path "~/elisp/erc")
-@c PRE5_2: (Node) Tips and tricks
+;; Load ERC
+(require 'erc)
-This section has not yet been written.
+;; Load authentication info from an external source. Put sensitive
+;; passwords and the like in here.
+(load "~/.emacs.d/.erc-auth")
+
+;; This is an example of how to make a new command. Type "/uptime" to
+;; use it.
+(defun erc-cmd-UPTIME (&rest ignore)
+ "Display the uptime of the system, as well as some load-related
+stuff, to the current ERC buffer."
+ (let ((uname-output
+ (replace-regexp-in-string
+ ", load average: " "] @{Load average@} ["
+ ;; Collapse spaces, remove
+ (replace-regexp-in-string
+ " +" " "
+ ;; Remove beginning and trailing whitespace
+ (replace-regexp-in-string
+ "^ +\\|[ \n]+$" ""
+ (shell-command-to-string "uptime"))))))
+ (erc-send-message
+ (concat "@{Uptime@} [" uname-output "]"))))
+
+;; This causes ERC to connect to the Freenode network upon hitting
+;; C-c e f. Replace MYNICK with your IRC nick.
+(global-set-key "\C-cef" (lambda () (interactive)
+ (erc :server "irc.freenode.net" :port "6667"
+ :nick "MYNICK")))
+
+;; This causes ERC to connect to the IRC server on your own machine (if
+;; you have one) upon hitting C-c e b. Replace MYNICK with your IRC
+;; nick. Often, people like to run bitlbee (http://bitlbee.org/) as an
+;; AIM/Jabber/MSN to IRC gateway, so that they can use ERC to chat with
+;; people on those networks.
+(global-set-key "\C-ceb" (lambda () (interactive)
+ (erc :server "localhost" :port "6667"
+ :nick "MYNICK")))
+
+;; Make C-c RET (or C-c C-RET) send messages instead of RET. This has
+;; been commented out to avoid confusing new users.
+;; (define-key erc-mode-map (kbd "RET") nil)
+;; (define-key erc-mode-map (kbd "C-c RET") 'erc-send-current-line)
+;; (define-key erc-mode-map (kbd "C-c C-RET") 'erc-send-current-line)
+
+;;; Options
+
+;; Join the #emacs and #erc channels whenever connecting to Freenode.
+(setq erc-autojoin-channels-alist '(("freenode.net" "#emacs" "#erc")))
+
+;; Interpret mIRC-style color commands in IRC chats
+(setq erc-interpret-mirc-color t)
+
+;; The following are commented out by default, but users of other
+;; non-Emacs IRC clients might find them useful.
+;; Kill buffers for channels after /part
+;; (setq erc-kill-buffer-on-part t)
+;; Kill buffers for private queries after quitting the server
+;; (setq erc-kill-queries-on-quit t)
+;; Kill buffers for server messages after quitting the server
+;; (setq erc-kill-server-buffer-on-quit t)
+@end lisp
-@node Sample Configuration, , Tips and Tricks, Advanced Usage
+@node Options, , Sample Configuration, Advanced Usage
@comment node-name, next, previous, up
-@section Sample Configuration
-@cindex configuration, sample
+@section Options
+@cindex options
-@c PRE5_2: (Node) Sample configs
+@c PRE5_3: (Node) Document every ERC option (module options go in
+@c previous chapter)
-This section has not yet been written.
+This section has not yet been written. For now, the easiest way to
+check out the available option for ERC is to do
+@kbd{M-x customize-group erc RET}.
@node Getting Help and Reporting Bugs, History, Advanced Usage, Top
@end itemize
-@node History, Concept Index, Getting Help and Reporting Bugs, Top
+@node History, GNU Free Documentation License, Getting Help and Reporting Bugs, Top
@comment node-name, next, previous, up
@chapter History
@cindex history, of ERC
@end itemize
-@node Concept Index, , History, Top
+@node GNU Free Documentation License, Concept Index, History, Top
+@appendix GNU Free Documentation License
+@include doclicense.texi
+
+@node Concept Index, , GNU Free Documentation License, Top
@comment node-name, next, previous, up
@unnumbered Index
HCoop / bpt / emacs.git / blobdiff