Fixed typo.
[riece] / doc / riece-en.texi
1 \input texinfo                  @c -*- mode: texinfo; coding: iso-2022-jp -*-
2 @c %**start of header
3 @setfilename riece-en.info
4 @settitle Riece -- An IRC client for Emacsen --
5 @c %**end of header
6 @set VERSION 1.0.8
7 @c @documentlanguage en
8
9 @dircategory GNU Emacs Lisp
10 @direntry
11 * Riece-en: (riece-en).   An IRC client for Emacsen
12 @end direntry
13
14 @ifinfo
15 This file describes Riece.
16
17 Copyright (C) 2003,2004,2005 Daiki Ueno.
18
19 Permission is granted to copy, distribute and/or modify this document
20 under the terms of the GNU Free Documentation License, Version 1.1 or
21 any later version published by the Free Software Foundation; with no
22 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
23 Texts.  A copy of the license is included in the section entitled "GNU
24 Free Documentation License".
25 @end ifinfo
26
27 @tex
28
29 @titlepage
30 @title Riece
31
32 @author by Daiki Ueno
33 @page
34
35 @vskip 0pt plus 1filll
36 Copyright @copyright{} 2003,2004,2005 Daiki Ueno.
37
38 Permission is granted to copy, distribute and/or modify this document
39 under the terms of the GNU Free Documentation License, Version 1.1 or
40 any later version published by the Free Software Foundation; with no
41 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
42 Texts.  A copy of the license is included in the section entitled "GNU
43 Free Documentation License".
44 @end titlepage
45 @page
46
47 @end tex
48
49 @node Top, Overview, (dir), (dir)
50 @top Riece user's manual
51
52 Riece is a program to participate in IRC (Internet Relay Chat) from Emacs.
53
54 @menu
55 * Overview::                    What's Riece?
56 * Getting started::             
57 * Basic usage::                 Let's talk with other people.
58 * Index::                       
59 * Function Index::              
60 * Variable Index::              
61 @end menu
62
63 @node Overview, Getting started, Top, Top
64 @chapter Overview
65
66 Riece is a full rewrite of the predecessor product "Liece" (whose code
67 has been unmaintainable for a long time), while providing a user
68 interface (mostly) compatible with Liece.
69
70 There are noteworthy improvements as compared with Liece:
71
72 @itemize @bullet
73 @item
74 Several IRC servers may be used at the same time.
75
76 @item
77 Essential features can be built upon the extension framework (called
78 "add-on") capable of dependency tracking.
79
80 @item
81 Installation is easy.  Riece doesn't depend on other packages.
82
83 @item
84 Setup is easy.  Automatically save/restore the configuration.
85
86 @item
87 Step-by-step instructions are included.
88
89 @item
90 Mostly compliant with the latest IRC client protocol (RFC 2812).
91 @end itemize
92
93 For more details, please look at the following pages:
94
95 @itemize @bullet
96 @item http://www.nongnu.org/riece/
97 @end itemize
98
99 @node Getting started, Basic usage, Overview, Top
100 @chapter Getting started
101
102 @menu
103 * Required Environments::       
104 * Installation::                
105 * Startup File::                
106 @end menu
107
108 @node Required Environments, Installation, Getting started, Getting started
109 @section Required Environments
110
111 We checked this version working on the following environments.
112
113 @itemize @bullet
114 @item Emacs 20.7 or later
115 @item XEmacs 21.4 or later
116 @end itemize
117
118 @node Installation, Startup File, Required Environments, Getting started
119 @section Installation
120
121 The latest version of Riece can be obtained from
122 @uref{http://wiliki.designflaw.org/riece.cgi}.  After unpacking the
123 tarball, you can install with the following commands:
124
125 @example
126 ./configure
127 make
128 make install
129 @end example
130
131 If you want to install Riece as an XEmacs package, use the following
132 commands instead of the above:
133
134 @example
135 ./configure --with-xemacs[=xemacs-21.4.17]
136 make package
137 make install-package
138 @end example
139
140 If you do not so, it is necessery to add autoload setting to your Emacs
141 startup file (probably @file{~/.emacs}) to be able to start Riece by
142 typing @kbd{M-x riece}.
143
144 @lisp
145 (autoload 'riece "riece" "Start Riece" t)
146 @end lisp
147
148 @node Startup File,  , Installation, Getting started
149 @section Startup file
150
151 In this section we describe Riece's startup files.
152
153 If you are attempting to use Riece by way of trial, nothing needed to be
154 written in startup files.  Thus you can skip this section.
155
156 Riece reads startup files under the directory pointed by the variable
157 @code{riece-directory} (by default, it has @file{~/.riece/} as the
158 value).  There are two kinds of startup files in the directory:
159
160 @table @code
161 @item riece-saved-variables-file
162 @vindex riece-saved-variables-file
163 Variables changed during the last session are automatically saved in this file.
164 (by default, it is located at @file{~/.riece/save})
165 @item riece-variables-file
166 @vindex riece-variables-file
167 Users can edit this file to configure their own settings (by default, it
168 is located at @file{~/.riece/init})
169 @end table
170
171 At startup, Riece will first read @code{riece-saved-variables-file},
172 and then @code{riece-variables-file}.  That is to say, automatically
173 saved variables may be refered/modified by user configuration.
174
175 @node Basic usage, Index, Getting started, Top
176 @chapter Basic usage
177
178 To start Riece, you just type @kbd{M-x riece}.  Then you will prompted
179 for the name of an IRC server.  A typical IRC network may consist of
180 several IRC servers and you will need to pick up appropriate one.  Most
181 of IRC networks provide a list of available servers on their Web pages:
182
183 @itemize @bullet
184 @item http://irc.kyoto-u.ac.jp
185 @item http://freenode.net
186 @end itemize
187
188 If your nickname is taken, you will be asked to use different one.  The
189 initial nickname can be set via the variable @code{riece-nickname}.  By
190 default, your nickname is generated from your login name.
191 @vindex riece-nickname
192
193 After successfully connecting to an IRC server, you can join a channel
194 and talk with people there.  To join a channel, type @kbd{C-c j}.  By
195 the way there is a channel called @samp{#Riece} on IRCnet, so feel free
196 to use it for testing.
197
198 Now you enter a message and it will be seen by everyone else on the
199 channel.  Messages from other people will appear on the top-left window.
200
201 @menu
202 * Windows::                     
203 * Indicators::                  
204 * Commands::                    
205 * Connecting to multiple servers::  
206 @end menu
207
208 @node Windows, Indicators, Basic usage, Basic usage
209 @section Windows
210
211 By default, Riece uses 5 windows to inform user of his status:
212
213 @example
214 +-----+-----------------+
215 |     |                 |
216 |     |                 |
217 | (1) |       (2)       |
218 |     |                 |
219 |     |                 |
220 +-----+-----------------+
221 |     |       (4)       |
222 |     +-----------------+
223 | (3) |                 |
224 |     |       (5)       |
225 |     |                 |
226 +-----+-----------------+
227 @end example
228
229 Each window is used for different purpose:
230
231 @enumerate
232 @item
233 "user list window" (@samp{*Users XXX*}).  Users on the current
234 channel are listed in this window.
235
236 @item
237 "channel window" (@samp{*Channel XXX*}).  This window keeps
238 dialogues on the current channel.
239
240 @item
241 "channel list window" (@samp{*Channels*}).  All channels you are
242 joined are listed in this window.
243
244 @item
245 "command window" (@samp{*Commands*}).  This window is used for either
246 sending messages or issueing commands.
247
248 @item
249 "others buffer" (@samp{*Others*}).  This window displays dialogues on
250 channels except the current channel.
251 @end enumerate
252
253 @node Indicators, Commands, Windows, Basic usage
254 @section Indicators
255
256 Indicators are characters which indicate your status.  Usually they are
257 put on the left side of the modeline like:
258
259 @example
260 Riece: --- ueno #Riece [n]
261 @end example
262
263 In this case, @samp{---} are indicators.  From left to right their
264 meanings are:
265
266 @enumerate
267 @item
268 You are not "away". (If you marked yourself as "away", it would be
269 @samp{A})
270
271 @item
272 You are not an IRC operator. (If you entered operator mode, it would be
273 @samp{O})
274
275 @item
276 The channel window is not locked.
277 (If it was locked, it would be @samp{F}.  If it was locked until next
278 send, it would be @samp{f})
279 @end enumerate
280
281 @node Commands, Connecting to multiple servers, Indicators, Basic usage
282 @section Commands
283
284 The buffer used for sending messages is called "command buffer".
285 You can issue various commands from the command buffer.
286
287 @subsection IRC commands
288 @table @kbd
289 @item RET
290 @findex riece-command-enter-message
291 Send the current line. (@code{riece-command-enter-message})
292 @item C-RET
293 @findex riece-command-enter-message-as-notice
294 Send the current line as NOTICE. (@code{riece-command-enter-message-as-notice})
295 @item C-c j
296 @findex riece-command-join
297 Join a channel. (@code{riece-command-join})
298 @item C-c C-p
299 @findex riece-command-part
300 Part from a channel. (@code{riece-command-part})
301 @item C-c p
302 @findex riece-command-enter-message-to-user
303 Send the current line to particular
304 user. (@code{riece-command-enter-message-to-user})
305 @item C-c q
306 @findex riece-command-quit
307 Quit from IRC. (@code{riece-command-quit})
308 @item C-c n
309 @findex riece-command-change-nickname
310 Change your nickname. (@code{riece-command-change-nickname})
311 @item C-c f
312 @findex riece-command-finger
313 Get information of a user. (@code{riece-command-finger})
314 @item C-c C-k
315 @findex riece-command-kick
316 Kick a user from the current channel. (@code{riece-command-kick})
317 @item C-c i
318 @findex riece-command-invite
319 Invite a user to the current channel. (@code{riece-command-invite})
320 @item C-c l
321 @findex riece-command-list
322 Issue a LIST command with specified pattern. (@code{riece-command-list})
323 @item C-c C-n
324 @findex riece-command-names
325 Issue a NAMES command with specified pattern. (@code{riece-command-names})
326 @item C-c w
327 @findex riece-command-who
328 Issue a WHO command with specified pattern. (@code{riece-command-who})
329 @item C-c t
330 @findex riece-command-topic
331 Set topic of the current channel. (@code{riece-command-topic})
332 @item C-c C-m
333 @findex riece-command-change-mode
334 Change the mode of the current channel. (@code{riece-command-change-mode})
335 @item C-c o
336 @findex riece-command-set-operators
337 Assign channel operator privilege to a user.  If a prefix argument
338 (@kbd{C-u}) is given, remove the privilege from a
339 user. (@code{riece-command-set-operators})
340 @item C-c v
341 @findex riece-command-set-speakers
342 Allow a user to speak in the current channel.  If a prefix argument
343 (@kbd{C-u}) is given, disallow a user to
344 speak. (@code{riece-command-set-speakers})
345 @item C-c V
346 @findex riece-version
347 Display version number of Riece.  If a prefix argument (@kbd{C-u}) is
348 given, use User-Agent format.
349 @item C-c /
350 @findex riece-command-raw
351 Send raw IRC command. (@code{riece-command-raw})
352 @end table
353
354 @subsection Window manipulating commands
355 @table @kbd
356 @item C-c r
357 @findex riece-command-configure-windows
358 Redraw windows. (@code{riece-command-configure-windows})
359 @item C-c C-j
360 @findex riece-command-next-channel
361 Switch to the next channel in the channel
362 list. (@code{riece-command-next-channel})
363 @item C-c <
364 @findex riece-command-previous-channel
365 Switch to the previous channel in the channel
366 list. (@code{riece-command-previous-channel})
367 @item C-c >
368 @findex riece-command-next-channel
369 Switch to the next channel in the channel
370 list. (@code{riece-command-next-channel})
371 @item C-c ^
372 @findex riece-command-list-addons
373 Browse add-ons currently insinuated. (@code{riece-command-list-addons})
374 @item C-c digit
375 @findex riece-command-switch-to-channel-by-number
376 Switch to @var{n}th channel in the channel
377 list. (@code{riece-command-switch-to-channel-by-number})
378 @item C-c C-c digit
379 @findex riece-command-switch-to-channel-by-number
380 Switch to @var{n} + 10th channel in the channel
381 list. (@code{riece-command-switch-to-channel-by-number})
382 @item C-c Home
383 @findex riece-command-beginning-of-buffer
384 Move point to the beginning of the buffer in the channel window.
385 (@code{riece-command-beginning-of-buffer})
386 @item C-c $
387 @findex riece-command-end-of-buffer
388 Move point to the end of the buffer in the channel window.
389 (@code{riece-command-end-of-buffer})
390 @item C-c SPC
391 @findex riece-command-scroll-up
392 Scroll text of the channel window up. (@code{riece-command-scroll-up})
393 @item C-c DEL
394 @findex riece-command-scroll-down
395 Scroll text of the channel window down. (@code{riece-command-scroll-down})
396 @end table
397
398 @subsection Status toggle commands
399 @table @kbd
400 @item C-c C-t c
401 @findex riece-command-toggle-channel-buffer-mode
402 Toggle visibility of the channel
403 window. (@code{riece-command-toggle-channel-buffer-mode})
404 @item C-c C-t C
405 @findex riece-command-toggle-channel-list-buffer-mode
406 Toggle visibility of the channel list
407 window. (@code{riece-command-toggle-channel-list-buffer-mode})
408 @item C-c C-t u
409 @findex riece-command-toggle-user-list-buffer-mode
410 Toggle visibility of the user list
411 window. (@code{riece-command-toggle-user-list-buffer-mode})
412 @item C-c C-t f
413 @findex riece-command-toggle-freeze
414 Disable scrolling of the channel window. (@code{riece-command-toggle-freeze})
415 @item C-c C-t o
416 @findex riece-command-toggle-own-freeze
417 Disable scrolling of the channel window until next
418 send. (@code{riece-command-toggle-own-freeze})
419 @item C-c C-t a
420 @findex riece-command-toggle-away
421 Mark or unmark yourself as "away". (@code{riece-command-toggle-away})
422 @end table
423
424 @node Connecting to multiple servers,  , Commands, Basic usage
425 @section Connecting to multiple servers
426
427 One of the most important features of Riece is that users can use
428 several IRC servers at the same time.
429
430 The procedure to use multiple servers consists (1) connecting to the
431 foreign server and (2) joinning a channel:
432
433 @enumerate
434 @item
435 Type @kbd{C-c O} (@code{riece-command-open-server}), and then you will
436 be asked the server name.
437
438 @item
439 Type @kbd{C-c j} (@code{riece-command-join}) to join a channel.  Here
440 the server name follows the channel name.  To input a space character,
441 use @kbd{C-q}.  For example, if you want to join the channel
442 @samp{#Riece} on the server @samp{irc6}, type @kbd{C-c j #Riece C-q SPC
443 irc6}.
444 @end enumerate
445
446 If you want to send IRC command without joinning a channel, @kbd{C-c M}
447 (@code{riece-command-universal-server-name-argument}) may be useful.
448
449 Commands used for connection management are listed below:
450
451 @table @kbd
452 @item C-c O
453 @findex riece-command-open-server
454 Connect to the foreign server. (@code{riece-command-open-server})
455 @item C-c C
456 @findex riece-command-close-server
457 Close the connection to the server. (@code{riece-command-close-server})
458 @item C-c M
459 @findex riece-command-universal-server-name-argument
460 Issue a command on the specified
461 server. (@code{riece-command-universal-server-name-argument})
462 @end table
463
464 @node Index, Function Index, Basic usage, Top
465 @chapter Index
466 @printindex cp
467
468 @node Function Index, Variable Index, Index, Top
469 @chapter Function Index
470 @printindex fn
471
472 @node Variable Index,  , Function Index, Top
473 @chapter Variable Index
474 @printindex vr
475
476 @summarycontents
477 @contents
478 @bye
479
480 @c End: