| 1 | The yrc manual |
| 2 | |
| 3 | Version 97 Kelvin |
| 4 | Jacob Welsh |
| 5 | |
| 6 | Table of Contents |
| 7 | 1 About yrc |
| 8 | 2 Display |
| 9 | 3 Commands |
| 10 | 3.1 Slash commands |
| 11 | 3.2 Keyboard commands |
| 12 | 3.2.1 Anywhere |
| 13 | 3.2.2 In the window list |
| 14 | 3.2.3 At the prompt |
| 15 | 3.2.4 In the scrollback window |
| 16 | 4 Configuration |
| 17 | 4.1 Keys |
| 18 | 4.2 Logging |
| 19 | 4.3 Example |
| 20 | 5 Roadmap |
| 21 | 6 Notes |
| 22 | |
| 23 | 1. About yrc |
| 24 | |
| 25 | yrc is a text-based, screen-oriented Internet Relay Chat (IRC) client providing a vital dose of simplicity in a computing world drowning in complexity. There are certain things that just shouldn't have bugs, and in the author's opinion, chat programs are among them. |
| 26 | |
| 27 | Simple does not necessarily mean "user-friendly" in the sense that you can expect to operate it without reading this manual. It does mean the literate operator should be able to read and comprehend the manual in an hour or two, and on this basis to fully grasp the workings of the program with a little practice. |
| 28 | |
| 29 | For yrc to achieve its goals, the following decisions were made: |
| 30 | |
| 31 | 1. High-level language implementation. In a network-exposed, not performance-critical application, there's just no excuse for the possibility of invoking Undefined Behavior and the ensuing vulnerabilities. |
| 32 | |
| 33 | 2. Simple configuration mechanism employing the filesystem as a hierarchical key-value database; no structured format to parse. [1] |
| 34 | |
| 35 | 3. Support exclusively VT100-compatible terminals on Unix-like systems. |
| 36 | |
| 37 | 4. No dependencies besides POSIX. [2] |
| 38 | |
| 39 | 5. No superfluous features such as mIRC colors, DCC or CTCP. [3] |
| 40 | |
| 41 | 6. No Unicode or any other flavor of hieroglyphs. Control and 8-bit characters in any IRC string are sanitized on display, both to protect the terminal and show the operator exactly what he is receiving. [4] |
| 42 | |
| 43 | 7. No SSL/TLS/TLS_1.3/whatever-they're-calling-it-today. [5] |
| 44 | |
| 45 | It does support several niceties: |
| 46 | |
| 47 | 1. Multiple message windows (separated channels/conversations) |
| 48 | |
| 49 | 2. Maintenance of connections to multiple networks, defined either by configuration or on the fly |
| 50 | |
| 51 | 3. Round-robin server balancing independent of DNS |
| 52 | |
| 53 | 4. Unlimited scrollback [6] |
| 54 | |
| 55 | 5. Basic authentication (the PASS command) |
| 56 | |
| 57 | 6. Sending raw commands to the IRC server for unsupported features |
| 58 | |
| 59 | 7. Communication of internal state to the operator: unread messages, connection state |
| 60 | |
| 61 | 8. Chat logging |
| 62 | |
| 63 | It is written in Python 2.7 (though this is an implementation detail and subject to change). Some of its more reusable terminal interface code is included as a separate "yterm" module. The yrc+yterm code weighs in around 2360 raw lines, compressing to 18KB. |
| 64 | |
| 65 | While source code is published freely, the project does not accept code contributions from unknown entities. |
| 66 | |
| 67 | 2. Display |
| 68 | |
| 69 | The yrc display is designed to maximize information and context available on a single screen, because eyes move faster than fingers. It has five parts: |
| 70 | |
| 71 | Title bar: shows a description of the current window, or the channel topic. |
| 72 | |
| 73 | Window list: an index of open windows (see below). |
| 74 | |
| 75 | Scrollback window: shows message history for a particular channel or private conversation, or server messages for a network, or general messages. |
| 76 | |
| 77 | Status bar: typically, shows the current nickname, network, and message target. |
| 78 | |
| 79 | Prompt: messages and commands are typed here. |
| 80 | |
| 81 | The window list is kept in alphabetical order, grouped by network, after the general messages window "yrc". An asterisk (*) in the first column indicates the currently selected window and a hyphen (-) the previous. Unread messages are indicated by a +N after the window name, where N is the number unread. A network's connection state is indicated by a symbol in front of its name, as follows: |
| 82 | |
| 83 | Blank: Not connected |
| 84 | |
| 85 | Tilde (~): Connection down: awaiting TCP handshake completion, or connection lost and waiting to reconnect |
| 86 | |
| 87 | Hyphen (-): TCP connection established but not registered to the server |
| 88 | |
| 89 | Equals (=): Fully registered; clear to send messages |
| 90 | |
| 91 | 3. Commands |
| 92 | |
| 93 | yrc is controlled using _slash commands_ and _keyboard commands_. Slash commands are entered at the prompt by starting the line with the forward "/" character. Most can be given as abbreviations, as indicated below. Some take one or more space-delimited arguments. To send a line starting with a slash as a normal message, use two slashes. Keyboard commands are invoked by typing special keys or key combinations. |
| 94 | |
| 95 | For interactive use, the phrases "current network" or "current channel" mean the network or channel of the currently selected window. For scripts (not yet implemented), they mean the network or channel under which the script is configured. |
| 96 | |
| 97 | 3.1. Slash commands |
| 98 | |
| 99 | [c]onnect NETWORK [HOST[:PORT] [NICK [PASS]]] |
| 100 | |
| 101 | Connect to NETWORK, either preconfigured or with the given parameters. |
| 102 | |
| 103 | [d]isconnect [NETWORK] |
| 104 | |
| 105 | Disconnect from NETWORK or the current network, or cancel a reconnection attempt. |
| 106 | |
| 107 | [j]oin CHANNEL [KEY] |
| 108 | |
| 109 | Join a channel on the current network. |
| 110 | |
| 111 | [k]ick USER [MESSAGE] |
| 112 | |
| 113 | Kick a user from the current channel. |
| 114 | |
| 115 | [l]ist [CHANNEL] |
| 116 | |
| 117 | Request a list of channels and topics, or the status of a given channel, on the current network. |
| 118 | |
| 119 | me MESSAGE |
| 120 | |
| 121 | Send MESSAGE as a CTCP ACTION (rendered by many clients in an alternate style showing the nickname as the start of a sentence). |
| 122 | |
| 123 | [m]ode MODE {[CHANNEL] | NICK [CHANNEL]} |
| 124 | |
| 125 | [TODO; uncertain...] Set a mode on CHANNEL or the current channel, or a user mode on NICK in CHANNEL or the current channel. |
| 126 | |
| 127 | msg {CHANNEL | NICK} [MESSAGE] |
| 128 | |
| 129 | Switch to the window for CHANNEL or NICK on the current network, creating one if needed, and send the given MESSAGE, if any. (This does not join a channel; messages to an unjoined channel might be rejected by the server.) |
| 130 | |
| 131 | [na]mes [CHANNEL] |
| 132 | |
| 133 | Request the list of names in the given channel, or all visible channels and users on the current network. |
| 134 | |
| 135 | [n]ick NICK |
| 136 | |
| 137 | Temporarily change nickname on the current network (persists across reconnections but not new connections). |
| 138 | |
| 139 | [p]art [PART_MESSAGE] |
| 140 | |
| 141 | Leave the current channel, keeping its window open. |
| 142 | |
| 143 | [q]uit [QUIT_MESSAGE] |
| 144 | |
| 145 | Disconnect from all networks and quit yrc. |
| 146 | |
| 147 | [s]end COMMAND |
| 148 | |
| 149 | Send a raw IRC command to the server for the current network. |
| 150 | |
| 151 | [st] set-topic TOPIC |
| 152 | |
| 153 | Set the topic for the current channel to TOPIC. |
| 154 | |
| 155 | [t]opic [CHANNEL] |
| 156 | |
| 157 | Get the topic for the current channel or the given channel on the current network. |
| 158 | |
| 159 | [w]hois NICK |
| 160 | |
| 161 | Request information on a user on the current network. |
| 162 | |
| 163 | [ww] whowas NICK |
| 164 | |
| 165 | Request cached information for a disconnected user on the current network. |
| 166 | |
| 167 | [x] close |
| 168 | |
| 169 | Close the current window, parting with no message if it is a channel. |
| 170 | |
| 171 | [xn] close-net (TODO) |
| 172 | |
| 173 | Disconnect and close all windows for the current network. |
| 174 | |
| 175 | 3.2. Keyboard commands |
| 176 | |
| 177 | In the Emacs tradition, C- means to hold Ctrl, and M- means to hold Alt (Meta). |
| 178 | |
| 179 | Some commands are multi-key sequences beginning with C-x. For these, you can either continue holding Ctrl or not. That is, C-x n is equivalent to C-x C-n. If necessary, an Alt combination can be emulated by pressing (not holding) Esc followed by the letter. Key sequences in progress are indicated in the status bar and can be cancelled with C-g. |
| 180 | |
| 181 | Each keyboard command has an associated name (used internally for key mapping and perhaps a future scripting feature). The mapping of some keys to commands depends on which part of the interface is focused. Most commands have multiple keybindings, providing a choice of Emacs, vi, or dedicated key styles. To become a more productive Unix user, it can't hurt to learn them all! |
| 182 | |
| 183 | 3.2.1. Anywhere |
| 184 | |
| 185 | C-x n: buflist-switch-next |
| 186 | |
| 187 | Switches to the next scrollback window in the list. |
| 188 | |
| 189 | C-x p: buflist-switch-prev |
| 190 | |
| 191 | Switches to the previous scrollback window in the list. |
| 192 | |
| 193 | C-x l: buflist-last-selected |
| 194 | |
| 195 | Switches to the previously active scrollback window. |
| 196 | |
| 197 | C-x w: buflist-enter |
| 198 | |
| 199 | Moves focus to the window list (see 3.2.2). |
| 200 | |
| 201 | C-l: redraw |
| 202 | |
| 203 | Performs a full redraw of the screen, e.g. in case of corruption from the output of another program. |
| 204 | |
| 205 | 3.2.2. In the window list |
| 206 | |
| 207 | C-n, j, Down: buflist-next |
| 208 | |
| 209 | Moves the cursor to the next entry in the window list. |
| 210 | |
| 211 | C-p, k, Up: buflist-prev |
| 212 | |
| 213 | Moves the cursor to the previous entry in the window list. |
| 214 | |
| 215 | h, Left: buflist-shrink |
| 216 | |
| 217 | Reduces window list width. |
| 218 | |
| 219 | l, Right: buflist-grow |
| 220 | |
| 221 | Increases window list width. |
| 222 | |
| 223 | M-<, g, Home: buflist-top |
| 224 | |
| 225 | Moves the cursor to the top of the window list. |
| 226 | |
| 227 | M->, G, End: buflist-bottom |
| 228 | |
| 229 | Moves the cursor to the bottom of the window list. |
| 230 | |
| 231 | Return (C-m): buflist-submit |
| 232 | |
| 233 | Activates the selected scrollback window and returns focus to where it was. |
| 234 | |
| 235 | 3.2.3. At the prompt |
| 236 | |
| 237 | Return (C-m): prompt-submit |
| 238 | |
| 239 | Submits the message or command given at the prompt. |
| 240 | |
| 241 | Ins: prompt-exit |
| 242 | |
| 243 | Moves focus to the scrollback window (see 3.2.4). |
| 244 | |
| 245 | C-f, Right: prompt-forward |
| 246 | |
| 247 | Moves the cursor forward by one character. |
| 248 | |
| 249 | C-b, Left: prompt-backward |
| 250 | |
| 251 | Moves the cursor backward by one character. |
| 252 | |
| 253 | C-a, Home: prompt-start |
| 254 | |
| 255 | Moves the cursor to the start of the line. |
| 256 | |
| 257 | C-e, End: prompt-end |
| 258 | |
| 259 | Moves the cursor to the end of the line. |
| 260 | |
| 261 | Backspace (C-h, C-?): prompt-backspace |
| 262 | |
| 263 | Deletes backward by one character. |
| 264 | |
| 265 | C-d, Del: prompt-delete |
| 266 | |
| 267 | Deletes forward by one character. |
| 268 | |
| 269 | C-v, PgDn: scroll-down-page |
| 270 | M-v, PgUp: scroll-up-page |
| 271 | |
| 272 | Scrolls the active scrollback window (see 3.2.4). |
| 273 | |
| 274 | 3.2.4. In the scrollback window |
| 275 | |
| 276 | If the window is scrolled to the bottom (the last available message is fully visible), it will autoscroll as new messages arrive. |
| 277 | |
| 278 | i, Ins: prompt-enter |
| 279 | |
| 280 | Moves focus to the prompt (see 3.2.3). |
| 281 | |
| 282 | C-v, C-f, f, PgDn, Space: scroll-down-page |
| 283 | M-v, C-b, b, PgUp: scroll-up-page |
| 284 | |
| 285 | Scrolls the window down or up by a page. The current implementation is fairly stupid and scrolls by half a page worth of messages, ignorant of wrapping. |
| 286 | |
| 287 | C-n, j, Down: scroll-down-line |
| 288 | C-p, k, Up: scroll-up-line |
| 289 | |
| 290 | Scrolls the window down or up by one message. |
| 291 | |
| 292 | M-<, g, Home: scroll-top |
| 293 | M->, G, End: scroll-bottom |
| 294 | |
| 295 | Scrolls to the top or bottom. |
| 296 | |
| 297 | 4. Configuration |
| 298 | |
| 299 | As mentioned above, yrc is configured using the filesystem as a key-value store. The config tree is rooted at ~/.yrc (the hidden directory ".yrc" under your home directory), known as the yrc home. Each config key is represented by a text file; trailing linefeeds are stripped. |
| 300 | |
| 301 | Under the yrc home may be a "nets" subdirectory. IRC networks are defined by creating further subdirectories under "nets" with names of your choice; these names are used for NETWORK in the yrc commands. |
| 302 | |
| 303 | 4.1. Keys |
| 304 | |
| 305 | The following keys may be defined at top level (directly in the yrc home) or per network, with network level taking precedence. |
| 306 | |
| 307 | addrs -- one or more server addresses (required) |
| 308 | nick -- initial IRC nickname (required) |
| 309 | pass -- plain-text password to send on connect |
| 310 | |
| 311 | Addresses are specified one per line as either hostname or IPv4 address optionally followed by ":" and port number. Lines starting with the "#" character are ignored. Per common practice, the default port is 6667. On initial connection to a network, a server is selected at random; subsequent reconnections by the same process rotate sequentially through the list. |
| 312 | |
| 313 | 4.2. Logging |
| 314 | |
| 315 | A "logs" tree is created automatically under the yrc home with subdirectories for each network. Messages associated with chats are appended to log files under these, named by VENUE.log where VENUE is the channel name or correspondent nick, casefolded and %-encoded for problematic characters. [7] To suppress logging for a particular entity, you could symlink its log file to /dev/null. |
| 316 | |
| 317 | yrc behaves as if each log file is opened fresh on each write, in the sense that deleting, truncating, renaming or linking log files works immediately and as expected. [8] yrc attempts to write each message with a single system call, so concurrent processes should be safe, though not recommended. |
| 318 | |
| 319 | The log format, designed for a degree of human and machine readability, is one message per line with the following single-space-delimited fields: |
| 320 | |
| 321 | timestamp -- decimal integer, centiseconds since the epoch |
| 322 | type -- mostly matching the IRC protocol but with some variation; consult the "message" variant type in yrc.py for details |
| 323 | sender -- quoted in <angle brackets> for aesthetics |
| 324 | content -- running to end of line |
| 325 | |
| 326 | Note that unlike in the UI, message content is not escaped; the only characters excluded by protocol are ASCII NUL, CR and LF. Thus printing a log directly to terminal (as opposed to using an editor or "less") can cause unexpected and possibly dangerous behavior. |
| 327 | |
| 328 | 4.3. Example |
| 329 | |
| 330 | An example tree, including some planned keys not yet implemented: |
| 331 | |
| 332 | ~/.yrc |
| 333 | |-- nets |
| 334 | | |-- net1 |
| 335 | | | |-- auto |
| 336 | | | |-- addrs |
| 337 | | | |-- nick |
| 338 | | | |-- pass |
| 339 | | | |-- chans |
| 340 | | | | `-- #somechan |
| 341 | | | | |-- auto |
| 342 | | | | `-- key |
| 343 | | | `-- contacts |
| 344 | | | `-- buddy |
| 345 | | `-- net2 |
| 346 | | `-- addrs |
| 347 | |-- nick |
| 348 | |-- realname |
| 349 | |-- user |
| 350 | `-- logs |
| 351 | |-- net1 |
| 352 | | |-- buddy.log |
| 353 | | `-- #channel.log |
| 354 | `-- net2 |
| 355 | `-- 1337%2Fhax0r%0A.log |
| 356 | |
| 357 | 5. Roadmap |
| 358 | |
| 359 | High-priority missing features: |
| 360 | |
| 361 | - Prompt history, kill/yank commands |
| 362 | - Indication of nick mentions (ring bell + bold the window name?) |
| 363 | - Tab completion (nicks, slash commands) |
| 364 | - Formatting for displayed messages (e.g. bold sender, highlight own nick) |
| 365 | - Finish mode/op and close-net commands |
| 366 | - Filtering of inbound PMs (/ignore or similar) |
| 367 | - Scrolling based on rendered lines rather than messages |
| 368 | - Scrolling + more efficient navigation of window list |
| 369 | |
| 370 | Nice to have: |
| 371 | |
| 372 | - Search in scrollback |
| 373 | - Nickname fallback |
| 374 | - Online /help command |
| 375 | - Auto-connect/join or scripting |
| 376 | - Parse WHOIS/WHOWAS/LIST responses |
| 377 | - Bracketed paste [meh, not all it's cracked up to be] |
| 378 | - Date change messages |
| 379 | - Channel join status indicators |
| 380 | - Finish config fields [?] |
| 381 | |
| 382 | 6. Notes |
| 383 | |
| 384 | [1] Inspired by DJB software, http://cr.yp.to/. |
| 385 | |
| 386 | [2] Not even "ncurses", a lesson learned from the first implementation. It's a mess. |
| 387 | |
| 388 | [3] With the possible exception of CTCP ACTION (the /me command) due to its popularity. |
| 389 | |
| 390 | [4] Contrary to presently popular opinion, this does not preclude non-English communication. It's simpler, and probably healthier, for people to learn "pinyin"/transliteration systems to a single alphabet, than to have every program pretend to support some Consortium's never-finished Babel of an infinite alphabet and all the related landmines. Double-width characters in fixed-width fonts; bidirectionality; combining ligatures, diacritics, and canonicalization thereof; surrogate escapes; multiple types of spaces; characters that look the same but aren't; non-standard private mappings; variable length encodings; byte orderings; decode error handling; glyph substitution because no single font designer can hope to provide complete coverage... are you scared yet? |
| 391 | |
| 392 | [5] Historically it's had more holes than Swiss cheese -- in design, in every major implementation -- and there's no cause to imagine that just one more patch release will fix everything. Use good cryptography if you need it, and stop deluding yourself otherwise. |
| 393 | |
| 394 | [6] Well, limited by your available memory. It would take a very busy channel indeed to make a serious dent in today's memory sizes, but in such a case, you can reclaim memory by closing its specific window from time to time. |
| 395 | |
| 396 | [7] Control and 8-bit characters plus ".", "/" and "%"; this does not include various shell metacharacters. |
| 397 | |
| 398 | [8] Currently this is in fact the implementation, which may result in interface lag e.g. on network filesystems. FD caching or a separate log thread are possible remedies if anyone cares. |