X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/5df4f04cd32af723742c81095b38ae83b3c2b462..ddc412646dbcc51032cf438064d5eb4c8dded906:/doc/misc/erc.texi diff --git a/doc/misc/erc.texi b/doc/misc/erc.texi index 0d87d7d315..569750bd1e 100644 --- a/doc/misc/erc.texi +++ b/doc/misc/erc.texi @@ -3,13 +3,13 @@ @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, 2006, 2007, 2008, 2009, 2010, 2011 -Free Software Foundation, Inc. +Copyright @copyright{} 2005--2012 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -20,15 +20,14 @@ 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''. (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. @end quotation @end copying -@dircategory Emacs +@dircategory Emacs network features @direntry * ERC: (erc). Powerful and extensible IRC client for Emacs. @end direntry @@ -36,7 +35,7 @@ and modified without restriction. @titlepage @title ERC manual @subtitle a full-featured IRC client -@subtitle for GNU Emacs and XEmacs +@subtitle for Emacs and XEmacs @c The following two commands @c start the copyright page. @@ -48,8 +47,7 @@ and modified without restriction. @contents @ifnottex -@node Top, Introduction, (dir), (dir) -@comment node-name, next, previous, up +@node Top @top ERC @insertcopying @@ -57,30 +55,18 @@ and modified without restriction. @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 @@ -95,11 +81,11 @@ Advanced Usage @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. @@ -119,217 +105,13 @@ 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. @@ -344,8 +126,7 @@ you want, do @kbd{M-x customize-variable RET erc-modules RET}. * 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 @@ -403,8 +184,7 @@ talk with them. @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. @@ -461,7 +241,7 @@ translation effort. @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 @@ -478,8 +258,7 @@ ERC buffer and run the @code{/RECONNECT} command. @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 @@ -562,8 +341,7 @@ Kill current input line using `erc-bol' followed by `kill-line'. @end table -@node Modules, Advanced Usage, Keystroke Summary, Top -@comment node-name, next, previous, up +@node Modules @chapter Modules @cindex modules @@ -607,11 +385,6 @@ Complete nicknames and commands (programmable) @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 @@ -644,6 +417,11 @@ Don't display non-IRC commands after evaluation @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 @@ -701,8 +479,7 @@ Translate morse code in messages @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 @@ -712,8 +489,7 @@ Translate morse code in messages * 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 @@ -722,7 +498,7 @@ If you want to assign this function to a keystroke, the following will 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 @@ -749,7 +525,7 @@ parameters. @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 @@ -761,7 +537,7 @@ value is found. @end defun -@defopt erc-server nil +@defopt erc-server IRC server to use if one is not provided. @end defopt @@ -770,7 +546,7 @@ IRC server to use if one is not provided. @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 @@ -793,7 +569,7 @@ This can be either a string or a number. 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) @@ -817,19 +593,43 @@ The string to append to the nick if it is already in use. @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) @@ -846,12 +646,11 @@ User full name. 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}. @@ -902,7 +701,7 @@ stuff, to the current ERC buffer." (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) @@ -926,21 +725,33 @@ stuff, to the current ERC buffer." ;; (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.: -@node Getting Help and Reporting Bugs, History, Advanced Usage, Top -@comment node-name, next, previous, up +@example +(setq erc-hide-list '("JOIN" "PART" "QUIT")) +@end example +@end defopt + +@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 considerd a lurker. +@end defopt + + +@node Getting Help and Reporting Bugs @chapter Getting Help and Reporting Bugs @cindex help, getting @cindex bugs, reporting @@ -952,36 +763,24 @@ or if you have bugs to report, there are several places you can go. @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 @@ -1044,24 +843,20 @@ our revision control system. Our mailing list address changed as well. We switched to using git for our version control system. -@end itemize +@item 2009+ -@node Copying, GNU Free Documentation License, History, Top -@comment node-name, next, previous, up -@include gpl.texi +Since about 2009, ERC is no longer developed as a separate project, but +is maintained as part of Emacs. -@node GNU Free Documentation License, Concept Index, Copying, Top -@comment node-name, next, previous, up +@end itemize + +@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 @bye - -@ignore - arch-tag: cf9cfaff-fc12-4297-ad15-ec2493002b1e -@end ignore