-
Notifications
You must be signed in to change notification settings - Fork 2
/
readme.htm
312 lines (312 loc) · 19.3 KB
/
readme.htm
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>quIRC: README</title>
<meta http-equiv="Content-Type" content="text/html;charset=utf-8;" />
<link rel="stylesheet" href="readme.css" />
<style type="text/css">
tt {margin-left:4em;}
</style>
</head>
<body>
<div id="title">
<h1>quIRC: readme</h1>
<h5>quIRC is a lightweight terminal-based <acronym title="Internet Relay Chat">IRC</acronym> client. It is written in C.</h5>
</div><!--#title-->
<div id="contents">
<h2>Contents</h2>
<ul>
<li><a href="#foreword">Foreword</a></li>
<li><a href="#furtherhelp">Further Help</a></li>
<li><a href="#commands">Commands</a></li>
<li><a href="#configuration">Configuration</a></li>
<li><a href="#inputcontrols">Input Controls</a></li>
<li><a href="#othercontrols">Other Controls</a></li>
<li><a href="#keymapping">Keymapping</a></li>
<li><a href="#tabstrip">Tab strip</a></li>
<li><a href="#trouble">Troubleshooting</a></li>
</ul>
</div><!--#contents-->
<div id="foreword">
<h2>Foreword</h2>
<p>I like to engage with my user population. I welcome bug reports, feature requests, patches, and even undirected rambling musings about what direction quIRC should take in the future. If you use (or are considering using) quIRC, please drop into #quirc on irc.newnet.net for a chat.</p>
</div><!--#foreword-->
<div id="furtherhelp">
<h2>Further Help</h2>
<p>If this file doesn't answer your question, you can find help from several other places.</p>
<p>First port of call is the website, <a href="http://jttlov.no-ip.org/projects/quirc.htm">http://jttlov.no-ip.org</a>.<br />
Then there's the github page, <a href="http://github.com/ec429/quIRC">http://github.com/ec429/quIRC</a>.</p>
<p>Or try our IRC channel, #quirc on irc.newnet.net (if your problem doesn't prevent you from joining us there!)</p>
</div><!--#furtherhelp-->
<div id="commands">
<h2>Commands</h2>
<p>All commands are prefixed with a '/'. Anything else is a message to be sent to the channel (or nick if current tab is a private messaging tab).</p>
<dl>
<dt>/help [<em>cmd</em>]</dt>
<dd>Show on-line help for command <small>/<em>cmd</em></small>. If <em>cmd</em> is omitted, list all commands.</dd>
<dt>/server <em>url</em></dt>
<dd>Connects to the given server (will open in a new tab).</dd>
<dt>/nick <em>nickname</em></dt>
<dd>Sets your nickname. Scope is server-wide (or, in (status) tab, sets default for new /servers).</dd>
<dt>/join <em>channel</em> [<em>key</em>]</dt>
<dd>Joins the given channel (will open in a new tab).</dd>
<dt>/me <em>action</em></dt>
<dd>Sends an 'action' to the channel.</dd>
<dt>/msg [-n] <em>recipient</em> [<em>message</em>]</dt>
<dd>Private message; sends the message to the given recipient. Will open a private messaging tab if one is not already open for that recipient (suppress with -n). If <em>message</em> is omitted, just opens the tab.</dd>
<dt>/amsg <em>message</em></dt>
<dd>Send message to all attached channels on this server.</dd>
<dt>/ping [<em>recipient</em>]</dt>
<dd>Send a CTCP ping to <em>recipient</em>. If used in a private messaging tab, <em>recipient</em> may be omitted.</dd>
<dt>/topic [<em>message</em>]</dt>
<dd>Sets or gets the channel topic.</dd>
<dt>/mode [<em>nick</em> [{+|-}<em>mode</em>]]</dt>
<dd>Without a {+|-}<em>mode</em>, queries your mode, or the mode of <em>nick</em> if given.<br />
<small>/mode <em>nick</em> +<em>mode</em></small> sets mode <em>mode</em> on <em>nick</em>; <small>/mode <em>nick</em> -<em>mode</em></small> unsets it.</dd>
<dt>/away [<em>msg</em>]</dt>
<dt>/unaway</dt>
<dt>/away -</dt>
<dd>Indicates that you are away, by storing an away message (<em>msg</em>) on the server; it will be sent to anyone who private-messages you. <small>/away -</small> or <small>/unaway</small> removes any away message you have set.</dd>
<dt>/afk [<em>msg</em>]</dt>
<dt>/afk -</dt>
<dd>Indicates that you are 'away from keyboard' ('afk') by appending <small>|afk</small> (or <small>|<em>msg</em></small>) to your nick. <small>/afk -</small> removes any such indications.</dd>
<dt>/set <em>option</em> [<em>value</em>]</dt>
<dd>Sets configuration options; the options are analogous to those in .quirc, with one or two extras.
<ul>
<li>The options 'height' and 'width' are used to tell quIRC how many rows and columns your terminal has (for cursor-positioning). quIRC will try to deduce these values (from environment variables $LINES and $COLUMNS, using defaults of 80x24 if these env vars are not found), but you can override those guesses here or on the command line.</li>
<li>The option 'conf' can be /set for each channel (the rc and cmdline versions control the default setting). In Conference Mode (<small>/set conf +</small>), joins, parts, quits, nick changes etc. will not be displayed. This can be useful in busy channels.</li>
<li>The options 'uname', 'fname' and 'pass' are analogous to the --uname, --fname and --pass commandline options.</li>
</ul>
For full details see <a href="config_ref.htm">config_ref.htm</a>.
</dd>
<dt>/log <em>logtype</em> <em>file</em></dt>
<dt>/log -</dt>
<dd>Starts logging the current buffer to <em>file</em> (relative to <small>~/.quirc/</small>), using a format specified by <em>logtype</em>. This may be <small>plain</small> (human-readable output similar to normal display) or <small>symbolic</small> (machine-readable, though still textual, format).<br />
<small>/log -</small> disables logging for the current buffer.</dd>
<dt>/ignore [-ipd] <em>nick</em>[!<em>user</em>[@<em>host</em>]]</dt>
<dt>/ignore [-ipd] -r <em>regex</em></dt>
<dt>/ignore -l</dt>
<dd>Adds a nick to your "ignore list", thus preventing messages from that nick from appearing.
<dl>
<dt>-i</dt>
<dd>Match will be case-insensitive</dd>
<dt>-p</dt>
<dd>Will also ignore matching <em>private</em> messages</dd>
<dt>-d</dt>
<dd>Instead of adding a rule, remove all rules matching the given nick!user@host</dd>
<dt>-r</dt>
<dd>Supply a regular expression match. The usual form (without -r) generates the regular expression <small>^<em>nick</em>[_~]*!<em>user</em>@<em>host</em>$</small>; if <em>user</em> or <em>host</em> are not given (or begin with *), they are replaced with <small>[^!@]*</small> resp. <small>[^@]</small></dd>
<dt>-l</dt>
<dd>Instead of adding a rule, list rules which apply to this tab</dd>
</dl>
</dd>
<dt>/rejoin [<em>key</em>]</dt>
<dd>Rejoins a channel tab which is dead (eg after losing server connection). If <em>key</em> is not specified, the previous key (if any) will be used.</dd>
<dt>/reconnect</dt>
<dd>Reconnects to a server from which you have become disconnected.</dd>
<dt>/realsname</dt>
<dd>Displays the hostname of the server you are connected to.</dd>
<dt>/grep [<em>pattern</em>]</dt>
<dd>Searches backwards through the current tab's backscroll for the regular expression <em>pattern</em>, and scrolls to a match if found. If <em>pattern</em> is omitted, uses your nick (note that this may behave oddly if your nick contains regex metacharacters). Uses POSIX Extended Regular Expression syntax.</dd>
<dt>/part <em>channel</em></dt>
<dt>/leave <em>channel</em></dt>
<dd>Leaves (departs) the given channel.</dd>
<dt>/disconnect [<em>message</em>]</dt>
<dd>Disconnects from the server, optionally sending a 'quit message'.</dd>
<dt>/close</dt>
<dd>Closes the current tab. In addition, has an effect which depends on the tab type:
<dl>
<dt>(status)</dt>
<dd>Disconnects from all servers and quits quIRC</dd>
<dt>{server}</dt>
<dd>Disconnects from the server and all channels on that server</dd>
<dt>[channel]</dt>
<dd>Leaves the channel</dd>
</dl>
</dd>
<dt>/quit [<em>message</em>]</dt>
<dt>/exit [<em>message</em>]</dt>
<dd>Quits quIRC, optionally sending a 'quit message' to the server.</dd>
<dt>/cmd <em>command</em></dt>
<dd>Allows you to send a raw command to the server; not recommended.</dd>
<dt>/tab <em>n</em></dt>
<dd>Switches to tab number <em>n</em>; (status) is tab 0.</dd>
<dt>/left</dt>
<dt>/right</dt>
<dd>Swaps the current tab with the tab on its left (or right); tab 0 (status) cannot be moved.</dd>
<dt>/sort</dt>
<dd>Sorts the tab list into an intuitive order (grouping channels after their parent servers; maintaining the order of the servers and of each server's channels).</dd>
<dt>//[<em>msg</em>]</dt>
<dd>Sends /<em>msg</em> to the channel.</dd>
</dl>
</div><!--#commands-->
<div id="configuration">
<h2>Configuration</h2>
<p>quIRC can be configured through an "rc file" as follows. (For a compact reference table see <a href="config_ref.htm">config_ref.htm</a>)</p>
<p>In your home directory (/home/<em>username</em>), create a folder called ".quirc", a file within that folder called "rc", and open it in your editor.</p>
<p>In this file you can set servers, nick and channels to automatically use:<br />
<tt>nick <em>global-nickname</em></tt><br />
<tt>pass <em>global-password</em></tt><br />
<tt>ignore -<em>options</em> <em>global-ignore</em></tt><br />
<tt>server <em>url</em></tt><br />
<tt>*chan <em>channel-on-that-server</em></tt><br />
<tt>>log <em>logtype-for-that-channel</em> <em>logfile-for-that-channel</em></tt><br />
<tt>*nick <em>nick-on-that-server</em></tt><br />
<tt>*pass <em>password-for-that-server</em></tt><br />
<tt>*ignore -<em>options</em> <em>ignore-on-that-server</em></tt><br />
where the <em>options</em> to [*]ignore are those for the /ignore command (except for l and d), and must not be separated by whitespace. You can however combine options, like <small>-ipr</small>. The <em>options</em> may not be omitted; if none are required, use <small>-</small> (dash).<br />
The logfile (for >log) is relative to <small>~/.quirc/</small>, as with the /log command.</p>
<p>Set the maximum length of nick that will be displayed, with lines<br />
<tt>mnln <em>maxnicklen</em></tt></p>
<p>You can also set mirc-colour-compatibility, with<br />
<tt>mcc <em>mcc-level</em></tt><br />
where 0 doesn't scan for mirc-colours, 1 silently strips them out, and 2 displays the appropriate colour. The default is mcc 1.</p>
<p>The size of each scrollback buffer, in lines, can be set with<br />
<tt>buf <em>buf-lines</em></tt><br />
the default being 1024. Larger values will, of course, increase memory consumption.</p>
<p>You can turn on a few display options too;<br />
<tt>fwc</tt><br />
<tt>hts</tt><br />
<tt>tsb</tt><br />
<tt>quiet</tt><br />
will turn on Full-Width-Colour (makes coloured backgrounds for lines (eg. /me) run all the way across the terminal), Highlight-Tab-Strip (gives the tab strip a magenta background, to make it more visible), Top-Status-Bar (uses the top line of the terminal for some status information), and Quiet Mode (many informational messages, including unrecognised IRC traffic, are suppressed). To turn them off prefix them with <small>no-</small>, like<br />
<tt>no-hts</tt><br />
By default fwc, hts and quiet are turned off; tsb is turned on.</p>
<p>You can control the timestamping settings:<br />
<tt>ts <em>ts-level</em></tt><br />
<tt>utc</tt><br />
<tt>its</tt><br />
The timestamping levels are:
<table><tr><td style="padding-left:1em;padding-right:1em;">ts-level</td><td>Meaning</td></tr>
<tr><td style="text-align:center;">0</td><td>No timestamps will be displayed</td></tr>
<tr><td style="text-align:center;">1</td><td>Display timestamps in the form [HH:MM]</td></tr>
<tr><td style="text-align:center;">2</td><td>Display timestamps in the form [HH:MM:SS]</td></tr>
<tr><td style="text-align:center;">3</td><td>Display timestamps in the form [HH:MM:SS +hhmm], where <em>+hhmm</em> is the time zone offset</td></tr>
<tr><td style="text-align:center;">4</td><td>Display timestamps in the form [Day. HH:MM:SS], where <em>Day</em> is the day of the week</td></tr>
<tr><td style="text-align:center;">5</td><td>Display timestamps in the form [Day. HH:MM:SS +hhmm]</td></tr>
<tr><td style="text-align:center;">6</td><td>Pointlessly, display timestamps as seconds since the Epoch</td></tr>
</table>
If <small>utc</small> is enabled, timestamps will be displayed as UTC instead of local time, and <em>+hhmm</em> will be replaced by <em>UTC</em>.<br>
If <small>its</small> is enabled, a clock will be displayed at the left-hand end of the input line, using the format specified by the current <small>ts</small> setting.<br>
The default setting is ts-level 1, no-utc, no-its.</p>
<p>These settings and others can be overridden at runtime with commandline options. For details run "quirc --help".</p>
<p>You can also customise the colours quIRC uses. A custom colour line starts with '%', followed optionally by 'S' or 'R' (only use this colour when Sending or Receiving respectively), followed by an identifier, then space or tab, then four space-separated numbers. Like this:<br />
<tt>%[S|R]<em>ident</em> <em>fore</em> <em>back</em> <em>hi</em> <em>ul</em></tt></p>
<p>Fore and Back set the foreground and background colours (8 colours each, red=4 green=2 blue=1, add for mixtures, eg white=7). Hi sets bright, Ul sets underline; both are true if nonzero.</p>
<p><em>ident</em> can be any of</p>
<dl>
<dt>msg</dt>
<dd>Ordinary messages</dd>
<dt>notice</dt>
<dd>Notices</dd>
<dt>join</dt>
<dd>Channel-Join notifications</dd>
<dt>part</dt>
<dd>Channel-Leave notifications</dd>
<dt>quit</dt>
<dd>Quit-messages</dd>
<dt>nick</dt>
<dd>Nick-change notifications</dd>
<dt>act</dt>
<dd>Actions ('/me does something')</dd>
<dt>status</dt>
<dd>status messages</dd>
<dt>err</dt>
<dd>error messages</dd>
<dt>unk</dt>
<dd>Unknown commands (splurged to output)</dd>
<dt>unn</dt>
<dd>Unknown numerics (splurged to output)</dd>
</dl>
</div><!--#configuration-->
<div id="inputcontrols">
<h2>Input controls</h2>
<p>These are based, broadly, on <small>bash</small>'s controls.</p>
<dl>
<dt>Up/Down/PgUp/PgDn</dt>
<dd>Read lines from the input history. History is local to the current tab.</dd>
<dt>Left/Right</dt>
<dd>Move the cursor within the current input line.</dd>
<dt>Home</dt>
<dt>Ctrl-A</dt>
<dd>Move the cursor to the beginning of the input line.</dd>
<dt>End</dt>
<dt>Ctrl-E</dt>
<dd>Move the cursor to the end of the input line.</dd>
<dt>Ctrl-C</dt>
<dd>Clear the input line.</dd>
<dt>Ctrl-X</dt>
<dd>Clear everything to the left of the cursor.</dd>
<dt>Ctrl-K</dt>
<dd>Clear everything to the right of the cursor.</dd>
<dt>Tab</dt>
<dt>Ctrl-I</dt>
<dd>Autocomplete the nickname or command to the left of the cursor.</dd>
<dt>Ctrl-H</dt>
<dt>Backspace</dt>
<dd>Delete the character to the left of the cursor.</dd>
<dt>Ctrl-W</dt>
<dd>Delete the word to the left of the cursor. Words are delimited only by spaces.</dd>
</dl>
</div><!--#inputcontrols-->
<div id="othercontrols">
<h2>Other controls</h2>
<dl>
<dt>Ctrl-Up</dt>
<dt>Ctrl-Down</dt>
<dd>Scroll the current buffer a line at a time.</dd>
<dt>Ctrl-PgUp</dt>
<dt>Ctrl-PgDn</dt>
<dd>Scroll the current buffer a page at a time.</dd>
<dt>Ctrl-Home</dt>
<dd>Scroll to the top of the current buffer.</dd>
<dt>Ctrl-End</dt>
<dd>Scroll to the bottom of the current buffer.</dd>
<dt>Ctrl-left</dt>
<dt>Ctrl-right</dt>
<dd>Change tab.</dd>
<dt>F1 through F12</dt>
<dd>Equivalent to <small>/tab <em>#</em></small>, except that F12 is /tab 0.</dd>
</dl>
</div><!--#othercontrols-->
<div id="keymapping">
<h2>Keymapping</h2>
<p>quIRC's mapping of function and other special keys is derived from <strong>terminfo</strong>, so it's important to set your <small>$TERM</small> correctly. For a few key chords that don't have <strong>terminfo</strong> bindings, it defaults to a VT100 mapping, such as used by <small>xterm</small> and <small>rxvt</small>. However, this mapping can be changed with a file <small>/home/<em>username</em>/.quirc/keys</small>.</p>
<p>To change key mappings, add lines of the form <small><em>MODNAME</em> <em>hex</em></small>. The <em>MODNAME</em>s expected are those which appear in the "<small>keys</small>" file in the quIRC source directory.<br />
The prefix 'C' refers to Ctrl, 'S' to Shift, and 'A' to Alt.</p>
<p>If, for instance, your terminal sends Ctrl-Left as ^[OD, you would add the following line:<br />
<tt>CLEFT 1b4f44</tt><br />
Similarly, if your terminal sends backspace as ^H, you would add:<br />
<tt>BS 08</tt></p>
<p>You can find out what sequences your terminal sends for various keys by running a hex-dump program such as <small>xxd</small> or <small>hd</small>, pressing the key, and noting the output. <em>(You will usually need to press first the key, then enter/return, then ^D)</em></p>
</div><!--#keymapping-->
<div id="tabstrip">
<h2>Tab strip</h2>
<p>The strip of tabs along the bottom of the screen has various indicators.</p>
<p>The parens bracketing the name tell you what kind of tab it is:</p>
<dl>
<dt>()</dt><dd>status</dd>
<dt>{}</dt><dd>server</dd>
<dt>[]</dt><dd>channel</dd>
<dt><></dt><dd>nick (private messaging)</dd>
</dl>
<p>The background colour is green for the current tab, and blue for the current tab's parent server (if applicable).</p>
<p>The foreground colour of tabs other than the current tab will turn red to indicate that there are new messages on that tab (and flash cyan if a message contains your nick). If a tab is 'dead' (eg. disconnected from server), it turns yellow.</p>
</div><!--#tabstrip-->
<div id="trouble">
<h2>Troubleshooting</h2>
<dl>
<dt>I get several copies of the status line scrolling up my screen!</dt>
<dd><p>One possible cause of this is that your terminal size is not what quIRC thinks it is. You may need to /set height and width, or export the environment variables $LINES and $COLUMNS from your shell (typically you would also add this to your shell's .rc file), or as a last resort resize your terminal to 80x24.</p><p>Another possibility is that your terminal emulator isn't recognising terminal escape sequences (which quIRC uses heavily for eg. cursor positioning). For details see your terminal emulator's documentation; it is known that xterm works out-of-the-box. In general quIRC relies on your system's <strong>terminfo</strong> database; if this is inaccurate, or your <small>$TERM</small> is set incorrectly, quIRC will be sending the wrong escape sequences.</p></dd>
<dt>The control keys/cursor keys/function keys don't do anything!</dt>
<dd>This probably means your terminal isn't sending VT100 (ANSI) escape sequences, but rather some other set of sequences. See the section "<a href="#keymapping">Keymapping</a>", above.</dd>
<dt>I can't build it! My libc doesn't support getaddrinfo_a()!</dt>
<dd><p>You need to disable ASYNCH_NL; <small>cp dist/config.mak .</small> (unless you already have a config.mak) and then uncomment the relevant lines.</p>
<p>This should disable asynchronous name lookups, instead using code which will block while performing the DNS lookup.</p></dd>
<dt>I can't build it! My compiler complains about %jd and intmax_t!</dt>
<dd><p>This is a known bug in some compiler/libc combinations; to work around it you need to define INTMAX_BUG to 1. <small>cp dist/config.mak .</small> (unless you already have a config.mak) and then uncomment the relevant lines.</p>
<p>This should work around the bug by using %lld and (long long int) instead of %jd and (intmax_t). Since what we're actually printing is a time_t, this ought to work.</p></dd>
</dl>
</div><!--#trouble-->
</body>
</html>