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