@setfilename ../../info/erc
@settitle ERC Manual
@syncodeindex fn cp
+@include emacsver.texi
@c %**end of header
@copying
-This manual is for ERC version 5.3.
+This manual is for ERC as distributed with Emacs @value{EMACSVER}.
-Copyright @copyright{} 2005-2012
-Free Software Foundation, Inc.
+Copyright @copyright{} 2005--2013 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
is included in the section entitled ``GNU Free Documentation License''.
(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
-modify this GNU manual. Buying copies from the FSF supports it in
-developing GNU and promoting software freedom.''
+modify this GNU manual.''
All Emacs Lisp code contained in this document may be used, distributed,
and modified without restriction.
@contents
@ifnottex
-@node Top, Introduction, (dir), (dir)
-@comment node-name, next, previous, up
+@node Top
@top ERC
@insertcopying
@menu
* Introduction:: What is ERC?
-* Obtaining ERC:: How to get ERC releases and development
- versions.
-* Installation:: Compiling and installing ERC.
* Getting Started:: Quick Start guide to using ERC.
* Keystroke Summary:: Keystrokes used in ERC buffers.
* Modules:: Available modules for ERC.
* Advanced Usage:: Cool ways of using ERC.
-* Getting Help and Reporting Bugs::
+* Getting Help and Reporting Bugs::
* History:: The history of ERC.
-* Copying:: The GNU General Public License gives you
- permission to redistribute ERC on
- certain terms; it also explains that
- there is no warranty.
* GNU Free Documentation License:: The license for this documentation.
* Concept Index:: Search for terms.
@detailmenu
--- The Detailed Node Listing ---
-Obtaining ERC
-
-* Releases:: Released versions of ERC.
-* Development:: Latest unreleased development changes.
-
Getting Started
* Sample Session:: Example of connecting to the #emacs channel
@end detailmenu
@end menu
-@node Introduction, Obtaining ERC, Top, Top
-@comment node-name, next, previous, up
+@node Introduction
@chapter Introduction
ERC is a powerful, modular, and extensible IRC client for Emacs.
+It is distributed with Emacs since version 22.1.
It comes with the following capabilities enabled by default.
@end itemize
-@node Obtaining ERC, Installation, Introduction, Top
-@comment node-name, next, previous, up
-@chapter Obtaining ERC
-
-@menu
-* Releases:: Released versions of ERC.
-* Development:: Latest unreleased development changes.
-@end menu
-
-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.3-extras.tar.gz}
-@item @uref{http://ftp.gnu.org/gnu/erc/erc-5.3-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
-@section Releases
-
-Choose to install a release if you want to minimize risk.
-
-Errors are corrected in development first. User-visible changes will be
-announced on the @email{erc-discuss@@gnu.org} mailing list.
-@pxref{Getting Help and Reporting Bugs}.
-
-@cindex releases, Debian package
-@cindex Debian package for ERC
-Debian users can get ERC via apt-get. The @file{erc} package is
-available in the official Debian repository.
-
-@cindex releases, from source
-Alternatively, you can download the latest release from
-@uref{http://ftp.gnu.org/gnu/erc}, or your local GNU mirror.
-
-@node Development, , Releases, Obtaining ERC
-@comment node-name, next, previous, up
-@section Development
-@cindex development
-
-Choose the development version if you want to live on the bleeding edge
-of ERC development or try out new features before release.
-
-@cindex git version control system, using
-The git version control system allows you to keep up-to-date with the
-latest changes to the development version of ERC. It also allows you
-to contribute changes (via commits, if you are have developer access to
-the repository, or via patches, otherwise). If you would like to
-contribute to ERC development, it is highly recommended that you use
-git.
-
-If you are new to git, you might find this tutorial helpful:
-@uref{http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html}.
-
-Downloading ERC with git and staying up-to-date involves the following
-steps.
-
-@enumerate
-@item Install git.
-
-@itemize @bullet
-@item Debian and Ubuntu: @kbd{apt-get install git-core}.
-@item Windows: @uref{http://git.or.cz/gitwiki/WindowsInstall}.
-@item Other operating systems: download, compile, and install the source
-from @uref{http://www.kernel.org/pub/software/scm/git/}, or find a git
-package for your operating system.
-@end itemize
-
-@item Download the ERC development branch.
-
-If you have developer access to ERC, do:
-
-@example
-git clone ssh://loginname@@git.sv.gnu.org/srv/git/erc.git
-@end example
-
-otherwise, do:
-
-@example
-git clone git://git.sv.gnu.org/erc.git
-@end example
-
-If you are behind a restrictive firewall, and do not have developer
-access, then do the following instead:
-
-@example
-git clone http://git.sv.gnu.org/r/erc.git
-@end example
-
-@item List upstream changes that are missing from your local copy.
-Do this whenever you want to see whether new changes have been committed
-to ERC. If you wish, you may skip this step and proceed directly to
-the ``update'' step.
-
-@example
-# Change to the source directory you are interested in.
-cd erc
-
-# Fetch new changes from the repository, but don't apply them yet
-git fetch origin
-
-# Display log messages for the new changes
-git log HEAD..origin
-@end example
-
-``origin'' is git's name for the location where you originally got ERC
-from. You can change this location at any time by editing the
-@file{.git/config} file in the directory where the ERC source was
-placed.
-
-@cindex updating ERC with git
-@item Update to the latest version by pulling in any missing changes.
-
-@example
-cd erc
-git pull origin
-@end example
-
-git will show how many files changed, and will provide a visual display
-for how many lines were changed in each file.
-
-@end enumerate
-
-There are other ways to interact with the ERC repository.
-
-@itemize
-@item Browse git repo: @uref{http://git.sv.gnu.org/gitweb/?p=erc.git}
-@item Latest development snapshot: @uref{http://mwolson.org/static/dist/erc-latest.tar.gz}
-@item Latest development snapshot (zip file): @uref{http://mwolson.org/static/dist/erc-latest.zip}
-@end itemize
-
-The latest development snapshot can lag behind the git repo by as much
-as 20 minutes, but never more than that.
-For further information on committing changes to ERC and performing
-development, please consult
-@uref{http://emacswiki.org/cgi-bin/wiki/ErcDevelopment}.
-
-
-@node Installation, Getting Started, Obtaining ERC, Top
-@comment node-name, next, previous, up
-@chapter Installation
-
-ERC may be compiled and installed on your machine.
-
-This section may be skipped if you are using the version of ERC that
-comes with Emacs.
-
-@subsubheading Compilation
-
-This is an optional step, since Emacs Lisp source code does not
-necessarily have to be byte-compiled. It will yield a speed increase,
-though.
-
-A working copy of Emacs or XEmacs is needed in order to compile ERC. By
-default, the program that is installed with the name @command{emacs}
-will be used.
-
-If you want to use the @command{xemacs} binary to perform the
-compilation, you would need to edit @file{Makefile} in the top-level
-directory as follows. You can put either a full path to an Emacs or
-XEmacs binary or just the command name, as long as it is in the
-@env{PATH}.
-
-@example
-EMACS = xemacs
-SITEFLAG = -no-site-file
-@end example
-
-Running @code{make} should compile the ERC source files in the
-@file{lisp} directory.
-
-@subsubheading Installation
-
-ERC may be installed into your file hierarchy by doing the following.
-
-Edit the @file{Makefile} file so that @env{ELISPDIR} points to where you
-want the source and compiled ERC files to be installed and
-@env{INFODIR} indicates where to put the ERC manual. Of course, you
-will want to edit @env{EMACS} and @env{SITEFLAG} as shown in the
-Compilation section if you are using XEmacs.
-
-If you are installing ERC on a Debian system, you might want to change
-the value of @env{INSTALLINFO} as specified in @file{Makefile}.
-
-Run @code{make} as a normal user.
-
-Run @code{make install} as the root user if you have chosen installation
-locations that require this.
-
-
-@node Getting Started, Keystroke Summary, Installation, Top
-@comment node-name, next, previous, up
+@node Getting Started
@chapter Getting Started
@cindex settings
-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.
-
-@lisp
-(require 'erc)
-@end lisp
-
-Once ERC is loaded, the command @kbd{M-x erc} will start ERC and
-prompt for the server to connect to.
+The command @kbd{M-x erc} will start ERC and prompt for the server to
+connect to.
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.
* Special Features:: Differences from standalone IRC clients
@end menu
-@node Sample Session, Special Features, Getting Started, Getting Started
-@comment node-name, next, previous, up
+@node Sample Session
@section Sample Session
This is an example ERC session which shows how to connect to the #emacs
@end itemize
-@node Special Features, , Sample Session, Getting Started
-@comment node-name, next, previous, up
+@node Special Features
@section Special Features
ERC has some features that distinguish it from some IRC clients.
@item user scripting
-Users can load scripts (e.g. auto greeting scripts) when ERC starts up.
+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
@end itemize
-@node Keystroke Summary, Modules, Getting Started, Top
-@comment node-name, next, previous, up
+@node Keystroke Summary
@chapter Keys Used in ERC
@cindex keystrokes
@end table
-@node Modules, Advanced Usage, Keystroke Summary, Top
-@comment node-name, next, previous, up
+@node Modules
@chapter Modules
@cindex modules
@item fill
Wrap long lines
-@cindex modules, hecomplete
-@item hecomplete
-Complete nicknames and commands (old). This is the old module---you
-might prefer the ``completion'' module instead.
-
@cindex modules, identd
@item identd
Launch an identd server on port 8113
@item notify
Notify when the online status of certain users changes
+@cindex modules, notifications
+@item notifications
+Send you a notification when you get a private message,
+or your nickname is mentioned
+
@cindex modules, page
@item page
Process CTCP PAGE requests from IRC
@c PRE5_4: Document every option of every module in its own subnode
-@node Advanced Usage, Getting Help and Reporting Bugs, Modules, Top
-@comment node-name, next, previous, up
+@node Advanced Usage
@chapter Advanced Usage
@cindex advanced topics
* Options:: Options that are available for ERC.
@end menu
-@node Connecting, Sample Configuration, Advanced Usage, Advanced Usage
-@comment node-name, next, previous, up
+@node Connecting
@section Connecting to an IRC Server
@cindex connecting
help you figure out its parameters.
@defun erc
-Select connection parameters and run ERC.
+Select connection parameters and run ERC@.
Non-interactively, it takes the following keyword arguments.
@itemize @bullet
@defun erc-compute-server &optional server
Return an IRC server name.
-This tries a number of increasingly more default methods until a non-nil
+This tries a number of increasingly more default methods until a non-@code{nil}
value is found.
@itemize @bullet
@end defun
-@defopt erc-server nil
+@defopt erc-server
IRC server to use if one is not provided.
@end defopt
@defun erc-compute-port &optional port
Return a port for an IRC server.
-This tries a number of increasingly more default methods until a non-nil
+This tries a number of increasingly more default methods until a non-@code{nil}
value is found.
@itemize @bullet
Return user's IRC nick.
This tries a number of increasingly more default methods until a
-non-nil value is found.
+non-@code{nil} value is found.
@itemize
@item @var{nick} (the argument passed to this function)
@end defopt
@defopt erc-try-new-nick-p
-If the nickname you chose isn't available, and this option is non-nil,
+If the nickname you chose isn't available, and this option is non-@code{nil},
ERC should automatically attempt to connect with another nickname.
You can manually set another nickname with the /NICK command.
@end defopt
+@subheading Password
+@cindex password
+
+@defopt erc-prompt-for-password
+If non-@code{nil} (the default), @kbd{M-x erc} prompts for a password.
+@end defopt
+
+If you prefer, you can set this option to @code{nil} and use the
+@code{auth-source} mechanism to store your password. For instance, if
+you use @file{~/.authinfo} as your auth-source backend, then put
+something like the following in that file:
+
+@example
+machine irc.example.net login "#fsf" password sEcReT
+@end example
+
+@noindent
+ERC also consults @code{auth-source} to find any channel keys required
+for the channels that you wish to autojoin, as specified by the
+variable @code{erc-autojoin-channels-alist}.
+
+For more details, @pxref{Top,,auth-source, auth, Emacs auth-source Library}.
+
+
@subheading Full name
@defun erc-compute-full-name &optional full-name
Return user's full name.
This tries a number of increasingly more default methods until a
-non-nil value is found.
+non-@code{nil} value is found.
@itemize @bullet
@item @var{full-name} (the argument passed to this function)
This can be either a string or a function to call.
@end defopt
-@node Sample Configuration, Options, Connecting, Advanced Usage
-@comment node-name, next, previous, up
+@node Sample Configuration
@section Sample Configuration
@cindex configuration, sample
-Here is an example of configuration settings for ERC. This can go into
+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}.
(erc :server "localhost" :port "6667"
:nick "MYNICK")))
-;; Make C-c RET (or C-c C-RET) send messages instead of RET. This has
+;; 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)
;; (setq erc-kill-server-buffer-on-quit t)
@end lisp
-@node Options, , Sample Configuration, Advanced Usage
-@comment node-name, next, previous, up
+@node Options
@section Options
@cindex options
@c PRE5_4: (Node) Document every ERC option (module options go in
@c previous chapter)
-This section has not yet been written. For now, the easiest way to
-check out the available options for ERC is to do
+This section is extremely incomplete. For now, the easiest way to
+check out all the available options for ERC is to do
@kbd{M-x customize-group erc RET}.
+@defopt erc-hide-list
+If non, @code{nil}, this is a list of IRC message types to hide, e.g.:
+
+@example
+(setq erc-hide-list '("JOIN" "PART" "QUIT"))
+@end example
+@end defopt
-@node Getting Help and Reporting Bugs, History, Advanced Usage, Top
-@comment node-name, next, previous, up
+@defopt erc-lurker-hide-list
+Like @code{erc-hide-list}, but only applies to messages sent by
+lurkers. The function @code{erc-lurker-p} determines whether a given
+nickname is considered a lurker.
+@end defopt
+
+
+@node Getting Help and Reporting Bugs
@chapter Getting Help and Reporting Bugs
@cindex help, getting
@cindex bugs, reporting
@item
@uref{http://www.emacswiki.org/cgi-bin/wiki/ERC} is the
-emacswiki.org page for ERC. Anyone may add tips, hints, or bug
-descriptions to it.
+emacswiki.org page for ERC@. Anyone may add tips, hints, etc. to it.
@item
-There are several mailing lists for ERC. To subscribe, visit
-@uref{http://savannah.gnu.org/mail/?group=erc}.
-
-The mailing lists are also available on Gmane.
-(@url{http://gmane.org/}). Gmane provides additional methods for
-accessing the mailing lists, adding content to them, and searching them.
-
-@enumerate
-@item gmane.emacs.erc.announce: Announcements
-
-@item gmane.emacs.erc.discuss: General discussion
-
-@item gmane.emacs.erc.cvs: Log messages for changes to the ERC source code
-
-@end enumerate
+You can ask questions about using ERC on the Emacs mailing list,
+@uref{http://lists.gnu.org/mailman/listinfo/help-gnu-emacs}.
@item
You can visit the IRC Freenode channel @samp{#emacs}. Many of the
contributors are frequently around and willing to answer your
questions.
+@item
+To report a bug in ERC, use @kbd{M-x report-emacs-bug}.
+
@end itemize
-@node History, Copying, Getting Help and Reporting Bugs, Top
-@comment node-name, next, previous, up
+@node History
@chapter History
@cindex history, of ERC
We switched to using git for our version control system.
-@end itemize
+@item 2009+
+
+Since about 2009, ERC is no longer developed as a separate project, but
+is maintained as part of Emacs.
-@node Copying, GNU Free Documentation License, History, Top
-@comment node-name, next, previous, up
-@include gpl.texi
+@end itemize
-@node GNU Free Documentation License, Concept Index, Copying, Top
-@comment node-name, next, previous, up
+@node GNU Free Documentation License
+@appendix GNU Free Documentation License
@include doclicense.texi
-@node Concept Index, , GNU Free Documentation License, Top
-@comment node-name, next, previous, up
+@node Concept Index
@unnumbered Index
@printindex cp