<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
  <!ENTITY mirc "<application>mIrc</application>">
  <!ENTITY kappname "&ksirc;">
  <!ENTITY package "kdenetwork">
  <!ENTITY irc "<acronym>IRC</acronym>">
  <!ENTITY CTCP "<acronym>CTCP</acronym>">
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE" > <!-- change language only here -->
]>
	
<book lang="&language;">

<bookinfo>
<title>The &ksirc; Handbook</title>
<authorgroup>
<author>
&Andrew.Stanley-Jones;
&Andrew.Stanley-Jones.mail;
</author>
<author>
&Philip.Rodrigues;
&Philip.Rodrigues.mail;
</author>
</authorgroup>

<copyright>
<year>1997</year>
<holder>Andrew Stanley-Jones</holder>
</copyright>

<copyright>
<year>2001</year><year>2002</year><year>2004</year>
<holder>
Philip Rodrigues
</holder>

</copyright>

<!-- TRANS:ROLES_OF_TRANSLATORS -->
<date>2004-02-06</date>
<releaseinfo>1.3.9</releaseinfo>

<legalnotice>&FDLNotice;</legalnotice>

<abstract>
<para>This documentation describes &ksirc; 1.2.1, the &kde; &irc;
client.</para>
</abstract>

<keywordset>
<keyword>KDE</keyword>
<keyword>KSirc</keyword>
<keyword>irc</keyword>
<keyword>Internet relay chat</keyword>
</keywordset>
</bookinfo>

<chapter id="introduction">
<title>Introduction</title>

<para>&ksirc; is the default &kde; &irc; client. It supports scripting
with <acronym>Perl</acronym> and has a lot of compatibility with &mirc;
for general use.</para>

</chapter>

<chapter id="using-ksirc">
<title>Using &ksirc;</title>

<sect1 id="irc-basics">
<title>If you haven't used &irc; before...</title>

<para>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).</para>

<para>To connect to a server, open &ksirc; and select
<menuchoice><guimenu>Connections</guimenu><guimenuitem>New
Server...</guimenuitem></menuchoice> or press <keycap>F2</keycap>. 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
<userinput><command>/list</command></userinput>. To join a channel,
type: <userinput><command>/join</command>
<replaceable>#channelname</replaceable></userinput>. To leave a channel,
just type <userinput><command>/part</command></userinput>.</para>

<para>That's the basics, for more detailed information, read
on...</para>

</sect1>

<sect1 id="ksirc-basics">
<title>&ksirc; Basics</title>

<sect2 id="servers">
<title>Servers</title>

<para>&ksirc; allows you to connect to any number of
servers. To connect to a server, select
<menuchoice><guimenu>Connections</guimenu><guimenuitem>New
Server</guimenuitem></menuchoice> or press <keycap>F2</keycap>.The
<guilabel>Connect to Server</guilabel> Dialog appears, and you can select a
<guilabel>Group</guilabel>, then a <guilabel>Server</guilabel>, and also
a <guilabel>Port</guilabel> to connect to.</para>

<para>Just click <guilabel>Connect</guilabel> 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; <guilabel>Server
Control</guilabel> window.</para>

<para>You can get help on most &irc; commands by typing <userinput>/help
<replaceable>commandname</replaceable></userinput>.
 Typing <userinput>/help</userinput> on its own gives a list of available
commands.</para>
</sect2>

<sect2 id="channels">
<title>Channels</title>

<para>You can connect to channels with the normal &irc; command
<userinput><command>/join</command> <replaceable>#channelname</replaceable>
</userinput>, by selecting
<menuchoice><guimenu>Connections</guimenu><guimenuitem>Join
Channel...</guimenuitem></menuchoice> or by pressing
<keycap>F3</keycap>.</para>

<para>Channels you are connected to are shown in the <guilabel>Server
Control</guilabel> window under the server to which the they belong. To
leave a channel, you can <userinput>/part</userinput>, select
<menuchoice><guimenu>Channel</guimenu><guimenuitem>Close</guimenuitem>
</menuchoice> or press <keycombo action="simul">&Ctrl;<keycap>W</keycap></keycombo>.</para>

</sect2>

<sect2 id="channel-options">
<title>Channel Options</title>

<para>The <guimenu>Channel</guimenu> menu, available in any channel
window, contains some useful options:</para>

<variablelist>

<varlistentry>
<term><menuchoice>
<shortcut><keycombo>&Ctrl;<keycap>S</keycap>
</keycombo></shortcut>
<guimenuitem>Save to Logfile...</guimenuitem>
</menuchoice></term>
<listitem>
<para><action>Saves the contents of the channel to a
file.</action></para>
</listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenuitem>Time Stamp</guimenuitem>
</menuchoice></term>
<listitem>
<para><action>If selected, prepends each thing said in the channel with the
time it was said, in the form [HH:MM:SS]</action></para>
</listitem>
</varlistentry>

<varlistentry>
<term><menuchoice> <shortcut><keycombo action="seq">&Alt;<keycap>C</keycap>
<keycap>T</keycap></keycombo></shortcut>
<guimenuitem>Ascii Table</guimenuitem>
</menuchoice></term>
<listitem>
<para><action>Displays a table of Ascii characters</action>, from which you can
choose any characters you require.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice><shortcut><keycombo action="seq">&Alt;<keycap>C</keycap>
<keycap>P</keycap></keycombo></shortcut>
<guimenuitem>Beep on Change</guimenuitem>
</menuchoice></term>
<listitem>
<para><action>If selected, &ksirc; emits a beep every time something is said on
a channel.</action></para></listitem>
</varlistentry>


</variablelist>

</sect2>

<sect2 id="user-options">
<title>User Options</title>

<para>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:</para>

<variablelist>

<varlistentry>
<term><guimenuitem>Refresh Nicks</guimenuitem></term>
<listitem>
<para><action>Sends a message to the server to request the list of users in the
channel.</action> This ensures that the list of nicknames is up-to-date.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guimenuitem>Follow</guimenuitem></term>
<listitem>
<para><action>Highlights the user's nick in every message they send to
the channel. This way, you can follow someone's thread of conversation
in a busy channel.</action></para>
</listitem>
</varlistentry>

<varlistentry>
<term><guimenuitem>unFollow</guimenuitem></term>
<listitem>
<para><action>Stops following the user.</action></para>
</listitem>
</varlistentry>

<varlistentry>
<term><guimenuitem>Whois</guimenuitem></term>
<listitem>
<para><action>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.</action></para>
</listitem>
</varlistentry>

<varlistentry>
<term><guimenuitem>Ping</guimenuitem></term>
<listitem>
<para><action>Sends a &CTCP; ping request to the user, to
determine his echo time.</action></para>
</listitem>
</varlistentry>

<varlistentry>
<term><guimenuitem>Version</guimenuitem></term>
<listitem>
<para><action>Sends a &CTCP; version request to the user, to
determine what software he is using.</action></para>
</listitem>
</varlistentry>

<varlistentry>
<term><guimenuitem>Abuse</guimenuitem></term>
<listitem>
<para><action>Abuses the user in one of various amusing
ways.</action></para>
</listitem>
</varlistentry>

</variablelist>

<para>The following commands are only available if you are an operator
on the channel:</para>

<variablelist>
<varlistentry>
<term><guimenuitem>Kick</guimenuitem></term>
<listitem>
<para><action>Removes the user off the channel.</action></para>
</listitem>
</varlistentry>

<varlistentry>
<term><guimenuitem>Ban</guimenuitem></term>
<listitem>
<para><action>Bans the user from joining the channel.</action></para>
</listitem>
</varlistentry>

<varlistentry>
<term><guimenuitem>unBan</guimenuitem></term>
<listitem>
<para><action>Removes the ban on the user joining the channel.</action></para>
</listitem>
</varlistentry>

<varlistentry>
<term><guimenuitem>Op</guimenuitem></term>
<listitem>
<para><action>Gives the user operator privileges.</action></para>
</listitem>
</varlistentry>

<varlistentry>
<term><guimenuitem>DeOp</guimenuitem></term>
<listitem>
<para><action>Removes operator privileges from the user.</action></para>
</listitem>
</varlistentry>

</variablelist>

</sect2>
</sect1>

<sect1 id="autoconnecting">
<title>Autoconnecting</title>
<para>If you have a number of servers and/or channels which you
connect to every time you use &ksirc;, then you can set up &ksirc; to
automatically connect to them: In the <guilabel>Server
Control</guilabel> window, select
<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure
KSirc...</guimenuitem></menuchoice>, and in the dialog which appears,
select the <guilabel>Auto Connect</guilabel> page. To add a channel on
a new server, fill in the <guilabel>Server</guilabel> and
<guilabel>Channel</guilabel> text boxes, and then click on
<guibutton>Add</guibutton>. To add another channel on this server,
select the server name in the tree view, enter the channel name in the
<guilabel>Channel</guilabel> text box, and click on
<guibutton>Update/Add</guibutton>. You can repeat this process as many
times as you like to add several servers and channels for &ksirc; to
connect to at startup.</para>
</sect1>

</chapter>

<chapter id="ksirc-configuration">
<title>&ksirc; Configuration</title>

<sect1 id="config-intro">
<title>Introduction to Configuration</title>
<para>The &ksirc; configuration dialog is available from
<menuchoice><guimenu>Options</guimenu><guimenuitem>Preferences...</guimenuitem></menuchoice>
in the &ksirc; <guilabel>Server Control</guilabel> window.
</para>
</sect1>

<sect1 id="general-config">
<title>The <guilabel>General</guilabel> Tab</title>

<sect2 id="windowmode">
<title><guilabel>Window Mode</guilabel></title>
<para>
<variablelist>

<varlistentry>
<term><guilabel>SDI Mode (old behavior)</guilabel></term>
<listitem><para>Causes &ksirc; to use single document interface mode, in which
each new channel or <command>/query</command> window has its own, separate
window.</para></listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Paged MDI mode (XChat)</guilabel></term>
<listitem><para>Causes &ksirc; to use multiple document interface mode, in the
style of <application>XChat</application>, in which each new channel or
<command>/query</command> 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
<keycombo>&Alt;<keysym>Left Arrow</keysym></keycombo> and
<keycombo>&Alt;<keysym>Right Arrow</keysym></keycombo>.</para>
</listitem>
</varlistentry>

</variablelist>

</para>
</sect2>

<sect2 id="misc-general-config">
<title>The <guilabel>Misc</guilabel> Configuration Section</title>
<para>

<variablelist>

<varlistentry>
<term><guilabel>Auto Create Window</guilabel></term> <listitem><para>If
selected, &ksirc; will automatically create a new window for each user who
sends a <command>/msg</command> command to you. If not selected, any text sent
to you with <command>/msg</command> is displayed in the current window and you
can use <command>/query <replaceable>username</replaceable></command> to create
a window to chat to that user.</para></listitem>
</varlistentry>


<varlistentry id="nick-completion">
<term><guilabel>Nickname Completion</guilabel></term> <listitem><para>
If selected, switches nickname completion on. Nickname completion works as
follows:
<orderedlist>

<listitem><para>Type the first letters of a user's nickname.</para></listitem>

<listitem><para>Press <keysym>TAB</keysym>. The text you typed will be
completed to match the username, including changes in capitalization if
necessary. &eg; <userinput>phi&lt;TAB&gt;</userinput> becomes
<computeroutput>PhilRod</computeroutput> if there is a user called
<quote>PhilRod</quote> on the channel.</para></listitem>

<listitem><para>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
<keysym>TAB</keysym> subsequent times displays the next nickname in the
list. For example, if there are users <quote>PhilA</quote> and
<quote>PhilRod</quote> on a channel, and you type
<userinput>phi&lt;TAB&gt;</userinput>, the text will first be completed to
<computeroutput>PhilA</computeroutput>, and if you press <keysym>TAB</keysym>
again, it will change to <computeroutput>PhilRod</computeroutput>.</para>
</listitem>

</orderedlist>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Display topic in caption</guilabel></term>
<listitem><para><action>Displays the topic of the current channel in the window
caption.</action> If not selected, the topic is only displayed inside the
window.</para></listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Time Stamp</guilabel></term> <listitem><para><action>Prepends
each thing said in the channel with the time it was said,</action> in the form
[HH:MM:SS].</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Beep on Notify</guilabel></term>
<listitem><para>If selected, a system beep will be generated whenever a user on
your <command>/notify</command> list signs onto the &irc; server you are
on.</para></listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Color Picker Popup</guilabel></term>
<listitem><para>If selected, a popup window from which to select the color of
your text is presented when you press
<keycombo action="simul">&Ctrl;<keycap>K</keycap></keycombo>. If not, you have
to type the color codes manually. See also <xref
linkend="sectcolors"/>.</para></listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Auto Rejoin</guilabel></term>
<listitem><para><action>Rejoins channels automatically if you are
disconnected.</action></para></listitem>
</varlistentry>

<varlistentry>
<term><guilabel>History Length</guilabel></term>
<listitem><para>Stores up to this many lines of chat from each window, allowing
you to scroll upwards and see what has already been said.</para></listitem>
</varlistentry>

</variablelist>
</para>
</sect2>

<sect2 id="wallpaper-config">
<title><guilabel>Wallpaper</guilabel> Configuration</title>
<para>
In the <guilabel>Wallpaper</guilabel> 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;, <acronym>JPEG</acronym> or
<acronym>PNG</acronym> format. A preview of the image is shown at the right of
the dialog box.</para>
</sect2> 
</sect1>

<sect1 id="startup-tab">
<title>The <guilabel>Startup</guilabel> Tab</title>

<para>
Here you can configure &ksirc;'s startup settings.
</para>

<sect2 id="name-settings">
<title><guilabel>Name Settings</guilabel></title>

<para>

<variablelist>

<varlistentry>
<term><guilabel>Nick Name</guilabel></term>
<listitem><para>Set your &irc; nickname.</para></listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Alternative Nick</guilabel></term>
<listitem><para>Set the nickname to use if your first choice is already in use
by another user.</para></listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Real Name</guilabel></term>
<listitem><para>Your real name, as returned by a <command>/whois</command>
query on you.</para></listitem>
</varlistentry>

</variablelist>
</para>
</sect2>

<sect2 id="notify-list">
<title><guilabel>Notify List</guilabel></title>

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

</sect1>

<sect1 id="colors-tab">
<title>The <guilabel>Colors</guilabel> Tab</title>
<para>
Here you can configure &ksirc;'s use of color.
</para>

<sect2 id="chat-colors">
<title><guilabel>Chat colors</guilabel> Configuration</title>
<para>
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.
</para>
</sect2>

<sect2 id="nick-colors">
<title><guilabel>Nick Colors</guilabel></title>
<para>
<guilabel>Foreground:</guilabel> and <guilabel>Background:</guilabel> set the
colors for the foreground and background of users' nicknames in chat
windows. The <guilabel>Color for messages containing your nick:</guilabel>
option sets the color for any message appearing in a channel which contains
your nickname.</para>
</sect2>

<sect2 id="color-codes">
<title><guilabel>Color codes</guilabel></title>
<para>
Here you can set whether &ksirc; allows native color codes (see <xref
linkend="sectcolors"/>) and also whether &mirc; color codes are allowed.</para>
</sect2>

</sect1>

</chapter>


<chapter id="sectcolors">
<title>&ksirc; Colors</title>

<para>&ksirc; follows the color scheme used by
&mirc; and a slight modification for more
powerful in house use.</para>

<screen>&lt;fg&gt; == foreground
&lt;bg&gt; == background
&lsqb;&rsqb; == optional
</screen>

<sect1 id="mirccompatibility">
<title>&mirc; compatibility</title>

<para>Format:</para>
<itemizedlist>
<listitem>
<para><userinput>0x03&lt;fg&gt;&lsqb;,&lt;bg&gt;&rsqb;</userinput>
sets the foreground and background</para>
</listitem>
<listitem>
<para><userinput>0x03</userinput>
resets to defaults for <emphasis>that</emphasis> line</para>
</listitem>
</itemizedlist>
</sect1>

<sect1 id="ksircnative">
<title>&ksirc; native</title>

<para>Format:</para>

<itemizedlist>
<listitem>
<para><userinput>&tilde;&lt;fg&gt;&lsqb;,&lt;bg&gt;&rsqb;</userinput>
sets the foreground and background</para>
</listitem>
<listitem>
<para><userinput>&tilde;c</userinput> resets to defaults</para>
</listitem>
<listitem>
<para><userinput>&tilde;b</userinput> sets bold font</para>
</listitem>
<listitem>
<para><userinput>&tilde;u</userinput> sets underline</para>
</listitem>
<listitem>
<para><userinput>&tilde;i</userinput> sets italics</para>
</listitem>
<listitem>
<para><userinput>&tilde;r</userinput> sets reverse video</para>
</listitem>
</itemizedlist>

<para>Why did I change &ksirc; to use &tilde; instead of 0x03
(<keycombo action="simul">&Ctrl;<keycap>C</keycap></keycombo>)?
Well, it's hard to use 0x03 in scripts and not all C functions seem to
like it. <userinput>&tilde;<replaceable>letter</replaceable></userinput>
also allows more commands while not stomping on &mirc;'s future changes.</para>

</sect1>

<sect1 id="colornumbers">
<title>Color Numbers</title>

<orderedlist>
<listitem>
<para> white</para>
</listitem>
<listitem>
<para> black</para>
</listitem>
<listitem>
<para> blue</para>
</listitem>
<listitem>
<para> green</para>
</listitem>
<listitem>
<para> red</para>
</listitem>
<listitem>
<para> brown</para>
</listitem>
<listitem>
<para> purple</para>
</listitem>
<listitem>
<para> orange</para>
</listitem>
<listitem>
<para> yellow</para>
</listitem>
<listitem>
<para> lightGreen</para>
</listitem>
<listitem>
<para> cyan</para>
</listitem>
<listitem>
<para> lightCyan</para>
</listitem>
<listitem>
<para> lightBlue</para>
</listitem>
<listitem>
<para> pink</para>
</listitem>
<listitem>
<para> gray</para>
</listitem>
<listitem>
<para> lightGray</para>
</listitem>
</orderedlist>
</sect1>

<sect1 id="sendingboldunderlinereverseandcolor">
<title>Sending Bold, Underline, Reverse, and Color</title>

<para>You can use the following key combinations to insert control codes
in text:</para>

<itemizedlist>
<listitem>
<para><keycombo action="simul">&Ctrl;<keycap>B</keycap></keycombo> for
bold text</para>
</listitem>
<listitem>
<para><keycombo action="simul">&Ctrl;<keycap>U</keycap></keycombo> for
underlined text</para>
</listitem>
<listitem>
<para><keycombo action="simul">&Ctrl;<keycap>R</keycap></keycombo> for
reverse text</para>
</listitem>
<listitem>
<para><keycombo action="simul">&Ctrl;<keycap>K</keycap></keycombo> for
colored text</para>
</listitem>
<listitem>
<para><keycombo action="simul">&Ctrl;<keycap>O</keycap></keycombo> for
plain text</para>
</listitem>
</itemizedlist>

</sect1>

<sect1 id="examplessetcolors">
<title>Examples</title>

<para>To underline a single word in a sentence:</para>

<procedure>
<step>
<para>Type <keycombo
action="simul">&Ctrl;<keycap>U</keycap></keycombo></para>
</step>
<step>
<para>Type in the word</para>
</step>
<step>
<para>Type <keycombo action="simul">&Ctrl;<keycap>U</keycap></keycombo>
again</para>
</step>
</procedure>

<para>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.</para>

<para>The <keycombo action="simul">&Ctrl;<keycap>K</keycap></keycombo>
control code is slightly different because it allows you to specify a
color number. To color a single word in a sentence:</para>

<procedure>
<step>
<para>Type <keycombo
action="simul">&Ctrl;<keycap>K</keycap></keycombo></para>
</step>
<step>
<para>Type a number between 0 and 15</para>
</step>
<step>
<para>Type the word</para>
</step>
<step>
<para>Type <keycombo
action="simul">&Ctrl;<keycap>K</keycap></keycombo> again</para>
</step>
</procedure>

<para>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.</para>

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

</sect1>
</chapter>

<chapter id="filters">
<title>Filters</title>

<sect1 id="filterrulesandhowtomakethem">
<title>Filter Rules and How to Make them</title>

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

<para>The filter tries to find the <quote>match</quote> string then use
the <quote>From</quote> and <quote>To</quote> as a substitution.  The
match, from and to are all <application>Perl</application> 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:</para>

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

<para><varname>$$<replaceable>name</replaceable></varname> is
substituted with the <acronym>Perl</acronym>
<varname>$<replaceable>name</replaceable></varname> variable during the
match.  This can be substrings such as <varname>$1</varname>,
<varname>$2</varname> in the substitution, or normal variables available
under <application>sirc</application> (such as <varname>$nick</varname>,
<varname>$channel</varname>, &etc;).</para>

<para><varname>&tilde;<replaceable>name</replaceable>&tilde;</varname>
<emphasis>prepended once and only once</emphasis> to the line will send
the line of text to the window called <replaceable>name</replaceable>.
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
<literal>!</literal>:</para>

<para><variablelist>
<varlistentry>
<term><varname>!default</varname></term>
<listitem>
<para>The current default window.  Guaranteed to exist.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>!all</varname></term>
<listitem>
<para>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 <command>/part</command> or <command>/quit</command> unless the nickname is on the channel.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>!discard</varname></term>
<listitem>
<para>discards the text.</para>
</listitem>
</varlistentry>
</variablelist>
</para>

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

</sect1>

<sect1 id="examplesfilters">
<title>Examples:</title>

<orderedlist><listitem>
<para>Want to convert all boren from boren to BoreN</para>

<screen>Match: .*
From: boren
To: BoreN</screen>

<para>Pretty straight forward, match anything, then substitute boren
with BoreN.</para>

</listitem>
<listitem>
<para>You want to match everything with boren in it and send to the
window called <quote>boren</quote></para>

<screen>Match: boren
From: &circ;
To: &tilde;boren&tilde;</screen>

<para>Looks for <quote>boren</quote> if found, substitutes the beginning
of the string (&circ;) with &tilde;boren&tilde;.</para>

</listitem>
<listitem>

<para>Though the previous example works, if the string already has
<literal>&tilde;somewindow&tilde;</literal> on it, you'll now have two
<literal>&tilde;boren&tilde;&tilde;somewindow&tilde;...</literal> So you
can do this instead.</para>

<screen>Match: boren
From: ^(?:&tilde;\S+&tilde;)
To: &tilde;boren&tilde;</screen>

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

</listitem>

<listitem>
<para>Server kill messages tend to be long, ugly, annoying, &etc; A basic
message on dalnet looks like:</para>

<screen>*** 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)</screen>

<para>When you're <literal>+s</literal> 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:</para>

<screen>Match: ^\*\*\*.* KILL message for.*
From:  Path: \S+
To: .</screen>


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

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

<para>The message now looks like:</para>

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

<para>Notice the new <literal>"."</literal> after
<literal>NickServ</literal>?</para>
</listitem>

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

<screen>Match: ^\*\*\*.*KILL message.*\(NickServ Enforcement\)
From: ^(?:&tilde;\S+&tilde;)
To:  &tilde;!discard&tilde;</screen>

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

</listitem>
<listitem>
<para>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:</para>

<screen>*** [KILL] <replaceable>KILLER</replaceable>; killed <replaceable>KILLED</replaceable>; (<replaceable>REASON</replaceable>)</screen>

<screen>Match: \*\*\*.*KILL message
From: \*\*\*.*for (.*?) from (.*?)\. \((.*?)\).*
To: *** [KILL] $$2 killed $$1 ($$3)
</screen>

<para>Ok, the match looks for
<literal>***<replaceable>something</replaceable> KILL message</literal>.
We can't use <literal>&circ;</literal> since we may have just appended
<literal>&tilde;&lt;window&gt;&tilde;</literal>.</para>

<para>The from line gets a little more interesting. The <literal>"for
(.*?) "</literal> looks for the word "for" then some text.
<literal>.*?</literal> 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 <literal>()</literal> means: save the contents.  Each
() saves the matched data in <literal>$&num;</literal> where
<literal>&num;</literal> starts at 1 for the first substring, &etc;  In
this case, <varname>$1</varname> gets the nick/user-info of the person
killed. <varname>$2</varname> is then filled with the name of the
killer. Between the <literal>()</literal> we have the reason for the
kill. Here the <literal>(</literal> and <literal>\(</literal> get a
little confusing.  Remember <literal>\(</literal> matches the actual
character <literal>'('</literal>.</para>

</listitem>
<listitem>
<para>How to colorize your life.</para>

<para>Ok, you want to add some color to
&ksirc;.  See the <link linkend="sectcolors">Colors section</link> for
color info, but here's a filter rule to highlight the nickname between
<literal>&lt;NICK&gt;</literal> on each line: </para>

<screen>Match: ^(?:&tilde;\S+&tilde;)&lt;\S+&gt;
From: &lt;(\S+)&gt;
To: &lt;&tilde;4$$1&tilde;c&gt;</screen>

<para>Takes the nickname and adds color &num;4 between the two
<literal>&lt;&gt;</literal>. <literal>&tilde;c</literal> clears the color.</para>

</listitem>
</orderedlist>

</sect1>
</chapter>

<chapter id="keys">
<title>Keys</title>

<para>This is a listing of the shortcut and command keys available
under &ksirc;.</para>

<table>
<title>Keybindings</title>
<tgroup cols="2">
<thead>
<row>
<entry>Keybinding</entry>
<entry>Action</entry>
</row>
</thead>

<tbody>

<row>
<entry><keycombo
action="simul">&Ctrl;<keycap>N</keycap></keycombo></entry>
<entry>Open a new Channel/Query Window.</entry>
</row>

<row>
<entry><keycombo
action="simul">&Ctrl;<keycap>Q</keycap></keycombo></entry>
<entry>Quit</entry>
</row>

<row>
<entry><keycombo
action="simul">&Ctrl;<keycap>Enter</keycap></keycombo></entry>
<entry>Begin a message to the most recent person to send you a
message.</entry>
</row>

<row>
<entry><keycombo
action="simul">&Ctrl;&Shift;<keycap>Enter</keycap></keycombo></entry>
<entry>Begin a message to the last-but-one person to send you a
message.</entry>
</row>

<row>
<entry><keycombo
action="simul">&Ctrl;<keycap>K</keycap></keycombo></entry>
<entry>Start color code with a number. Text you type after this will be
colored.</entry>
</row>

<row>
<entry><keycombo
action="simul">&Ctrl;<keycap>U</keycap></keycombo></entry>
<entry>Begin or end underlining text. Text after the first occurrence
of this will be underlined until you type the shortcut again.</entry>
</row>

<row>
<entry><keycombo action="simul">&Ctrl;<keycap>I</keycap></keycombo></entry>
<entry>Begin or end italic text. Text after the first occurrence
of this will be italic until you type the shortcut again.</entry>
</row>

<row>
<entry><keycombo action="simul">&Ctrl;<keycap>B</keycap>
</keycombo></entry>
<entry>Begin or end bold text. Text after the first occurrence
of this will be bold until you type the shortcut again.</entry>
</row>

<row>
<entry><keycombo action="simul">&Ctrl;<keycap>R</keycap></keycombo></entry>
<entry>Begin or end reverse video text.  Text after the first occurrence
of this will be reversed  until you type the shortcut again.</entry>
</row>

<row>
<entry><keycap>TAB</keycap></entry>
<entry>Tries 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 <xref linkend="nick-completion"/>.</entry>
</row>

</tbody>
</tgroup>
</table>

</chapter>

<chapter id="credits-and-license">
<title>Credits and Licenses</title>

<para>&ksirc; copyright 1997-2002, the &ksirc; developers.</para>

<para>Portions of documentation copyright 1997, &Andrew.Stanley-Jones;</para>

<para>Documentation updated for &kde; 3.0 by &Philip.Rodrigues;
&Philip.Rodrigues.mail;.</para>

<!-- TRANS:CREDIT_FOR_TRANSLATORS -->

&underFDL;
&underGPL;

</chapter>

<appendix id="installation">
<title>Installation</title>

<sect1 id="getting-ksirc">
<title>Where to get &ksirc;</title>

&install.intro.documentation;

</sect1>


<sect1 id="compilation">
<title>Compilation and Installation</title>

&install.compile.documentation;

</sect1>
</appendix>

&documentation.index;

</book>

<!--
Local Variables:
mode: sgml
sgml-omittag: nil
sgml-shorttag: t
sgml-indent-step: nil
End:
-->




