Mercurial > emacs
diff man/erc.texi @ 68451:fc745b05e928
Revision: emacs@sv.gnu.org/emacs--devo--0--patch-22
Creator: Michael Olson <mwolson@gnu.org>
Install ERC.
author | Miles Bader <miles@gnu.org> |
---|---|
date | Sun, 29 Jan 2006 13:08:58 +0000 |
parents | |
children | 86c478cccc57 |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/man/erc.texi Sun Jan 29 13:08:58 2006 +0000 @@ -0,0 +1,624 @@ +\input texinfo +@c %**start of header +@setfilename ../info/erc +@settitle ERC Manual +@c %**end of header + +@dircategory Emacs +@direntry +* ERC: (erc). Powerful, modular, and extensible IRC client for Emacs. +@end direntry + +@syncodeindex fn cp + +@copying +This manual is for ERC version 5.1. + +Copyright @copyright{} 2005, 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, Front-Cover texts, or Back-Cover Texts. +@end quotation +@end copying + +@titlepage +@title ERC manual +@subtitle a full-featured IRC client +@subtitle for GNU Emacs and XEmacs + +@c The following two commands +@c start the copyright page. +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@c So the toc is printed at the start +@contents + +@ifnottex +@node Top, Introduction, (dir), (dir) +@comment node-name, next, previous, up +@top ERC + +@insertcopying +@end ifnottex + +@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:: +* History:: The history of ERC. +* Concept Index:: Search for terms. + +@detailmenu + --- The Detailed Node Listing --- + +Obtaining ERC + +* Releases:: Released versions of ERC. +* Development:: Latest unreleased development changes. + +@end detailmenu +@end menu + +@node Introduction, Obtaining ERC, Top, Top +@comment node-name, next, previous, up +@chapter Introduction + +ERC is a powerful, modular, and extensible IRC client for Emacs. + +It comes with the following capabilities enabled by default. + +@itemize @bullet +@item Flood control +@item Timestamps +@item Join channels automatically +@item Buttonize URLs, nicknames, and other text +@item Wrap long lines +@item Highlight or remove IRC control characters +@item Highlight pals, fools, and other keywords +@item Detect netsplits +@item Complete nicknames and commands in a programmable fashion +@item Make displayed lines read-only +@item Input history +@item Track channel activity in the mode-line + +@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 + +These sections 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-help@@lists.sourceforge.net} 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://sourceforge.net/project/showfiles.php?group_id=30118}. + +@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. + +@subsection Using CVS +@cindex CVS, using + +ERC is primarily developed using a CVS repository on sourceforge.net. +To check out a copy of the latest changes, do the following. + +@example +cvs -d:pserver:anonymous@@cvs.sourceforge.net:/cvsroot/erc login +cvs -z3 -d:pserver:anonymous@@cvs.sourceforge.net:/cvsroot/erc co -P erc +@end example + +@cindex CVS snapshot +Alternatively, the latest CVS snapshot may be downloaded in the +following forms. + +@itemize @bullet +@item http://mwolson.org/static/dist/erc-latest.tar.gz +@item http://mwolson.org/static/dist/erc-latest.zip +@end itemize + +@subsection Using the GNU Arch Revision Control System +@cindex arch revision control system, using +The Arch revision control system allows you to retrieve previous +versions and select specific features and bug fixes. + +Michael Olson maintains an official Arch branch for ERC which stays +current with the CVS repository for ERC. If you would like to +contribute to ERC development, and would prefer to use a modern Revision +Control System, feel free to make your own branch. + +If you are new to Arch, you might find this tutorial helpful: +@uref{http://www.mwolson.org/projects/ArchTutorial.html}. + +Downloading ERC with Arch and staying up-to-date involves the following +steps. + +@enumerate +@item Install arch + +@itemize @bullet +@item Debian: @kbd{apt-get install tla}. +@item Other distributions: see @uref{ftp://ftp.gnu.org/gnu/gnu-arch/}. +@end itemize + +@item Register the archive. +@example +tla register-archive -f http://www.mwolson.org/archives/2006 +@end example + +@item Download the ERC source code. +@example +# Download ERC into the @file{erc} directory. +tla get mwolson@@gnu.org--2006/erc--cvs--0 erc +@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. + +@example +# Change to the source directory you are interested in. +cd erc/ + +# Display the summary of changes +tla missing --summary +@end example + +@cindex updating ERC with Arch +@item Update to the latest version by replaying missing changes. +@example +cd erc +tla replay +@end example + +@end enumerate + +There are other ways to interact with the ERC archive. + +@itemize +@item Browse arch repository: @uref{http://www.mwolson.org/archives/} +@item Latest development snapshot: @uref{http://www.mwolson.org/static/dist/erc-latest.tar.gz} +@end itemize + +The latest development snapshot will be kept up-to-date since it is +updated at the same time as the Arch repository. + + +@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 +@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 along with any extra modules you desire. An example follows. + +@lisp +(require 'erc) + +(require 'erc-spelling) +@end lisp + +Once this is loaded, the command @kbd{M-x erc-select} 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) + + +@node Keystroke Summary, Modules, Getting Started, Top +@comment node-name, next, previous, up +@chapter Keys Used in ERC +@cindex keystrokes + +This is a summary of keystrokes available in every ERC buffer. + +@table @kbd + +@item C-a or <home> (`erc-bol') +Go to beginning of line or end of prompt. + +@item RET (`erc-send-current-line') +Send the current line + +@item TAB (`erc-complete-word') +If at prompt, complete the current word. +Otherwise, move to the next link or button. + +@item M-TAB (`ispell-complete-word') +Complete the given word, using ispell. + +@item C-c C-a (`erc-bol') +Go to beginning of line or end of prompt. + +@item C-c C-b (`erc-iswitchb') +Use `iswitchb-read-buffer' to prompt for a ERC buffer to switch to. + +@item C-c C-c (`erc-toggle-interpret-controls') +Toggle interpretation of control sequences in messages. + +@item C-c C-d (`erc-input-action') +Interactively input a user action and send it to IRC. + +@item C-c C-e (`erc-toggle-ctcp-autoresponse') +Toggle automatic CTCP replies (like VERSION and PING). + +@item C-c C-f (`erc-toggle-flood-control') +Toggle use of flood control on sent messages. + +@item C-c TAB (`erc-invite-only-mode') +Turn on the invite only mode (+i) for the current channel. + +@item C-c C-j (`erc-join-channel') +Join channel. If point is at the beginning of a channel name, use that +as default. + +@item C-c C-k (`erc-go-to-log-matches-buffer') +Interactively open an erc-log-matches buffer + +@item C-c C-l (`erc-save-buffer-in-logs') +Append buffer contents to the log file, if logging is enabled. + +@item C-c C-n (`erc-channel-names') +Run "/names #channel" in the current channel. + +@item C-c C-o (`erc-get-channel-mode-from-keypress') +Read a key sequence and call the corresponding channel mode function. +After doing C-c C-o type in a channel mode letter. + +C-g means quit. +RET let's you type more than one mode at a time. +If "l" is pressed, `erc-set-channel-limit' gets called. +If "k" is pressed, `erc-set-channel-key' gets called. +Anything else will be sent to `erc-toggle-channel-mode'. + +@item C-c C-p (`erc-part-from-channel') +Part from the current channel and prompt for a reason. + +@item C-c C-q (`erc-quit-server') +Disconnect from current server after prompting for reason. + +@item C-c C-r (`erc-remove-text-properties-region') +Clears the region (start,end) in object from all colors, etc. + +@item C-c C-t (`erc-set-topic') +Prompt for a topic for the current channel. + +@item C-c C-u (`erc-kill-input') +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 +@chapter Modules +@cindex modules + +One way to add functionality to ERC is to customize which of its many +modules are loaded. + +There is a spiffy customize interface, which may be reached by typing +@kbd{M-x customize-option erc-modules RET}. Alternatively, set +@code{erc-modules} manually and then call @code{erc-update-modules}. + +The following is a list of available modules. + +@table @code + +@cindex modules, autoaway +@item autoaway +Set away status automatically. + +@cindex modules, autojoin +@item autojoin +Join channels automatically + +@cindex modules, bbdb +@item bbdb +Integrate with the Big Brother Database + +@cindex modules, button +@item button +Buttonize URLs, nicknames, and other text + +@cindex modules, fill +@item fill +Wrap long lines + +@cindex modules, irccontrols +@item irccontrols +Highlight or remove IRC control characters + +@cindex modules, log +@item log +Save buffers in logs + +@cindex modules, match +@item match +Highlight pals, fools, and other keywords + +@cindex modules, netsplit +@item netsplit +Detect netsplits + +@cindex modules, noncommands +@item noncommands +Don't display non-IRC commands after evaluation + +@cindex modules, notify +@item notify +Notify when the online status of certain users changes + +@cindex modules, pcomplete +@item pcomplete +Complete nicknames and commands (programmable) + +@cindex modules, readonly +@item readonly +Make displayed lines read-only + +@cindex modules, replace +@item replace +Replace text in messages + +@cindex modules, ring +@item ring +Enable an input history + +@cindex modules, scrolltobottom +@item scrolltobottom +Scroll to the bottom of the buffer + +@cindex modules, services +@item services +Identify to Nickserv (IRC Services) automatically + +@cindex modules, smiley +@item smiley +Convert smileys to pretty icons + +@cindex modules, sound +@item sound +Play sounds when you receive CTCP SOUND requests + +@cindex modules, spell +@item spell +Check spelling + +@cindex modules, stamp +@item stamp +Add timestamps to messages + +@cindex modules, track +@item track +Track channel activity in the mode-line + +@cindex modules, truncate +@item truncate +Truncate buffers to a certain size + +@cindex modules, unmorse +@item unmorse +Translate morse code in messages + +@end table + +@c PRE5_2: 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 +@chapter Advanced Usage +@cindex advanced topics + +Write me. + +@c PRE5_2: (Node) Document every ERC option + +@c PRE5_2: (Node) Tips and tricks + +@c PRE5_2: (Node) Sample configs + + +@node Getting Help and Reporting Bugs, History, Advanced Usage, Top +@comment node-name, next, previous, up +@chapter Getting Help and Reporting Bugs +@cindex help, getting +@cindex bugs, reporting + +After you have read this guide, if you still have questions about ERC, +or if you have bugs to report, there are several places you can go. + +@itemize @bullet + +@item +@uref{http://www.emacswiki.org/cgi-bin/wiki/EmacsIRCClient} is the +emacswiki.org page for ERC. Anyone may add tips, hints, or bug +descriptions to it. + +@item +You can join the mailing list at @email{erc-help@@lists.sourceforge.net} +using the subscription form at +@uref{http://lists.sourceforge.net/lists/listinfo/erc-help}. + +This mailing list is also available via Gmane +(@url{http://gmane.org/}). The group is called +@samp{gmane.emacs.erc.general}. This provides additional methods for +accessing the mailing list, adding content to it, and searching it. + +@item +You can visit the IRC Freenode channel @samp{#emacs}. Many of the +contributors are frequently around and willing to answer your +questions. + +@end itemize + + +@node History, Concept Index, Getting Help and Reporting Bugs, Top +@comment node-name, next, previous, up +@chapter History +@cindex history, of ERC + +ERC was originally written by Alexander L. Belikoff +@email{abel@@bfr.co.il} and Sergey Berezin +@email{sergey.berezin@@cs.cmu.edu}. They stopped development around +december 1999. Their last released version was ERC 2.0. + +P.S.: If one of the original developers of ERC reads this, we'd like to +receive additional information for this file and hear comments in +general. + +@itemize +@item 2001 + +In June 2001, Mario Lang @email{mlang@@delysid.org} and Alex Schroeder +@email{alex@@gnu.org} took over development and created a ERC Project at +sourceforge.net. + +In reaction to a mail about the new erc development, Sergey Berezin +said, "First of all, I'm glad that my version of ERC is being used out +there. The thing is, I do not have free time and enough incentive +anymore to work on ERC, so I would be happy if you guys take over the +project entirely." + +So we happily hacked away on ERC, and soon after (september 2001) +released the next "stable" version, 2.1. + +Most of the development of the new ERC happend on #emacs on +irc.openprojects.net. Over time, many people contributed code, ideas, +bugfixes. And not to forget alot of alpha/beta/gamma testing. + +See the @file{CREDITS} file for a list of contributors. + +@item 2003 + +ERC 3.0 is released. + +@item 2004 + +ERC 4.0 is released. + +@item 2005 + +ERC 5.0 is released. Michael Olson @email{mwolson@@gnu.org} becomes +the release manager and eventually the maintainer. + +After some discussion between him and the Emacs developers, it is +decided to include ERC in Emacs. + +@item 2006 + +ERC 5.1 is released. + +@end itemize + +@node Concept Index, , History, Top +@comment node-name, next, previous, up +@unnumbered Index + +@printindex cp + +@bye + +@ignore + arch-tag: cf9cfaff-fc12-4297-ad15-ec2493002b1e +@end ignore