The KSirc Handbook
 

The KSirc Handbook

Andrew Stanley-Jones <asj@chowtown.cban.com>

Philip Rodrigues <phil.rod@ntlworld.com>

Revision 1.02.01 (2002-04-17)

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".

This documentation describes KSirc 1.2.1, the KDE IRC client.


Chapter 1. Introduction
 

Chapter 1. Introduction

KSirc is the default KDE IRC client. It supports scripting with Perl and has a lot of compatibility with mIrc for general use.

Chapter 2. Using KSirc
 

Chapter 2. Using KSirc

If you haven't used IRC before...

Simply put, IRC is a chat protocol, defined by official Internet standards, and capable of stealing many hours of your life. To use IRC, you must connect to a server, and then join a channel (equivalent to a chat room).

To connect to a server, open KSirc and select Connections->New Server... or press F2. In the dialog box that is displayed, select a group from the leftmost drop-down box and then a server from the middle drop-down box. The port, shown on the right, will almost always be 6667. A new window will be displayed showing the messages sent by the server to the client. When these messages have finished scrolling past, you want to choose your channel. To display a list of available channels, type /list. To join a channel, type: /join #channelname. To leave a channel, just type /part.

That's the basics, for more detailed information, read on...

KSirc Basics
 

KSirc Basics

Servers

KSirc allows you to connect to an arbitrary number of servers. To connect to a server, select Connections->New Server or press F2.The Connect to Server Dialog appears, and you can select a Group, then a Server, and also a Port to connect to.

Just click Connect when you're done, and a new window for the server is displayed. You can keep track of the servers you're connected to in the KSirc Server Control window.

You can get help on most IRC commands by typing /help commandname. Typing /help on its own gives a list of available commands.

Channels

You can connect to channels with the normal IRC command /join #channelname , by selecting Connections->Join Channel... or by pressing F3.

Channels you are connected to are shown in the Server Control window under the server to which the they belong. To leave a channel, you can /part, select Channel->Close or press Ctrl+W.

Channel Options

The Channel menu, available in any channel window, contains some useful options:

Save to Logfile... (Ctrl-S)

Saves the contents of the channel to a file.

Time Stamp

If selected, prepends each thing said in the channel with the time it was said, in the form [HH:MM:SS]

Ascii Table (Alt C T)

Displays a table of Ascii characters, from which you can choose any characters you require.

Beep on Change (Alt C P)

If selected, KSirc emits a beep every time something is said on a channel.

User Options

In a channel, the user list is displayed along the right hand side. Right-clicking a nickname in that list gives you a pop-up menu of options, most of which are self-explanatory:

Refresh Nicks

Sends a message to the server to request the list of users in the channel. This ensures that the list of nicknames is up-to-date.

Follow

Follows the user into whatever channels he goes to.

unFollow

Stops following the user.

Whois

Sends a CTCP whois query to the user, which provides information about the user, such as his hostname and what server he is connected to.

Ping

Sends a CTCP ping request to the user, to determine his echo time.

Version

Sends a CTCP version request to the user, to determine what software he is using.

Abuse

Abuses the user in one of various amusing ways.

The following commands are only available if you are an operator on the channel:

Kick

Removes the user off the channel.

Ban

Bans the user from joining the channel.

unBan

Removes the ban on the user joining the channel.

Op

Gives the user operator privileges.

DeOp

Removes operator privileges from the user.

Chapter 3. KSirc Configuration
 

Chapter 3. KSirc Configuration

Introduction to Configuration

The KSirc configuration dialog is available from Options->Preferences... in the KSirc Server Control window.

The General Tab
 

The General Tab

Window Mode

SDI Mode (old behavior)

Causes KSirc to use single document interface mode, in which each new channel or /query window has its own, separate window.

Pagebed MDI mode (XChat)

Causes KSirc to use multiple document interface mode, in the style of XChat, in which each new channel or /query window has a tab in one main KSirc window. Each tab can be brought to the front by clicking its tab, and you can switch tabs using Shift-Left Arrow and Shift-Right Arrow.

The Misc Configuration Section

Auto Create Window

If selected, KSirc will automatically create a new window for each user who sends a /msg command to you. If not selected, any text sent to you with /msg is displayed in the current window and you can use /query username to create a window to chat to that user.

Nickname Completion

If selected, switches nickname completion on. Nickname completion works as follows:

  1. Type the first letters of a user's nickname.

  2. Press TAB. The text you typed will be completed to match the username, including changes in capitalization if necessary. e.g. phi<TAB> becomes PhilRod if there is a user called “PhilRod” on the channel.

  3. If more than one user's nickname on the channel matches the text you have typed, the first name in the list is chosen. Pressing TAB subsequent times displays the next nickname in the list. For example, if there are users “PhilA” and “PhilRod” on a channel, and you type phi<TAB>, the text will first be completed to PhilA, and if you press TAB again, it will change to PhilRod.

Display topic in caption

Displays the topic of the current channel in the window caption. If not selected, the topic is only displayed inside the window.

Time Stamp

Prepends each thing said in the channel with the time it was said, in the form [HH:MM:SS].

Beep on Notify

If selected, a system beep will be generated whenever a user on your /notify list signs onto the IRC server you are on.

Color Picker Popup

If selected, a popup window from which to select the color of your text is presented when you press Ctrl+K. If not, you have to type the color codes manually. See also Chapter 4.

Auto Rejoin

Rejoins channels automatically if you are disconnected.

History Length

Stores up to this many lines of chat from each window, allowing you to scroll upwards and see what has already been said.

Wallpaper Configuration

In the Wallpaper section, you can change the image placed in the background of your KSirc windows. You can enter the name of the file to use in the text box, or browse for files using the button to the right of the textbox. Image files used must be in GIF, JPEG or PNG format. A preview of the image is shown at the right of the dialog box.

The Startup Tab
 

The Startup Tab

Here you can configure KSirc's startup settings.

Name Settings

Nick Name

Set your IRC nickname.

Alternative Nick

Set the nickname to use if your first choice is already in use by another user.

Real Name

Your real name, as returned by a /whois query on you.

Notify List

Here you can enter a list of users who you want added to your /notify list at startup. You will be alerted when each of the users in the list is online.

The Colors Tab
 

The Colors Tab

Here you can configure KSirc's use of color.

Chat colors Configuration

Here you can set colors for each of the types of text. Clicking the color button to the right of each text type's label will display a color selector box in which you can choose the color in which you want this type of text to be displayed.

Nick Colors

Foreground: and Background: set the colors for the foreground and background of users' nicknames in chat windows. The Color for messages containing your nick: option sets the color for any message appearing in a channel which contains your nickname.

Color codes

Here you can set whether KSirc allows native color codes (see Chapter 4) and also whether mIrc color codes are allowed.

Chapter 4. KSirc Colors
 

Chapter 4. KSirc Colors

KSirc follows the color scheme used by mIrc and a slight modification for more powerful in house use.

<fg> == foreground
<bg> == background
[] == optional

mIrc compatibility

Format:

  • 0x03<fg>[,<bg>] sets the foreground and background

  • 0x03 resets to defaults for that line

KSirc native
 

KSirc native

Format:

  • ˜<fg>[,<bg>] sets the foreground and background

  • ˜c resets to defaults

  • ˜b sets bold font

  • ˜u sets underline

  • ˜i sets italics

  • ˜r sets reverse video

Why did I change KSirc to use ˜ instead of 0x03 (Ctrl+C)? Well, it's hard to use 0x03 in scripts and not all C functions seem to like it. ˜letter also allows more commands while not stomping on mIrc's future changes.

Color Numbers
 

Color Numbers

  1. white

  2. black

  3. blue

  4. green

  5. red

  6. brown

  7. purple

  8. orange

  9. yellow

  10. lightGreen

  11. cyan

  12. lightCyan

  13. lightBlue

  14. pink

  15. gray

  16. lightGray

Sending Bold, Underline, Reverse, and Color
 

Sending Bold, Underline, Reverse, and Color

You can use the following key combinations to insert control codes in text:

  • Ctrl+B for bold text

  • Ctrl+U for underlined text

  • Ctrl+R for reverse text

  • Ctrl+K for colored text

  • Ctrl+O for plain text

Examples
 

Examples

To underline a single word in a sentence:

Procedure 4.1.

  1. Type Ctrl+U

  2. Type in the word

  3. Type Ctrl+U again

Only the text that is enclosed by the start and end codes will be affected. You can use this method with all of the other control codes.

The Ctrl+K control code is slightly different because it allows you to specify a color number. To color a single word in a sentence:

Procedure 4.2.

  1. Type Ctrl+K

  2. Type a number between 0 and 15

  3. Type the word

  4. Type Ctrl+K again

If you also want to change the background color of a word, you would need to type two numbers separated by a comma instead of just one number. The first number is the text color, the second number is the background color. The colors range from 0 to 15, the index is in the previous section.

You can enclose text in multiple control codes, so for example you could have a bold, underlined, and colored word.

Chapter 5. Filters
 

Chapter 5. Filters

Filter Rules and How to Make them

If you just can't figure it out, wait. I want to build a nice “filter builder” where you can just click your way through it. Though, it might be a while.

The filter tries to find the “match” string then use the “From” and “To” as a substitution. The match, from and to are all Perl regex expressions. Rules are evaluated in descending order. The top rule is evaluated first, then the second from the top, etc. All strings are evaluated as:

$name is expanded to the environment variable name. This is done immediately when you insert the rule, and will not change after that time. Therefore it's probably of limited value.

$$name is substituted with the Perl $name variable during the match. This can be substrings such as $1, $2 in the substitution, or normal variables available under sirc (such as $nick, $channel, etc.).

˜name˜ prepended once and only once to the line will send the line of text to the window called name. If the window does not exist it will go to the last window which had focus. There are several special windows, all prefixed by a single !:

!default

The current default window. Guaranteed to exist.

!all

Send to every window. This might not show up on all windows, depending on how the text is parsed. For example, channel windows won't show a /part or /quit unless the nickname is on the channel.

!discard

discards the text.

The rest of the expression is dealt with as normal Perl regex. A good understanding of the perlre man page will definitely help, but a basic understanding of regex is most certainly required.

Examples:
 

Examples:

  1. Want to convert all boren from boren to BoreN

    Match: .*
    From: boren
    To: BoreN

    Pretty straight forward, match anything, then substitute boren with BoreN.

  2. You want to match everything with boren in it and send to the window called “boren”

    Match: boren
    From: ^
    To: ˜boren˜

    Looks for “boren” if found, substitutes the beginning of the string (^) with ˜boren˜.

  3. Though the previous example works, if the string already has ˜somewindow˜ on it, you'll now have two ˜boren˜˜somewindow˜... So you can do this instead.

    Match: boren
    From: ^(?:˜\S+˜)
    To: ˜boren˜

    Ok, the from line is a little bit more complicated. It means: match 0 or 1 copies of ˜\S+˜. Which is 1 tilde, one or more non-whitespaces, and then another tilde. The paranoid might do (*:˜\S+˜), which means: match 0 or more channel directives in case prior rules are broken.

  4. Server kill messages tend to be long, ugly, annoying, etc. A basic message on dalnet looks like:

    *** Notice -- Received KILL message for
    BOBO!ANDY@line82-basel.datacomm.ch from NickServ
    Path: empire.ny.us.dal.net[209.51.168.14]!trapdoor.ca.us.dal.net
    [206.86.127.252]!caris.ca.us.dal.net[208.1.222.221]
    !services.dal.net[2008.1.222.222]!services.dal.net
    (NickServ Enforcement)

    When you're +s you get tons of them; you don't want all of them flying across your screen. I'm going to make 3 rules to deal with them one bit at a time. You could do it in less rules, but it'll show you the basic rule structure, in nice steps, and how to use multiple rules to parse a message. The first step is to remove the Path: portion of the message:

    Match: ^\*\*\*.* KILL message for.*
    From:  Path: \S+
    To: .

    Match looks for the message starting with ***, the *'s have to be quoted with \ since by themselves they mean 0 or more of the prior character. .* means: match anything until you find KILL message for. This allows us to avoid typing in -- Received... etc. The trailing .* means: match anything to the end of the line. (not needed, I think)

    The From line means: substitute " Path: " and any non-whitespace characters with the To. To is a "." therefore the entire path turns into a single period.

    The message now looks like:

    *** Notice -- Received KILL message for BOBO!ANDY@line82-basel.datacomm.ch
    from NickServ. (NickServ Enforcement)

    Notice the new "." after NickServ?

  5. Ok, the message is a lot cleaner, but KILLs from nickserv aren't really that important, so let's forward them to the !discard window.

    Match: ^\*\*\*.*KILL message.*\(NickServ Enforcement\)
    From: ^(?:˜\S+˜)
    To:  ˜!discard˜

    Match rule searches for the KILL message and makes sure it's from NickServ. Notice the \( and \) are both used in regex, therefore we have to quote them. This is very similar to what we said two examples before.

  6. We've now filtered out all the nickserv kills, but the message is still pretty hard to read by simply glancing at it. So let's reorder it to something like:

    *** [KILL] KILLER; killed KILLED; (REASON)
    Match: \*\*\*.*KILL message
    From: \*\*\*.*for (.*?) from (.*?)\. \((.*?)\).*
    To: *** [KILL] $$2 killed $$1 ($$3)
    

    Ok, the match looks for ***something KILL message. We can't use ^ since we may have just appended ˜<window>˜.

    The from line gets a little more interesting. The "for (.*?) " looks for the word "for" then some text. .*? means: match zero or more of anything except newline, but isn't greedy. The rule is to stop when the first terminating condition is found, not the last. In other words it matches anything until a space is encountered. The surrounding () means: save the contents. Each () saves the matched data in $# where # starts at 1 for the first substring, etc. In this case, $1 gets the nick/user-info of the person killed. $2 is then filled with the name of the killer. Between the () we have the reason for the kill. Here the ( and \( get a little confusing. Remember \( matches the actual character '('.

  7. How to colorize your life.

    Ok, you want to add some color to KSirc. See the Colors section for color info, but here's a filter rule to highlight the nickname between <NICK> on each line:

    Match: ^(?:˜\S+˜)<\S+>
    From: <(\S+)>
    To: <˜4$$1˜c>

    Takes the nickname and adds color #4 between the two <>. ˜c clears the color.

Chapter 6. Keys
 

Chapter 6. Keys

This is a listing of the shortcut and command keys available under KSirc.

Table 6.1. Keybindings

KeybindingAction
Ctrl+NOpen a new Channel/Query Window.
Ctrl+QQuit
Ctrl+EnterBegin a message to the most recent person to send you a message.
Ctrl+Shift+EnterBegin a message to the last-but-one person to send you a message.
Ctrl+KStart color code with a number. Text you type after this will be colored.
Ctrl+UBegin or end underlining text. Text after the first occurrence of this will be underlined until you type the shortcut again.
Ctrl+IBegin or end italic text. Text after the first occurrence of this will be italic until you type the shortcut again.
Ctrl+BBegin or end bold text. Text after the first occurrence of this will be bold until you type the shortcut again.
Ctrl+RBegin or end reverse video text. Text after the first occurrence of this will be reversed until you type the shortcut again.
TABTries to complete the nickname of someone on the channel, based on the text you entered. You are probably familiar with this from your commandline shell, although it does not necessarily work in exactly the same way. See Nickname Completion.
Chapter 7. Credits and Licenses
 

Chapter 7. Credits and Licenses

KSirc copyright 1997-2002, the KSirc developers.

Portions of documentation copyright 1997, Andrew Stanley Jones

Documentation updated for KDE 3.0 by Philip Rodrigues <phil.rod@ntlworld.com>

This documentation is licensed under the terms of the GNU Free Documentation License.

This program is licensed under the terms of the GNU General Public License.

Appendix A. Installation
 

Appendix A. Installation

Where to get KSirc

KSirc is part of the KDE project http://www.kde.org/.

KSirc can be found in the kdenetwork package on ftp://ftp.kde.org/pub/kde/, the main FTP site of the KDE project.

Compilation and Installation
 

Compilation and Installation

In order to compile and install KSirc on your system, type the following in the base directory of the KSirc distribution:

% ./configure
% make
% make install

Since KSirc uses autoconf and automake you should have no trouble compiling it. Should you run into problems please report them to the KDE mailing lists.