[Emacs-diffs] Changes to emacs/man/erc.texi,v

[Miles Bader]

CVSROOT:        /cvsroot/emacs
Module name:    emacs
Changes by:     Miles Bader <miles>     07/04/01 13:36:38

Index: man/erc.texi
===================================================================
RCS file: /cvsroot/emacs/emacs/man/erc.texi,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -b -r1.12 -r1.13
--- man/erc.texi        21 Jan 2007 04:41:11 -0000      1.12
+++ man/erc.texi        1 Apr 2007 13:36:38 -0000       1.13
@@ -12,7 +12,7 @@
 @syncodeindex fn cp
 
 @copying
-This manual is for ERC version 5.2 stable pre-release.
+This manual is for ERC version 5.2.
 
 Copyright @copyright{} 2005, 2006, 2007 Free Software Foundation, Inc.
 
@@ -21,6 +21,9 @@
 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.
+
+All Emacs Lisp code contained in this document may be used, distributed,
+and modified without restriction.
 @end quotation
 @end copying
 
@@ -68,12 +71,16 @@
 * 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
@@ -111,8 +118,17 @@
 * 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.
+
address@hidden @bullet
address@hidden @uref{http://ftp.gnu.org/gnu/erc/erc-5.2-extras.tar.gz}
address@hidden @uref{http://ftp.gnu.org/gnu/erc/erc-5.2-extras.zip}
address@hidden 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
@@ -131,7 +147,7 @@
 
 @cindex releases, from source
 Alternatively, you can download the latest release from
address@hidden://ftp.gnu.org/gnu/erc}.
address@hidden://ftp.gnu.org/gnu/erc}, or your local GNU mirror.
 
 @node Development,  , Releases, Obtaining ERC
 @comment  node-name,  next,  previous,  up
@@ -188,9 +204,9 @@
 
 @end enumerate
 
-If you are new to Arch and want to learn more about developing with it,
-you might find this tutorial helpful:
address@hidden://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
 
@@ -261,8 +277,6 @@
 @chapter Getting Started
 @cindex settings
 
address@hidden 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.
@@ -274,20 +288,151 @@
 Once ERC is loaded, 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.
+
+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}.
+
address@hidden
+* Sample Session::              Example of connecting to the #emacs channel
+* Special Features::            Differences from standalone IRC clients
address@hidden menu
+
address@hidden Sample Session, Special Features, Getting Started, Getting 
Started
address@hidden  node-name,  next,  previous,  up
address@hidden 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.
+
address@hidden @bullet
+
address@hidden Connect to Freenode
+
+Run @kbd{M-x erc}.  Use ``irc.freenode.net'' as the IRC server, ``6667''
+as the port, and choose a nickname.
+
address@hidden 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.
+
address@hidden 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.
+
address@hidden 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.
+
address@hidden 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.
+
address@hidden 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.
+
address@hidden itemize
+
address@hidden Special Features, , Sample Session, Getting Started
address@hidden  node-name,  next,  previous,  up
address@hidden Special Features
+
+ERC has some features that distinguish it from some IRC clients.
+
address@hidden @bullet
+
address@hidden multiple channels and multiple servers
+
+Every channel is put in a separate buffer.  Several IRC servers may be
+connected to at the same time.
+
address@hidden query buffers
address@hidden private message separation
+
+Private conversations are treated as channels, and are put into separate
+buffers in Emacs.  We call these ``query buffers''.
+
address@hidden highlighting
+
+Some occurences of words can be highlighted, which makes it easier to
+track different kinds of conversations.
+
address@hidden notification
+
+ERC can notify you that certain users are online.
+
address@hidden 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.
+
address@hidden nick completion
+
+ERC can complete words upon hitting @kbd{TAB}, which eases the writing
+of nicknames in messages.
+
address@hidden history ring
address@hidden 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.
+
address@hidden 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
address@hidden@@gnu.org} if you are interested in helping with the
+translation effort.
+
address@hidden 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
address@hidden, where @code{NEWCOMMAND} is the name of the
+new command in capital letters.
+
address@hidden 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 /RECONNECT command.
+ERC  buffer and run the @code{/RECONNECT} command.
 
address@hidden PRE5_2: Sample session, including:
address@hidden - connect to Freenode
address@hidden - /join #emacs
address@hidden - see messages flying past, point out topic lines, messages, 
channel
address@hidden   members
address@hidden - identifying your nick with NickServ (most IRC servers have 
this)
address@hidden - talking to the channel
address@hidden - open a /query buffer to talk to someone (must identify first in
address@hidden   FreeNode)
address@hidden itemize
 
 
 @node Keystroke Summary, Modules, Getting Started, Top
@@ -439,6 +584,10 @@
 @item match
 Highlight pals, fools, and other keywords
 
address@hidden modules, menu
address@hidden menu
+Display a menu in ERC buffers
+
 @cindex modules, netsplit
 @item netsplit
 Detect netsplits
@@ -505,7 +654,7 @@
 
 @end table
 
address@hidden PRE5_2: Document every option of every module in its own subnode
address@hidden PRE5_3: Document every option of every module in its own subnode
 
 
 @node Advanced Usage, Getting Help and Reporting Bugs, Modules, Top
@@ -515,12 +664,11 @@
 
 @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
 
address@hidden Connecting, Options, Advanced Usage, Advanced Usage
address@hidden Connecting, Sample Configuration, Advanced Usage, Advanced Usage
 @comment  node-name,  next,  previous,  up
 @section Connecting to an IRC Server
 @cindex connecting
@@ -654,33 +802,97 @@
 This can be either a string or a function to call.
 @end defopt
 
address@hidden Options, Tips and Tricks, Connecting, Advanced Usage
address@hidden Sample Configuration, Options, Connecting, Advanced Usage
 @comment  node-name,  next,  previous,  up
address@hidden Options
address@hidden options
address@hidden Sample Configuration
address@hidden configuration, sample
 
address@hidden PRE5_2: (Node) Document every ERC option (module options go in
address@hidden 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.
address@hidden
+;;; Sample ERC configuration
 
address@hidden Tips and Tricks, Sample Configuration, Options, Advanced Usage
address@hidden  node-name,  next,  previous,  up
address@hidden Tips and Tricks
address@hidden 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")
 
address@hidden 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 address@hidden ["
+          ;; 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 "@address@hidden [" 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)
address@hidden lisp
 
address@hidden Sample Configuration, , Tips and Tricks, Advanced Usage
address@hidden Options, , Sample Configuration, Advanced Usage
 @comment  node-name,  next,  previous,  up
address@hidden Sample Configuration
address@hidden configuration, sample
address@hidden Options
address@hidden options
 
address@hidden PRE5_2: (Node) Sample configs
address@hidden PRE5_3: (Node) Document every ERC option (module options go in
address@hidden 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
address@hidden customize-group erc RET}.
 
 
 @node Getting Help and Reporting Bugs, History, Advanced Usage, Top