diff man/erc.texi @ 68451:fc745b05e928

Revision: [e-mail]/emacs--devo--0--patch-22 Creator: Michael Olson <[e-mail]> Install ERC.

--- /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