<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.1-Based Variant V1.0//EN" "dtd/kdex.dtd" [
  <!ENTITY kmuddy '<application>KMuddy</application>'>
  <!ENTITY kapp "&kmuddy;">
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE">
]>

<!-- ................................................................ -->

<book lang="&language;">

<bookinfo>
<title>The KMuddy Handbook</title>

<authorgroup>
<author>
<firstname>Tomas</firstname>
<surname>Mecir</surname>
<affiliation>
<address><email>kmuddy@kmuddy.com</email></address>
</affiliation>
</author>
<author>
<firstname>Vadim</firstname>
<surname>Peretokin</surname>
<affiliation>
<address><email>vadimuses@gmail.com</email></address>
</affiliation>
</author>
</authorgroup>

<!-- TRANS:ROLES_OF_TRANSLATORS -->

<copyright>
<year>2002-2007</year>
<holder>Tomas Mecir</holder>
</copyright>
<copyright>
<year>2007</year>
<holder>Vadim Peretokin</holder>
</copyright>

<legalnotice>&GPLNotice;</legalnotice>

<date>11/11/2007</date>
<releaseinfo>0.8</releaseinfo>

<!-- Abstract about this handbook -->

<abstract>
<para>
This manual describes &kmuddy; version 0.8. If you have comments, ideas, suggestions, or complaints, email them off to: <address><email>kmuddy@kmuddy.com</email></address>
</para>
<para>
 Enjoy!
</para>
</abstract>

<keywordset>
<keyword>KDE</keyword>
<keyword>MUD</keyword>
<keyword>telnet</keyword>
<keyword>network</keyword>
<keyword>game</keyword>
<keyword>multi</keyword>
<keyword>player</keyword>
<keyword>online</keyword>
<keyword>MCCP</keyword>
<keyword>MSP</keyword>
</keywordset>

</bookinfo>


<!-- The documentation begins HERE. -->

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

<para>
  &kmuddy; is a full featured MUD client for the <ulink url="http://www.kde.org">KDE desktop environment</ulink>.
  It should work on any OS that can run KDE. This includes UNIX/Linux
  systems, and maybe more.
</para>
<para>
  KMuddy is being developed on <emphasis>KDE version 3</emphasis>, it has not been
  tested with older versions, but feel free to give it a try.
</para>
<para>
  <emphasis> What is a MUD client good for? </emphasis>
  Well, MUD means <firstterm>Multi-User Dungeon</firstterm> and it's a text-based
  online multi-player role-playing game. This means you'll
  need an Internet connection (preferably one where you don't
  pay for time spent online!) and some time. But <emphasis>beware</emphasis> - MUDs
  can become very addictive - don't say you haven't been warned!
</para>
<para>
  If you're interested, have a look at <ulink url="http://www.mudconnector.com">
  www.mudconnector.com</ulink> for all things related to MUDs (MUD listings, reviews,
  descriptions, and much more).
</para>
</chapter>

<chapter id="using-kapp">
<title>Using KMuddy</title>

<sect1 id="connecting">
<title>Connecting</title>
<para>
There are two ways to connect to a MUD - Connect, and QuickConnect. When you click on the <guimenu>Connection</guimenu> tab on top, you'll see both options.
</para>
<para><emphasis role="bold">Connect</emphasis></para>
<para>
The normal Connect option is meant to be used if you regularly connect to a specific MUD. In there you can create a profile by clicking on the <emphasis>New Profile</emphasis> button.
</para>
<para>
To setup a new profile, you need to fill out several things for it. In the <emphasis>Profile name</emphasis> line, you select how would you want to name the profile - usually the name of your MUD. Next, you need to fill in the <emphasis>Server</emphasis> field - otherwise known as host, and it's <emphasis>Port</emphasis>. This information can be found on the website of your MUD.
</para>
<para>Optionally, you can also write your character's name in the <emphasis>Login name</emphasis> and the password in the field below it if you want to use &kmuddy;'s auto-login feature. If you don't want to use it, then leave those two fields blank, and clear the <emphasis>Connect sequence</emphasis> field.
</para>
<para>
The main difference between the Connect and the QuickConnect features is that you have the option of using Profiles with Connect - in them, you can define your own aliases, triggers, and much more. However, if you don't need to do any of that and just want to connect to a MUD for testing purposes, then the QuickConnect feature would be better to use.
</para>
<para><emphasis role="bold">QuickConnect</emphasis></para>
<para>
The QuickConnect feature allows you to quickly connect to a MUD, if you just want to look around and such. Many features are not available for this type of connection, because you aren't in any specific profile and thus settings aren't saved after you close the QuickConnect session. Simply fill in the server name and port, and there you go!
</para>
<para>
Note: If you use a proxy, &kmuddy; will detect it from the KDE settings and automatically use it.
</para>
<para>
&kmuddy; also supports an offline mode, allowing you to edit your settings while not connected.
Simply checkmark the "Offline editing" option when opening a profile to use it.
</para>
</sect1>

<sect1 id="window">
<title>Main window</title>
<para>
Once you open &kmuddy;, you will be presented with the main window, where you'll spend most of your time interacting with your MUD. The window consists of the output area (where you see text from your MUD), the <link linkend="input">input line</link>, the status bar, and optionally gauges, actions, and other output windows. Take a look below for a sample screenshot:
</para>

<para>
<screenshot>
<screeninfo>Sample screenshot</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="kmuddy.png" format="PNG" scalefit="1"/>
    </imageobject>
  </mediaobject>
</screenshot>
</para>


<sect2 id="tabbed_windows">
<title>Tabbed Windows</title>
<para>
The &kmuddy; window supports multiple connections at once; by default, you'll see a tab bar on top with all connections you have - to switch between them, simply click on the profile tab you want or use keyboard short-cuts (namely <keycombo><keycap>Alt</keycap><keycap>PageUp/PageDown</keycap></keycombo>, and
<keycombo><keycap>Alt</keycap><keycap>number</keycap></keycombo>). 
</para>
</sect2>
<sect2 id="output_window">
<title>Output Window</title>
<para>
The main &kmuddy; window, called the output window, is where you can see all of the interaction that you do with your MUD, and generally all other information about things that go on in that MUD. &kmuddy; supports ANSI colors, so if your MUD uses them, you'll be able to see text in it's full color. To see previously received text, use the scrollbar that's on your right. When you do so, the output view gets split into two parts; the smaller one (on the bottom) showing the latest text - so you can still keep track of what's going on, and the larger part allows you to traverse through the output history as desired. Middle-clicking in the output area will
 automatically scroll to the bottom - so you don't have to scroll all the way down manually. If you wish to move the dividing line higher or lower, the default option for that is <keycombo><keycap>Alt</keycap><keycap>Ctrl</keycap><keycap>Up/Down</keycap></keycombo>. The default size of the output window is 1,000 lines - you can change this in the <link linkend="output_settings">Output area section</link> of the Global Settings.
</para>
<para>
To copy text from the output window to the input-line or to other programs, either use quick-copy (select
it and middle-click in target place) or using the regular clipboard. There are many ways in which selected text
can be copied to the clipboard. These include:
</para>
<itemizedlist>
<listitem><para><guimenu>Edit tab on top</guimenu> / <guimenuitem>Copy Selection</guimenuitem></para></listitem>
<listitem><para>Use the "Copy Selection" option when you right-click in the output window</para></listitem>
<listitem><para>Use the default keycombo <keycombo><keycap>Ctrl</keycap><keycap>Shift</keycap><keycap>S</keycap></keycombo></para></listitem>
</itemizedlist>
</sect2>
<sect2 id = "input_line">
<title>Input Line</title>
<para>
Next is the input line - it's where you type your commands and aliases. To use it, simply type in whatever you wish, and press Enter - your command will be parsed then to see if it's an alias, and if it's not, it'll be sent directly to the MUD. But the input line offers much more flexibility than that. Under the <link linkend="input_settings">Input Line settings</link> in Global Settings, you can select to keep the text you sent, enable auto-completion, change the colors of the input line, enable an additional command line and much more.
</para>
<para>
The input line also comes in two input modes - standard, and multi-line input modes. When in the multi-line input mode, you can use Ctrl+Enter to make a new line (unless you enabled the "Swap Enter and Ctrl+Enter for multi-line" option, in which case pressing Enter will make a new line, and Ctrl+Enter will send the text).
</para>
<para>
Last but not least, you can also send text via a special multi-line input dialog - more on that <link linkend="menu_view">here</link>.
</para>
<para>
To paste text into the input line, you have several options:
</para>
<itemizedlist>
<listitem><para><guimenu>Edit</guimenu> / <guimenuitem>Paste As</guimenuitem></para></listitem>
<listitem><para>Use the "Paste As" option when you right-click in the output window</para></listitem>
<listitem><para>Use the Ctrl+V keybinding</para></listitem>
<listitem><para>By using the quick-paste (middle click in the input line)</para></listitem>
</itemizedlist>
<para>
When you paste text with multiple lines into the input line, the new lines are converted to spaces - unless the input line is in multi-line mode, in which case the new lines are preserved. 
</para>
<sect3 id="input">
<title>Entering commands</title>
<para>
When you type something into the input line and press enter, it will be first parsed for your aliases/internal scripting commands, and then if your command doesn't match them, sent to your mud (you can disable command parsing with <guimenu>Edit</guimenu> / <guimenuitem>Enable command parsing</guimenuitem> if you wish).
</para>
<para>
However, besides that, &kmuddy; also offers you special strings which make manipulating text much easier. They are the command separator, multi-command, speed-walk, internal command call, tab focus strings, and several special characters.
</para>
<para>
<emphasis role="bold">Command separator</emphasis> - a semicolon (;) by default, it separates commands (e.g. command 'look;say hello;n' will execute three separate commands: look, say hello and n).
</para>
<para>
<emphasis role="bold">Repeater</emphasis> - a number sign (#) by default, it is used to repeat a command multiple times. Usage: #&lt;number of times&gt; &lt;command&gt;. For example, entering <emphasis>#10 smile
</emphasis>will send the smile command 10 times. Note that repeater is limited to 100
repetitions, unless you disabled that option. Also note that repeater is handled AFTER
the line you've entered has been split into individual commands. That means that
typing <emphasis>#10 smile; say Hi</emphasis> will send smile 10 times, but say Hi
only once. If you want to repeat a set of commands (e.g., smile, say Hi, smile, say Hi,
...), you can either use an <link linkend="using_aliases">alias</link> or write an external
<link linkend="external_script">script</link>.
</para>
<para>
<emphasis role="bold">Speedwalk</emphasis> - a dot (.) by default, this accepts following letters/numbers which are treated as speed-walk commands - that is, one walking command is issued for every letter here.
Note that you can customize those commands for profile-based connections in
<guimenu>Profile</guimenu> - <guimenuitem>MUD Preferences...</guimenuitem> - <guimenuitem>Commands</guimenuitem>.
</para>
<para>
The following characters are recognized for the speedwalk:
</para>
<!-- wanted to use some list, but failed to make it work :( -->
<para>n : command for North</para>
<para>e : command for East</para>
<para>s : command for South</para>
<para>w : command for West</para>
<para>j : command for North-East</para>
<para>k : command for South-East</para>
<para>l : command for South-West</para>
<para>m : command for North-West</para>
<para>u : command for Up</para>
<para>d : command for Down</para>
<para>1-9 : repeat following command (numbers bigger or equal to ten are NOT valid. Instead, use the same direction an needed number of times - eg., if you need to do fifteen 'e' commands, do .9e6e). A typical Speed-walking command looks like this - <emphasis>.ne3n2je4ked</emphasis>, which would mean North, East, North, North, North, North-East, North-East, East, South-East, South-East, South-East, South-East, East, Down.
</para>
<para>
<emphasis role="bold">Internal command call</emphasis> - a forward slash (/) by default, this string invokes the <link linkend="internalscripting">internal scripting</link> commands.
</para><para>
<emphasis role="bold">Tab Focus</emphasis> - a colon (:) by default, this string sends text to a different tab window - the syntax is <emphasis>:tab window name: commands</emphasis>. For example, if you want to send some text to a tab named <emphasis role="bold">Me@MUD</emphasis>, you'd do <emphasis>:Me@MUD: hi</emphasis>.
</para>
<para>
<emphasis role="bold">Special characters</emphasis> - these start with a backslash (\), and do several useful things:
<itemizedlist>
<listitem>
<para>
<userinput>\n</userinput> - means end of line, it can serve as another command separator,
if you disable the standard one for any reason. It is also possible to enable this
sequence only in aliases and triggers. So for example, doing look\nsay hello\nn will cause look, say hello, and n to be sent.
</para>
</listitem>
<listitem>
<para>
<userinput>\t</userinput> - expands to a TAB-character. Note that &kmuddy; does not display TABs properly - it merely ignores them.
</para>
</listitem>
<listitem>
<para>
<userinput>\m</userinput> can be used to launch external scripts. Handy if you disable the
standard script-character. Note that there mustn't be any space between \m and
script name. Also note that it is possible to enable this character only for aliases
and triggers. Refer to <link linkend="scripts_running">scripting</link> section for more
information.
</para>
<para>Please note that external scripting is available as a plug-in, so it will not work if it's not loaded.</para>
</listitem>
<listitem>
<para>
Backslash followed by anything else is merely ignored (can be disabled).
</para>
</listitem>
<listitem>
<para>
Note that <userinput>\\</userinput> (double backslash) can be used to
send the '\' character. This only applies if backslash expansion is on.
</para>
</listitem>
</itemizedlist>
</para>
<para>Don't forget that if you accidentally start sending a lot of commands, you can cancel them (if it's not already too late :P) with <guimenu>Edit</guimenu> / <guimenuitem>Cancel pending commands</guimenuitem>
</para>
<para>
&kmuddy; also has a command history feature - try it out! To use it, just use the Up and Down arrows to scroll through it.
</para>
</sect3>

</sect2>

<sect2 id="commands">
<title>Tab Reference</title>
<para>Note that some buttons are profile-based, and won't be accessible until you open one.</para>
<sect3 id="menu_commands">
<title>The Connection Menu</title>
<para>
<variablelist>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><keycap>N</keycap></keycombo>
</shortcut>
<guimenu>Connection</guimenu>
<guimenuitem>Connect...</guimenuitem>
</menuchoice></term>
<listitem><para><action>
Establishes a new profile-based connection, and manages profiles. See </action><link linkend="connecting">connecting with &kmuddy;</link><action> for more information.
</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><keycap>O</keycap></keycombo>
</shortcut>
<guimenu>Connection</guimenu>
<guimenuitem>QuickConnect...</guimenuitem>
</menuchoice></term>
<listitem><para><action>
Establishes a quick connection. Note that advanced features (aliases, triggers, etc.)
are not accessible in this mode, as no profile is used.
</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><keycap>D</keycap></keycombo>
</shortcut>
<guimenu>Connection</guimenu>
<guimenuitem>Disconnect</guimenuitem>
</menuchoice></term>
<listitem><para><action>
Closes current connection (if any). It </action><emphasis>should</emphasis><action> be safe to use
this without going net-dead, as it sends out a </action><link linkend="profile_commands_settings">
customizable quitcommand</link> and then disconnects.
</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><keycap>R</keycap></keycombo>
</shortcut>
<guimenu>Connection</guimenu>
<guimenuitem>Reconnect</guimenuitem>
</menuchoice></term>
<listitem><para><action>
Re-opens last connection opened in this tab. This is only available after a connection is closed.
</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Connection</guimenu>
<guimenuitem>Close tab</guimenuitem>
</menuchoice></term>
<listitem><para><action>
Closes current tab. Only available after the connection is closed and if there is at least one more tab.
</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><keycap>Q</keycap></keycombo>
</shortcut>
<guimenu>File</guimenu>
<guimenuitem>Quit</guimenuitem>
</menuchoice></term>
<listitem><para>Saves all settings and <action>quits</action> &kmuddy;.</para></listitem>
</varlistentry>

</variablelist>
</para>
</sect3>

<sect3 id="menu_edit">
<title>The Edit Menu</title>
<para>
<variablelist>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><keycap>Shift</keycap><keycap>S</keycap></keycombo>
</shortcut>
<guimenu>Edit</guimenu>
<guimenuitem>Copy Selection</guimenuitem>
</menuchoice></term>
<listitem><para><action>
Copies the currently selected text in the main output window to the clipboard.
</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Edit</guimenu>
<guimenuitem>Paste As</guimenuitem>
</menuchoice></term>
<listitem><para><action>
Pastes text from the clipboard into where the cursor currently is.
</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><keycap>Shift</keycap><keycap>P</keycap></keycombo>
</shortcut>
<guimenu>Edit</guimenu>
<guimenuitem>Enable command parsing</guimenuitem>
</menuchoice></term>
<listitem><para><action>
Enables/disables command parsing (see the </action><link linkend="input">entering commands</link><action> for more info).
When this option is disabled, commands are sent out exactly as you've typed them without any interpretation by &kmuddy;.
</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Edit</guimenu>
<guimenuitem>Cancel pending commands</guimenuitem>
</menuchoice></term>
<listitem><para><action>
Cancels all commands that were issued but not yet sent, in case you've gotten yourself into a large loop.
</action></para></listitem>
</varlistentry>

</variablelist>
</para>
</sect3>

<sect3 id="menu_view">
<title>The View Menu</title>
<para>
<variablelist>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><keycap>Shift</keycap><keycap>M</keycap></keycombo>
</shortcut>
<guimenu>View</guimenu>
<guimenuitem>Show multi-line input</guimenuitem>
</menuchoice></term>
<listitem><para><action>
Shows/hides a multi-line input dialog, which allows you to type more commands and send them all
at once. The large box is where you can type the text to be sent; you also have an option of filling in the 'Prefix' and the 'Suffix' fields. When you add something to either of them, it'll be prefixed/suffixed to every line in the big output box.
</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>View</guimenu>
<guimenuitem>Show alias groups</guimenuitem>
</menuchoice></term>
<listitem><para>
Displays an alias groups dialog, where you can manipulate them. See <link linkend="atgroups">alias groups</link> for more information.
</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>View</guimenu>
<guimenuitem>Show trigger groups</guimenuitem>
</menuchoice></term>
<listitem><para>
Displays a trigger groups dialog, which is similar to alias groups. See <link linkend="atgroups">trigger groups</link> for more information.
</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>View</guimenu>
<guimenuitem>Show action toolbar</guimenuitem>
</menuchoice></term>
<listitem><para><action>
Displays action toolbar where all buttons are mde. This is only available for profile-based connections - more information </action><link linkend="toolbar">here</link>.
</para></listitem>
</varlistentry>


<varlistentry>
<term><menuchoice>
<guimenu>View</guimenu>
<guimenuitem>Show running scripts</guimenuitem>
</menuchoice></term>
<listitem><para>
Displays which scripts are currently active. See <link linkend="external_script">external scripting</link> for more information.
</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>View</guimenu>
<guimenuitem>Show connection statistics</guimenuitem>
</menuchoice></term>
<listitem><para>
Shows Connection statistics dialog. Here you can see some information about the active connection,
such as whether MCCP/MSP is used, how many bytes/lines/commands have been sent/received so far, and
connection time. The data displayed here is updated each second.
</para></listitem>
</varlistentry>

</variablelist>
</para>
</sect3>

<sect3 id="menu_profile">
<title>The Profile Menu</title>
<para>
<variablelist>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Alt</keycap><keycap>Ctrl</keycap><keycap>A</keycap></keycombo>
</shortcut>
<guimenu>Profile</guimenu>
<guimenuitem>Aliases...</guimenuitem>
</menuchoice></term>
<listitem><para><action>
Manages aliases for current profile-based connection. More information on using aliases is avialable
</action><link linkend="using_aliases">here</link>.
</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Alt</keycap><keycap>Ctrl</keycap><keycap>T</keycap></keycombo>
</shortcut>
<guimenu>Profile</guimenu>
<guimenuitem>Triggers...</guimenuitem>
</menuchoice></term>
<listitem><para><action>
Manages triggers for current profile-based connection. More information on using triggers is avialable
</action><link linkend="triggers">here</link>.
</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Profile</guimenu>
<guimenuitem>Variables...</guimenuitem>
</menuchoice></term>
<listitem><para><action>
Manages a list of variables available for current profile-based connection.
More information </action><link linkend="variables">here</link>.
</para></listitem>
</varlistentry>


<varlistentry>
<term><menuchoice>
<guimenu>Profile</guimenu>
<guimenuitem>Actions...</guimenuitem>
</menuchoice></term>
<listitem><para><action>
Manages action toolbar buttons for current profile-based connection. More information
</action><link linkend="toolbar">here</link>.
</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Profile</guimenu>
<guimenuitem>Timers...</guimenuitem>
</menuchoice></term>
<listitem><para><action>
Manages a list of timers available for current profile-based connection.
More information </action><link linkend="timers">here</link>.
</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Profile</guimenu>
<guimenuitem>Macro keys...</guimenuitem>
</menuchoice></term>
<listitem><para><action>
Manages a list of macro keys available for current profile-based connection.
More information </action><link linkend="macrokeys">here</link>.
</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Profile</guimenu>
<guimenuitem>Variable triggers...</guimenuitem>
</menuchoice></term>
<listitem><para><action>
Manages a list of variable triggers available for current profile-based connection.
More information </action><link linkend="variable_triggers">here</link>.
</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Profile</guimenu>
<guimenuitem>Status variables...</guimenuitem>
</menuchoice></term>
<listitem><para><action>
Manages a list of status variables available for current profile-based connection.
More information </action><link linkend="status_variables">here</link>.
</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Profile</guimenu>
<guimenuitem>Gauges...</guimenuitem>
</menuchoice></term>
<listitem><para><action>
Manages a list of gauges available for current profile-based connection.
More information </action><link linkend="gauges">here</link>.
</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Profile</guimenu>
<guimenuitem>Output windows...</guimenuitem>
</menuchoice></term>
<listitem><para><action>
Manages a list of output windows available for current profile-based connection.
More information </action><link linkend="output_windows">here</link>.
</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Profile</guimenu>
<guimenuitem>Tick timer...</guimenuitem>
</menuchoice></term>
<listitem><para><action>
Manages a list of tick timer available for current profile-based connection.
More information </action><link linkend="tick_timer">here</link>.
</para></listitem>
</varlistentry>


<varlistentry>
<term><menuchoice>
<guimenu>Profile</guimenu>
<guimenuitem>Scripts...</guimenuitem>
</menuchoice></term>
<listitem><para><action>
Manages a list of scripts available for current profile-based connection.
More information </action><link linkend="external_script">here</link>.
</para></listitem>
</varlistentry>




<varlistentry>
<term><menuchoice>
<guimenu>Profile</guimenu>
<guimenuitem>MUD preferences</guimenuitem>
</menuchoice></term>
<listitem><para><action>
Allows you to modify preferences for current profile-based connection. More information
</action><link linkend="profile_settings">here</link>.
</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><keycap>Shift</keycap><keycap>A</keycap></keycombo>
</shortcut>
<guimenu>Profile</guimenu>
<guimenuitem>Aliases enabled</guimenuitem>
</menuchoice></term>
<listitem><para><action>
Allows you to enable/disable all aliases.
</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><keycap>Shift</keycap><keycap>T</keycap></keycombo>
</shortcut>
<guimenu>Profile</guimenu>
<guimenuitem>Triggers enabled</guimenuitem>
</menuchoice></term>
<listitem><para><action>
Allows you to enable/disable all triggers.
</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Profile</guimenu>
<guimenuitem>Timers enabled</guimenuitem>
</menuchoice></term>
<listitem><para><action>
Allows you to enable/disable all timers.
</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Profile</guimenu>
<guimenuitem>Macro keys enabled</guimenuitem>
</menuchoice></term>
<listitem><para><action>
Allows you to enable/disable all macro keys.
</action></para></listitem>
</varlistentry>

</variablelist>
</para>
</sect3>

<sect3 id="menu_tools">
<title>The Tools Menu</title>
<para>
<variablelist>

<varlistentry>
<term><menuchoice>
<guimenu>Tools</guimenu>
<guimenuitem>Session transcript</guimenuitem>
</menuchoice></term>
<listitem><para><action>
Enables/disables/configures session transcript. More information
</action><link linkend="transcript">here</link>.
</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Tools</guimenu>
<guimenuitem>Dump buffer</guimenuitem>
</menuchoice></term>
<listitem><para><action>
This will dump the output buffer to a file.</action>
</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Tools</guimenu>
<guimenuitem>Decision assistant</guimenuitem>
</menuchoice></term>
<listitem><para>
Writes a random sentence. You can use this when in doubt and no dices/coins are
available.
<link linkend="transcript">here</link>.
</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Tools</guimenu>
<guimenuitem>Export profile</guimenuitem>
</menuchoice></term>
<listitem><para>
Will export all profile settings, aliases, triggers and so on into a file.
Useful to make backups and to transfer profiles between more computers.
</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Tools</guimenu>
<guimenuitem>Import profile</guimenuitem>
</menuchoice></term>
<listitem><para>
Imports a profile previously exported with the Export profile command.
</para></listitem>
</varlistentry>

</variablelist>
</para>
</sect3>

<sect3 id="menu_settings">
<title>The Settings Menu</title>
<para>
<variablelist>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><keycap>M</keycap></keycombo>
</shortcut>
<guimenu>Settings</guimenu>
<guimenuitem>Hide Menubar</guimenuitem>
</menuchoice></term>
<listitem><para>
Hides the Menubar from view (can also be shown or hidden via the main window
context menu).
</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><keycap>Shift</keycap><keycap>F</keycap></keycombo>
</shortcut>
<guimenu>Settings</guimenu>
<guimenuitem>Full Screen Mode</guimenuitem>
</menuchoice></term>
<listitem><para>
Enter/Exit from Full Screen Mode (can also be done via the main window context
menu).
</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Settings</guimenu>
<guimenuitem>Global settings</guimenuitem>
</menuchoice></term>
<listitem><para><action>
Global settings (not profile-based). More information
</action><link linkend="global_settings">here</link>.
</para></listitem>
</varlistentry>

</variablelist>
</para>
</sect3>

<sect3 id="menu_help">
<title>The Help Menu</title>
<para>
This is a standard Help menu, common to many KDE applications.
</para>
</sect3>


</sect2>

</sect1>

<sect1 id="settings">
<title>Customizing KMuddy</title>
<para>Settings here are profile-independent - so they're applied equally to all profiles. If you want to edit profile-dependant settings, head to Profile - MUD settings.</para>

<sect2 id="profile_settings">
<title>Profile Settings</title>
<para>
Besides the Global Preferences, which are applied equally to all profiles, there are also Profile preferences, which can be found in <guimenu>Profile</guimenu> / <guimenuitem>MUD Preferences</guimenuitem>. Profile-based settings are specific to each particular profile only, so feel free to customize these for each character.
</para>

<sect3 id="profile_connection_settings">
<title>Connection</title>
<para>Here are defined profile-specific settings on how your connection is generally handled.</para>
<para><emphasis>Use colorized output (if avialable)</emphasis> - selects whenever &kmuddy; will display MUD text in color. If unchecked, all text will be displayed in the default color.</para>
<para><emphasis>Enable trigger loop detection</emphasis> - this is a special feature in &kmuddy; that'll watch out for looping triggers. If one is detected, it'll temporarily pause all triggers so that you have time to disable and fix your triggers.</para>
<para><emphasis>Do not allow more than 100 repeated commands</emphasis> - this limits the amount of repeated commands (used with the repeat string) to be sent to 100. Useful if you accidently send too many by accident.</para>
<para><emphasis>Enable telnet negotiation on startup</emphasis> - special negotiation when you're connecting to a server. Some don't support this properly, so this is useful to disable when needed.</para>
<para><emphasis>Auto-append newlines on prompt</emphasis> - if enabled, &kmuddy; will append a newline onto each prompt - this is useful if some servers don't end the prompt properly.</para>
<para><emphasis>Show prompt in a separate field</emphasis> - this'll have &kmuddy; display your prompt to the left of your input line.</para>
<para><emphasis>Show prompt in the status bar</emphasis> - displays your prompt in the status bar at the bottom of the screen.</para>
<para><emphasis>Show prompt in the console</emphasis> - if unchecked, &kmuddy; will gag your prompt. This option, combined with the previous two can be very useful.</para>
<para><emphasis>Start advanced transcript when session starts</emphasis> - if enabled, &kmuddy; will automatically log everything as soon as you connect to a MUD. Log files are stored in your home folder, and a new one is made daily (if necessary).</para>
</sect3>

<sect3 id="profile_commands_settings">
<title>Commands</title>
<para>All of the commands listed here, save for the last one, are expanded as specified by the speedwalking string (so .ne will cause kmuddy to send "North" and "East"). The last one, quit, is sent to the server when you select the <guimenu>Connection</guimenu> - <guimenuitem>Disconnect</guimenuitem> option.</para>
</sect3>

<sect3 id="profile_directories_settings">
<title>Directories</title>
<para>Here, you can select which directories &kmuddy; will be using.</para>
<para><emphasis>Default script location</emphasis> - this selects the location where you have placed your external scripts, and this is where &kmuddy; will look for them.</para>
<para><emphasis>Default working directory</emphasis> - this is a directory for scripts that do not have any specified. Working directory is like the current directory that you "cd" to in a shell - so if the script tries to open a file without specifying any path, it'll look in that directory.</para>
<para><emphasis>Default transcript directory</emphasis> - selects the directory where all transcripts (logs) will be saved to.</para>
</sect3>

<sect3 id="profile_sound_settings">
<title>Sound</title>
<para>Here, you can configure settings for the MSP sound protocol. In the big box, you can add directories where &kmuddy; will look for sounds when it needs them.</para>
<para><emphasis>Use MSP even if not negotiated</emphasis> - When this option is enabled, KMuddy will interpret MSP sequences all the time, even if no negotiation took place. Useful for MUDs that don't support telnet negotiation of MSP. But beware - only turn this on if your MUD really supports MSP to prevent other players from sending malicious MSP sequences, if you allow downloading of sounds.</para>
<para><emphasis>Allow mid-line MSP sequences</emphasis> - Mid-line MSP sequences are a zMUD extension to the MSP spec that some MUDs seem to be using. You can enable support for this feature here, but ensure that other players cannot say/tell/whatever these sequences, or disable downloading support; otherwise players could instruct your client to download any file on the internet.</para>
</sect3>

<sect3 id="profile_mapper_directions_settings">
<title>Mapper: Directions</title>
<para>Here you can configure the long, and short names of the directions for the mapper to use. Generally you won't need to do this unless your MUD has specified them differently.</para>
</sect3>

<sect3 id="profile_mapper_movement_settings">
<title>Mapper: Movement</title>
<para>Here, you can configure triggers which will tell the mapper that you couldn't move to the room that you were going to. So you might want to list any closed doors, invalid room, or any other triggers listed here.</para>
<para><emphasis>Enable valid room checking</emphasis> - if enabled, this will check all of the invalid movement triggers before adding the new room when you're mapping/following in the mapper. If it matches any of the triggers, it won't count the movement as a sucsessful one.</para>
<para>In the main window, simply add the <link linkend="regexp">regular expression trigger</link> that matches the invalid move message, and they'll be taken into account.</para>
</sect3>

</sect2>

<sect2 id="global_settings">
<title>Global Settings</title>
<sect3 id="window_settings">
<title>Window</title>
<para>These settings control options for the main &kmuddy; window.</para>
<para><emphasis>Show the tab bar even if not needed</emphasis> - if this option is checked, then the tab top-left of &kmuddy; will always be displayed, even if you only have one profile open. The tab bar will also be displayed if you have multiple profiles open.</para>
<para><emphasis>Show auxilary input line</emphasis> - allows you to have two input lines, each acting independently. This is a very useful feature if you're multi-tasking.</para>
<para><emphasis>Always notify</emphasis> - if this option is enabled, &kmuddy; will notify you when new text is received - it'll be blinking in your window bar when that happens.</para>
<para>You'll only get notification for text lines that match some of the <link linkend="notify_triggers">
notification triggers</link>.</para>
<para><emphasis>Global notification</emphasis> - There are two different sorts of notification, <emphasis>global
</emphasis> and <emphasis>local</emphasis>. <emphasis>Global notification</emphasis> takes effect when the 
KMuddy window is inactive and some text arrives from any of the MUD servers you're connected to. It causes the 
window caption and the appropriate field in the taskbar to start flashing. (Note: this isn't supported in older,
 3.0 and below, versions of KDE).</para>
<para><emphasis>Local notification</emphasis> - only applies to one connection. When it is not active and some new text arrives, the caption in the tabbar on the top of KMuddy window starts flashing in the same way as with global notification. It keeps flashing until you switch to that connection. This flashing never happens for the active connection, so keep this in mind when using both local and global notification (some text may have arrived to the active connection; even if its tab is not flashing).</para>
</sect3>

<sect3 id="output_settings">
<title>Output area</title>
<para>These settings control the options for the output area - it's where you see all the MUD output.</para>

<para><emphasis>Default background color</emphasis> - this selects which color &kmuddy; will use as the 
background color for text coming from the MUD - black is usually the standard on MUDs.</para>
<para><emphasis>Default text color</emphasis> - this will be the color of non-colored text - grey is  usually the set color on most MUDs.</para>
<para><emphasis>Command echo color</emphasis> - commands sent by &kmuddy; will be colored in this color.</para>
<para><emphasis>System message color</emphasis> - &kmuddy;'s messages to you will be colored in this color.</para>
<para><emphasis>Indentation</emphasis> - if &kmuddy; wraps your text into multiple lines, the level of indentation will control by how much the wrapped lines are indented.</para>
<para><emphasis>Wrap at position</emphasis> - &kmuddy; will wrap to be the specified length, if they're over this limit.</para>
<para><emphasis>History buffer size</emphasis> - specifies the amount of lines that &kmuddy; will keep in it's buffer (the output area). By default, it's set at 1,000 - and keep in mind that changing this will only take affect the next time the profile is opened.</para>
<para><emphasis>Forced redraw after</emphasis> - specifies the amount of lines after which the whole output screen will be redrawn - only useful on old computers, and should be disabled (scroll the amount down to 'Never') if you aren't on one.</para>
<para><emphasis>Enable command echo</emphasis> - if enabled, this will echo the commands you sent in the output area (in yellow by default).</para>
<para><emphasis>Enable blinking</emphasis> - sets the option of text to blinking or not (used by certain MUds).</para>
<para><emphasis>Enable system messages</emphasis> - if enabled, this will echo system messages in the output area - you should keep this option on, as system messages are very important (they are colored in cyan by default).</para>
<para><emphasis>Enable word wrapping</emphasis> - if enabled, &kmuddy; will word wrap the incoming text, to a lengh
 specified by 'Wrap at position'.</para>
</sect3>
 
<sect3 id="font_settings">
<title>Font</title>
<para>This controls the fonts to be used in various places of &kmuddy;.</para>

<para><emphasis>Server output</emphasis> - this controls the font, font style, and size for the text that's incoming from your MUD.</para>
<para><emphasis>Input line</emphasis> - this controls the font of the input line (where you type commands to be sent to the MUD).</para>
<para><emphasis>Multi-line output</emphasis> - this controls the font of the multi-line input line.</para>
</sect3>

<sect3 id="input_settings">
<title>Input line</title>
<para>This controls the options for the input line - where you type commands to be sent to your MUD.</para>

<para><emphasis>Keep sent text</emphasis> - if enabled, the text that you just sent will be kept in the input line, and not cleared. Useful if you're doing repeated actions.</para>
<para><emphasis>Select kept text after it's sent</emphasis> - this handy feature, combined with the keep sent text option, will select the text you just sent - if you start typing a different command other than the previous one, it'll clear the previous one automatically.</para>
<para><emphasis>Cursor keys to browse history</emphasis> - if enabled, this will allow you to use the 
<emphasis>up</emphasis> and <emphasis>down</emphasis> keys on your keyboard to browse the history of last sent
 commands.</para>
<para><emphasis>Telnet-style paste</emphasis> - if enabled, this will cause text pasted into the input line to be sent directly to your MUD, and each line will be split up as it's own command.</para>
<para><emphasis>Trim spaces</emphasis> - this will remove the spaces before and after the commands you send - for example, if you send "   s   ", it'll only send "s".</para>
<para><emphasis>Enable auto-completion</emphasis> - enables/disables the feature of when you're typing something into the input line, &kmuddy; will suggest previous lines that you sent to use.</para>
<para><emphasis>Type of autocompletion</emphasis> - <emphasis>autofill</emphasis> - this type of autocompletion will only complete when there is one match possibility left. <emphasis>shortest match</emphasis> - this type will keep suggesting possible suggestions as you type the command out.<emphasis>Popup list-box</emphasis> - kmuddy will display all previous commands that you entered that match the current one in a popup box above he input line.</para>
<para><emphasis>Background color</emphasis> - sets the background color for the input line.</para>
<para><emphasis>Text color</emphasis> - sets the text color to be used by the input line.</para>
<para><emphasis>Swap ENTER and CTRL+ENTER for multi-line</emphasis> - this controls whether Ctrl+Enter inserts a newline into the input box and Enter sends the commands to the server, or the other way round.</para>
</sect3>

<sect3 id="color_settings">
<title>Colors</title>
<para>In this menu, you can select how &kmuddy; interprets, and displays the colors that it receives. This is useful 
if you want to change some shades of a color for whatever reason. To select a new color, simply click on the color box
beside the color name, and select the new color.</para>
</sect3>

<sect3 id="string_settings">
<title>Strings</title>
<para>In this menu, you can select the values for special strings in &kmuddy;. Note they are called strings for 
a reason - their length isn't limited to one.</para>

<para><emphasis>Command separator string</emphasis> - this string will cause your input to be split up.
So for example, if you do "n;ne", kmuddy will send "n" and then "ne". Note that this'll cause a winking 
smiley to be split up too, but to avoid that, you can prefix the "Send as-is" string before your 
command - read on for an example.</para>
<para><emphasis>Speedwalk string</emphasis> - to start a speedwalk, just prefix this string, and then put in your
speedwalk path. For example, the speedwalk character is a dot, then you could do .3n2e to walk 3 north and 2 east.</para>
<para><emphasis>Speedwalk even if empty</emphasis> - if enabled, and you send the speedwalk string without any commands after it, it'll effectively do nothing. Otherwise, if the option is disabled, it'll send the string itself.</para>
<para><emphasis>Internal command-call string</emphasis> - this defines the string to be used for calling &kmuddy;'s internal 
scripting commands (ie. set, echo, etc.)</para>
<para><emphasis>Repeater string</emphasis> - the syntax to use this is #&lt;string&gt; this'll cause any text after 
the string to be repeated x number of times. For example, #5 hi will cause five 'hi's to be sent.</para>
<para><emphasis>Focus string</emphasis> - this will cause text to be sent to a different tab - useful when multiplaying. The syntax is <emphasis>&lt;string&gt;&lt;tab name&gt;&lt;string&gt;commands to be sent</emphasis>.</para>
<para><emphasis>Send as-is</emphasis> - this'll cause text after this string not to be parsed by &kmuddy; and sent
directly to your mud exactly as you put it in. This is useful if you want to avoid an alias or a internal command going off
on text that you want to get sent.</para>
<para><emphasis>Expand backslashes</emphasis> - causes special strings that start with \ to be expanded and 
interpreted. The complete listing of them can be found expanded_backslashes here.</para>
</sect3>

<sect3 id="sound_settings">
<title>Sound</title>
<para>Select MSP (Mud Sound Protocol) - based settings here.</para>
<para><emphasis>Enable sounds globally</emphasis> - enables sound for all profiles. This can be disabled in each
profile setting individually.</para>
<para><emphasis>Allow downloading sounds</emphasis> - if enabled, and &kmuddy; receives a URL from the MSP protocol, it'll download and play that sound.</para>
<para>You can select directories where MSP sounds will be sought for if a server needs them (so if your MUD doesn't
use MSP, this is no use) in the big box.</para>
</sect3>

<sect3 id="shortcut_settings">
<title>Shortcuts</title>
<para>You can edit your shortcuts here. To search for a particular shortcut, just type it's name in the top bar.
To edit a shortcut, just double-click on it. Pressing the little white x on a red background will clear the
shortcut, and to set a new one, just press the new key combination.</para>

<para>On the bottom, you can either disable the shortcut by selecting 'None', set it to the default value, or
customize it. The button on the right shows the current key combination for that shortcut.</para>
</sect3>

<sect3 id="mapper_color_settings">
<title>Mapper: Colors</title>
<para>Here, you can select new colors that will be used by the mapper. Simply click on the current color, select
a new value then save for the change to take effect.</para>
</sect3>

<sect3 id="mapper_speedwalk_settings">
<title>Mapper: Speedwalk</title>
<para><emphasis>Limit speedwalk moves</emphasis> - if selected, the mapper won't allow more speedwalk moves than
specified by 'number of moves before aborting'. Some MUDs place a limit on how many commands you can send at once.
</para>
</sect3>

</sect2>
</sect1>

<sect1 id="profiles">
<title>Profiles</title>
<para>
A profile in &kmuddy; is meant to store character-related data - like aliases, triggers and more on a given MUD. For information on profile-based features, see the <link linkend="menu_profile">profile tab</link>.
</para>
<para>
Profiles can be added, modified, duplicated or removed in the <link linkend="connecting">Connection</link> menu item. Here you can set up profile
preferences such as the server, port, auto-login and the option of directly connecting
using this profile. You can also set commands to run immediately after logging in to a MUD.
Please note that these commands will be sent exactly as you type them in - no command parsing
will occur - so you cannot use speed-walking, scripts and so on. You can also temporarily
disable sending of those commands (by checking "Do not send login sequence") - this is useful when you want to create a new character.
</para>
<para>
IMPORTANT: if you delete a profile, it's removed from your hard drive! You'll lose all
your aliases/triggers/actions/script definitions! (you won't lose your external scripts
themselves though, as they are separate from KMuddy).
</para>
<para>
The <emphasis>Duplicate</emphasis> button can be used to duplicate an existing profile.
This allows you to reuse common aliases/triggers between profiles.
</para>
<para>
The <emphasis>Offline editing</emphasis> option allows you to edit your profile including
all of your aliases/triggers/actions without actually being logged into your MUD, which is
useful if you plan on making a lot of changes, or don't want to be bothered while working
on your system.
</para>
<para>
Note: profiles are stored in your homedir, in the directory .kde/share/apps/kmuddy/profiles or
.kde3/share/apps/kmuddy/profiles (depending on your distribution).
</para>
</sect1>




<sect1 id="transcript">
<title>Session transcript</title>
<para>
<guimenu>Tools</guimenu> / <guimenuitem>Session transcript</guimenuitem> gives you
access to the session transcript, which is useful if you want to store everything you're doing
on the MUD to a file. Note that transcript options are not remembered between
sessions, but if you want, you can have &kmuddy; transcript for you as soon as you login - just check the 
'Start advanced transcript when session starts' in MUD preferences.
</para>
<para>
The <emphasis>Advanced transcript</emphasis> is a special version of the
standard transcript. It is useful if you want to have a transcript running all the time.
You can have the transcript split by date, and you can (in MUD preferences) set up
advanced transcript to run immediately after connecting. It also offers you a choice to append timestamps at the beginning of the log. Note that this feature is somewhat confusing at the moment, and will be improved later on.
</para>
</sect1>

<sect1 id="notification">
<title>Output notification</title>
<para>
In <guimenu>Settings</guimenu> / <guimenuitem>Global settings</guimenuitem>, you can
enable output notification. This feature notifies you, when something arrives from
the MUD. There are two different sorts of notification, <emphasis>global</emphasis>
and <emphasis>local</emphasis>.
</para>
<para>
<emphasis>Global notification</emphasis> takes effect when the &kmuddy; window is
inactive and some text arrives from any of the MUD servers you're connected to.
It causes the window caption and the appropriate field in the taskbar to
start flashing. Note that in KDE 3.0 and below, this is done by showing and hiding some stars ('*'),since flashing isn't supported. It keeps flashing until you activate the
&kmuddy; window.
</para>
<para>
<emphasis>Local notification</emphasis> works similarly, but it only applies to one
connection. When it is not active and some new text arrives, the caption in the tab bar
on the top of &kmuddy; window starts flashing in the same way as with global
notification. It keeps flashing until you switch to that connection. This flashing
never happens for the active connection, so keep this in mind when using both local and
global notification (some text may have arrived to the active connection; even
if its tab is not flashing).
</para>
</sect1>

<sect1 id="msp">
<title>Sound support</title>
<para>
&kmuddy; supports the MUD Sound Protocol (MSP) version 0.3. This allows sound and music files to be played at certain events.
</para>
<para>
First of all, you can only use MSP if your MUD supports it. Also, you need to have sound support compiled in. Binary packages have this support included.
</para>
<para>
The sound samples that are to be played can be obtained in two ways. You can download a sound pack from your MUD's website - if such a pack is available - and place it (uncompressed, of course) to a directory specified in a list of directories with sound files (see below). Alternately, if your MUD supports it, &kmuddy; can download these files for you automatically, as they are requested. These sound files are then stored in your kdehome directory, usually in <emphasis>.kde/share/apps/kmuddy/sounds</emphasis>.
</para>
<para>
Sound support can be configured in <guimenu>Settings</guimenu> / <guimenuitem>Global settings</guimenuitem>
and in <guimenu>Profile</guimenu> / <guimenuitem>MUD Preferences</guimenuitem>. The former configures
global settings, the latter profile-based ones. In these dialogs, you can enable/disable sounds,
enter search paths where sound files are located and enable/disable support for downloading.
</para>
<para>
Some more things to be aware of - sound support is not (yet) perfect; if you're using aRts, then volume
setting doesn't work, if using SDL, MIDI files may not be played correctly. MIDI files don't work at all with aRts :-(. Binary packages use aRts.
</para>
<para>
If multiple MSP-enabled connections are open, then they share the same sound players. Therefore, if both
connections want to play something at the same time, only one sound will be played; exactly as if one
connection sent both requests. To determine which sound is played, sound priorities are used - refer to
MUD Sound Protocol specification for more information.
</para>
</sect1>

</chapter>

<chapter id="scripting">
<title>Scripting</title>

<sect1 id="internal_scripting">
<title>Internal Scripting</title>

<sect2 id="using_aliases">
<title>Using aliases</title>
<para>
Aliases are a very useful function that &kmuddy; provides to help you do everything from save on repetitive typing of the same, or similar commands, to making complete combat systems. For example, you may want to type <emphasis role="bold">light</emphasis> and let it be replaced with <emphasis role="bold">cast light on torch</emphasis>, or type walkaround and let &kmuddy; replace it with <emphasis role="bold">.nsewsnwe</emphasis>.
</para>
<para>
Aliases are only available for profile-based connections in <guimenu>Profile</guimenu>
/ <guimenuitem>Aliases</guimenuitem> - that is also where you can manage them.
</para>
<para>
To add a new alias, simply click the <guimenuitem>Add</guimenuitem> button. If you want to chage an existing alias, then select the alias, and click the <guimenuitem>Modify</guimenuitem> button. To delete an alias, simply select it, and press the <guimenuitem>Delete</guimenuitem> button. You can also change the order the aliases are matched in my simply moving them up or down the list.
</para>
<para>
Let's create a new alias and see what options we have. For example, we'll create an alias called <emphasis role="bold">hi</emphasis> that'll instead cause &kmuddy; to send <emphasis role="bold">hello</emphasis>. Clicking on the <guimenuitem>Add</guimenuitem> button, we get another window (titled <guimenuitem>Edit alias</guimenuitem>), and here is where we'll be adding the alias.
</para>
<para>
First off, there is the alias text line - it's where we'll type in the alias name. So we'll simply type <emphasis role="bold">hi</emphasis> in here. For more advanced aliases, you can also define multi-line aliases with the command-separator character (which is a <emphasis role="bold">;</emphasis> by default), or with the the \n sequence.
</para>
<para>
Next is the comparison type option. For our purposes, the default option of <guimenuitem>Begins with</guimenuitem> is okay, so leave it as it is. Comparison type just means how &kmuddy; will be matching the text you typed to your alias, and there are several options for that:
</para>
<para>
<guimenuitem>Exact match</guimenuitem> - as the name suggests, the alias will only be matched sucsessfuly if the command you enter is exactly the alias. So if we would have typed <emphasis role="bold">hi there</emphasis>, our alias would not have matched.
</para>
<para>
<guimenuitem>Sub-string</guimenuitem> - this one is a bit trickier. With this option, the alias name can be anywhere in the command that we entered - so for example, if we typed <emphasis role="bold">say oh, hi! How are you?</emphasis>, the <emphasis role="bold">hi</emphasis> in our command would get matched.
</para>
<para>
<guimenuitem>Begins with</guimenuitem> - this will only match the alias if our command begins with it. So if we did <emphasis role="bold">hi there</emphasis>, our alias then would match, since it begins with our <emphasis role="bold">hi</emphasis>.
</para>
<para>
<guimenuitem>Ends with</guimenuitem> - similar to the above option, our alias will only match if our commands ends with it - for example, <emphasis role="bold">say no, not hi</emphasis> would work, since it ends with <emphasis role="bold">hi</emphasis>.
</para>
<para>
<guimenuitem>Regular expression</guimenuitem> - this is useful for advanced users who want to use regular expressions in their alias matching. If you want to read up on how those work, look <link linkend="regexp">here</link>.
</para>
<para>
Next is the condition field. Again, for our purposes, just leave it as it is. This is used if you only want your alias to go off when a certain condition is true - so you'd put a logical statement here (for example, <emphasis role="bold">$variable == 1</emphasis>). If that statement is true, then the alias will go off.
</para>
<para>
The replacement text(s) field is next, and is just what we want. Here, we'll type in the things we want the alias to do - and since we want our alias to send <emphasis role="bold">hello</emphasis>, we'll just type <emphasis role="bold">hello</emphasis> in here. You can also use &kmuddy;'s internal scripting engine in here to build your scripts, or call your external scripts with the <emphasis>/notify</emphasis> command, or run a script <emphasis>/exec scriptname</emphasis> command. More information
can be found in the <link linkend="triggersadv">More advanced alias/trigger issues</link> section.
</para>
<para>
So now that we typed in the alias name (<emphasis role="bold">hi</emphasis>), and also our replacement text (<emphasis role="bold">hello</emphasis>), the alias is fully functional. Just click <guimenuitem>Ok</guimenuitem> and <guimenuitem>Done</guimenuitem>, and you're all set.
</para>
<para>
However, for advanced scripting purposes, &kmuddy; also offers you a testing area where you can test the aliases as you're making them.
</para>
<para>
In the text field, you can type in sample commands, and below that in the <guimenuitem>commands:</guimenuitem> field, &kmuddy; will echo how it will execute those commands.
</para>
<para>
Below that is a table with all pseudo-variables that matched, and their respective data. But be aware that they only work if you select a regex match. To read up on how they work, click <link linkend="pseudovars">here</link>.</para>
<para>
If desired, it is possible to disable aliases entirely, by using
<guimenu>Profile</guimenu> / <guimenuitem>Macro keys enabled</guimenuitem>.
</para>
<para>
There is also an <guimenuitem>options</guimenuitem> tab for more advanced settings on how aliases are handled:
</para>
<para>
<guimenuitem>Send original command</guimenuitem> - sends the original command you sent first, along with any commands that your replacement script executes.
</para>
<para>
<guimenuitem>Case sensitive</guimenuitem> - if checked, &kmuddy; will differentiate between upper- and lower-case letters, otherwise it'll treat them as the same character.
</para>
<para>
<guimenuitem>Global matching</guimenuitem> - with this on, a single pattern can match multiple times on a single line, if the line contains the pattern multiple times (for example, a pattern of <emphasis role="bold">abc</emphasis> and sub-string matching selected, will match on a line <emphasis role="bold">abc-abc-abc</emphasis> three times).
</para>
<para>
<guimenuitem>Whole words only</guimenuitem> - if enabled, &kmuddy; will only match the alias if there are no extra spaces before/after the alias. This option if useful if you want to avoid alias matching when it's not neeeded.
</para>
<para>
<guimenuitem>Include prefix/suffix</guimenuitem> - with this option on, &kmuddy; will append prefixes and suffixes (if any are avialable) to all lines your script sends. For example, if your alias is <emphasis role="bold">abc</emphasis> and you select sub-string matching, along with this option, and have the alias do <emphasis role="bold">someone</emphasis>, and you do <emphasis role="bold">tell abc bye</emphasis>, &kmuddy; will send <emphasis role="bold">tell someone bye</emphasis> - as you can see, it effectively functions as a variable.
</para>
<para>
Group - select which group this alias belongs to. See <link linkend="atgroups">alias groups</link> for more information.
</para>

<para>
Aliases are expanded in the order you specify - so keep this in mind when ordering aliases,
so you aren't surprised if another form of expansion takes place. Aliases are not yet expanded
 recursively, there is only one expansion per command.
</para>

</sect2>
<sect2 id="triggers">

<title>Using triggers</title>
<para>
Triggers are commands that are executed when some specific text arrives from the MUD.
For example, triggers can check for the text <emphasis role="bold">You are hungry.</emphasis> and issue the command <emphasis role="bold">eat bread</emphasis>.
</para>
<para>
Triggers are only available for profile-based connections in <guimenu>Profile</guimenu>
/ <guimenuitem>Triggers</guimenuitem>. Here you can manage your triggers.
</para>
<para>
Triggers are dealt with the same way aliases are - you can <guimenuitem>Add</guimenuitem>, <guimenuitem>Modify</guimenuitem>, <guimenuitem>Delete</guimenuitem>, and move them about in the order that they're being matched.
</para>
<para>
Triggers are similar to aliases,  with the exception that they match text from the server and not from your commands. See the above section for the explanation of the <guimenuitem>Basic</guimenuitem> and the <guimenuitem>Options</guimenuitem> tabs. Besides that, &kmuddy; can also do <link linkend="color_triggers">color</link>, <link linkend="rewrite_triggers">rewrite</link>, <link linkend="gag_triggers">gag</link>, and <link linkend="output_windows">output windows</link> triggers.
</para>
<para>
Triggers can be used execute simple actions for you (as the above hungry example), or for executing complex scripts. For the latter, see the <link linkend="internalscripting">internal scripting</link> commands or the <link linkend="external_script">external scripting</link> section.
</para>
<para>
You can test your trigger when you're editing it in the test area, to be sure that it does what you
expect. Especially useful with regular expressions and pseudo-variables - see the next section for that.
</para>
<para>
If desired, it is possible to disable triggers entirely, by using <guimenu>Profile</guimenu> / <guimenuitem>Triggers enabled</guimenuitem>.
</para>
</sect2>
<sect2 id="variables">
<title>Variables</title>
<sect3 id="variables_basic">
<title>Variable basics</title>
<para>
Basically, variables are special data types that store whatever you want them to. Variable names always begin with "$". The name of a variable may only contain letters and numbers. Therefore, possible legal variable names are $a, $variable, $bah44, and so on. Whenever &kmuddy; executes a command, it looks to see if a variable with that name exists. If so, the variable name (including the $ prefix) is replaced by the variable value.
</para>
<para>
For example, assume that you have variables called $enemy and $weapon, and an alias called <emphasis role="bold">hh</emphasis> that expands into <emphasis role="bold">hit $enemy with $weapon</emphasis>. We assume that the variable $enemy contains <emphasis role="bold">orc</emphasis> and $weapon contains <emphasis role="bold">sword</emphasis>. Then, whenever you send <emphasis role="bold">hh</emphasis>, the actual command sent will read <emphasis role="bold">hit orc with sword</emphasis>. Variables allow you to change the value at any time, and allow your alias to expand into something different. The variable can be changed within the GUI or by using the /set function - for example, <emphasis role="bold">/set enemy zombie</emphasis>. All further <emphasis role="bold">hh</emphasis> aliases will now expand into <emphasis role="bold">hit zombie with sword</emphasis>, unless of course, the value of the variable is changed again :).
</para>
<para>
The real power of variables becomes visible when calling /set commands in aliases and/or triggers. Thus, you can have a trigger that updates $weapon when the mud outputs "You wield ...", and another trigger that updates the value of $enemy when you receive something like "... attacks you!". Then you can have your triggers decide to  take appropriate action depending on the values in the variables.</para>
<para>
Variables are only available for profile-based connections. There is a GUI for managing variables available at <guimenu>Profile</guimenu> / <guimenuitem>Variables</guimenuitem>. You can also use the following commands to manage the variables. These commands can be entered at the input-line, or can be embedded within a trigger or an alias.
</para>
</sect3>
<sect3 id="variables_types">
<title>Types of variables</title>
<para>
Variables are automatically re-typed between numeric and string values as necessary, so you
can perform usual arithmetical operations on them. Have a look at <link linkend="expressions">expressions</link> for more information.
</para>
<para>
There are three types of variables. Regular variables, sets (lists) and arrays.
<itemizedlist>
<listitem><para><emphasis>Regular variables</emphasis>
can be accessed using the standard methods described in the <link linkend="expressions">expressions</link> section.
</para>
</listitem>
<listitem><para><emphasis>Sets</emphasis>
are manipulated using <emphasis>/additem</emphasis>, <emphasis>/delitem</emphasis> and
<emphasis>contains()</emphasis>. Sets are meant to hold an unordered list of values, and the
<emphasis>contains()</emphasis> function queries whether a particular value is held within the
set. Sets have no ordering. Set manipulation functions do not work on arrays.
</para>
</listitem>
<listitem><para><emphasis>Arrays</emphasis>
work like regular arrays in programming languages. They allow to hold multiple values
within one variable, each stored in one position. The positions are numbered, and their amount is not restricted - the array will automatically grow to hold all the values that you want to keep in it.They are manipulated using <emphasis>/arrayset</emphasis>,
<emphasis>/arraydel</emphasis> and <emphasis>item()</emphasis>. With arrays, you can
maintain an ordering, as you specify the position where you want to place a given item to.
Array manipulation functions do not work on sets.
</para>
</listitem>
</itemizedlist>
</para>
<para>Have a look at the <link linkend="internalscripting">Internal scripting</link> and
<link linkend="functions">Functions</link> section for a more detailed description of the
aforementioned macros and functions.</para>
</sect3>
</sect2>
<sect2 id="internalscripting">
<title>Internal scripting</title>
<para>
KMuddy contains its own parsing engine, which allows you to write simple scripts. The engine is far from being complete, and we're always looking to integrate new features into it..
</para>
<para>
Two core features exist, which form the internal scripting. Internal scripting commands and <link linkend="expressions">expressions</link>.</para>
<para>
Internal commands are denoted with the "/" character (can be overridden in preferences).
</para>
<para>
The following macros are available:</para>
<para><emphasis>/set</emphasis> varname value - set a variable </para>
<para><emphasis>/unset</emphasis> varname - delete a variable </para>
<para><emphasis>/inc</emphasis> varname number - increase variable value by certain number </para>
<para><emphasis>/dec</emphasis> varname number - decrease variable value by certain number </para>
<para><emphasis>/provide-res</emphasis> varname - provide a resource (increases variable by 1); usable in scripts </para>
<para><emphasis>/request-res</emphasis> varname - request a resource (decreases by 1, fails if current value is 0); usable in scripts </para>
<para><emphasis>/setval</emphasis> variable expression - evaluates the expression and puts the result into the given variable. Do not use "[","]" in the expression, it is assumed automatically. The purpose of this command is to allow placing lists and arrays into variables.</para>
<para><emphasis>/lset</emphasis> varname value - like /set, but the variable is local - exists only within the local script.</para>
<para><emphasis>/lunset</emphasis> varname - unsets a local variable.</para>
<para><emphasis>/linc</emphasis> varname value - increases a local variable.</para>
<para><emphasis>/ldec</emphasis> varname value - decreases a local variable.</para>
<para><emphasis>/echo</emphasis> params - echos its parameters. Useful to display variables and output from aliases/triggers.</para>
<para><emphasis>/agroupon</emphasis> group - enables an alias group.</para>
<para><emphasis>/agroupoff</emphasis> group - disables an alias group.</para>
<para><emphasis>/tgroupon</emphasis> group - enables a trigger group.</para>
<para><emphasis>/tgroupoff</emphasis> group - disables a trigger group.</para>
<para><emphasis>/tick</emphasis> - displays time until tick of the tick timer.</para>
<para><emphasis>/ticknow</emphasis> - resets the tick timer.</para>
<para><emphasis>/additem</emphasis> set value - adds a new item to a list variable.</para>
<para><emphasis>/delitem</emphasis> set value - removes an item from a list variable.</para>
<para><emphasis>/arrayset</emphasis> variable index value - sets an array item at position index.</para>
<para><emphasis>/arraydel</emphasis> variable index - removes the value at the given index from the array.</para>
<para><emphasis>/if [expression]</emphasis> value - the commands following the /if will only get executed if the value is non-zero. You will usually want to use an <link linkend="expressions">expression</link> here. Each /if must have its matching /endif, and, optionally, an /else. Ifs can be nested.</para>
<para>
A sample if statement can be the following:
</para>
<para>
<emphasis role="bold">
/if [$i_can_sip == 1 &amp;&amp; ($myhealth &gt; 100 || $mymana &gt; 80)]
</emphasis>
</para>
<para>
<emphasis role="bold">
sip health
</emphasis>
</para>
<para>
<emphasis role="bold">
/endif
</emphasis>
</para>
<para><emphasis>/else</emphasis> - reserves the effect of the last /if - if it matched, then commands after /else will not be executed, and vice versa.</para>
<para><emphasis>/endif</emphasis> - Ends a if-else-endif block.</para>
<para><emphasis>/exec</emphasis> script params - execute an external script. Part of the Scripting plugin.</para>
<para><emphasis>/notify</emphasis> port params - send out a notification to the given port. Part of the Scripting plugin.</para>
<sect3 id="expressions">
<title>Expression syntax</title>
<para>Expressions can be used in any command, be it a command that is to be sent to the server, or a internal scripting command. The expression is denoted in "[" and "]" characters. The string within these characters gets evaluated and the result is inserted to the command instead of the expression.</para>
<para>For example, executing <emphasis>/set $x [2+2]</emphasis> will first evaluate the 2+2 expression, then insert the result to the command - so the command will be /set $x 4, which will set the x variable to 4.</para>
<para>The expression engine supports the following:</para>
<para>$variable - variable value. Types get auto-converted as needed. Arrays and lists don't get auto-converted to strings if not necessary, hence, these variables can be used like this, unlike standard variable expansion outside expressions.</para>
<para>+, -, *, / - arithmetic operations</para>
<para>parentheses can be used to change operator priorities, as usual</para>
<para>conditional operators - &amp;&amp; (AND), || (OR), &gt;, &gt;=, &lt;, &lt;=, == (equal), != (not equal) - these return 1 when true, 0 when not. Suitable to be used within the /if command, or the conditional triggers.</para>
<para>FUNCTION(PARAM1,...,PARAMn) - a function, see below for list. Note that for the function to be evaluated properly, you need to enclose it as an expression - for example, [strlen("hi")]. And lastly, enclose strings in quotes (as the previous example shows).</para>
</sect3>
<sect3 id="functions">
<title>Functions</title>
<para><emphasis>Built-in functions:</emphasis></para>
<para><emphasis>contains</emphasis>(variable,item) - returns 1 if the given list variable contains a given item</para>
<para><emphasis>item</emphasis>(variable,index) - returns value stored in the given array variable at position index.</para>
<para><emphasis>count</emphasis>(variable) - returns count of a provided array or list variable.</para>
<para><emphasis>global</emphasis>(variable) - returns value of a global variable with the given name.</para>
<para><emphasis>local</emphasis>(variable) - returns value of a local variable with the given name.</para>
<para><emphasis>attrib</emphasis>(object, name) - attribute of a KMuddy object. Not usable at the moment.</para>
<para><emphasis>strattrib</emphasis>(object, name) - string attribute of a KMuddy object. Not usable ta the moment.</para>
<para><emphasis>Functions available in the STRINGS plug-in:</emphasis></para>
<para>IMPORTANT: these functions do NOT modify the original variable, they return the modified result for you to work with. If you want to modify the value, you need to do something like: /set $var [lower($var)]</para>
<para><emphasis>lower</emphasis>(string) - returns string value converted to lowercase.</para>
<para><emphasis>upper</emphasis>(string) - returns string value converted to uppercase.</para>
<para><emphasis>caps</emphasis>(string) - returns string value where first letter of each word is uppercase, and the rest lowercase</para>
<para><emphasis>left</emphasis>(string,c) - returns first c letters of the string</para>
<para><emphasis>right</emphasis>(string,c) - returns last c letters of the string</para>
<para><emphasis>mid</emphasis>(string,c,len) - returns len letters from the string, starting at position c. Positions are indexed from 0. For example, mid("abcdef",2,2)="cd"</para>
<para><emphasis>strlen</emphasis>(string) - returns length of a given string.</para>
<para><emphasis>trim</emphasis>(string) - removes spaces from beginning and end of the string.</para>
<para><emphasis>strpos</emphasis>(haystack,needle) - searches for needle in haystack, returns position if found, -1 if not.</para>
<para><emphasis>strfill</emphasis>(string,len) - if the string's length is less then len, append spaces to the string and return the result. Otherwise return the unmodified string.</para>
<para><emphasis>strleftfill</emphasis>(string,len) - like strfill, but spaces get prepended to the beginning.</para>
<para><emphasis>strcat</emphasis>(str1,str2,...strn) - concatenate strings and return the result as one string.</para>
<para><emphasis>join</emphasis>(list,sep) - converts a list/array to a string, with the given separator. Separator defaults to "|".</para>
<para><emphasis>explode</emphasis>(list,sep) - fills a list from a string, using sep as separator ("|" by default)</para>
<para><emphasis>replace</emphasis>(str,from,to) - replaces all occurences of string "from" in the string "str" to string "to" and returns the result.</para>
</sect3>
</sect2>
<sect2 id="triggersadv">
<title>More advanced alias/trigger issues</title>
<para>
There are also some more advanced options for aliases/triggers. These include
regular expressions, pseudo-variables and back-references.
</para>
<sect3 id="regexp">
<title>Regular expressions and back-references</title>
<para>
<emphasis>Regular expressions</emphasis> are special expressions that allow advanced
searching of certain patterns. Complete documentation of these is beyond the scope of
this manual, please refer to regexp manpage or to KRegExpEditor documentation.
Here I'll only include some basics to get you started.
</para>
<para>
Matching with regular expressions works like standard matching, only that some
characters have special meaning. For example, regular expression "hello" will match
anything that INCLUDES the hello string as a substring.
</para>
<para>
Character '.' matches one character. For example, "he.." matches hell or help or hello
(substring, remember?).
</para>
<para>
Character '*' says: previous character may appear any number times (including zero).
For example, hel*o matches Theo, helo, hello, hhhhhhhhellllllllloooo, but not hell.
Special combination .* matches anything.
</para>
<para>
Similarly, character '+' says: previous character may appear any number of times, but
at least once.
</para>
<para>
Characters '^' and '$' mean beginning and ending of a string, respectively.
</para>
<para>
Parentheses ('(' and ')') specify sections in the regular expression. They have two
common uses - they can be used to specify a part of expression, that then become
an argument to '+' and '*' operators (and to another ones not mentioned here). For
example, ^(d.)+$ can match do, dodo, dude, dadhdudjdldodqdbdcdu, but not dfd or dffd.
Parentheses are also used as back-references.
</para>
<para>
If you want to use any of special characters as a part of the text, you have to place
a backslash ('\') in front of it. (e.g., Hu\. matches anything that contains Hu.)
</para>
<para>
Regular expressions have much more possibilities, but this should be enough to get you
started. Below is a quick cheat sheet of regex patterns:
</para>
<itemizedlist>
<listitem><para>^ - matches the beginning of a line. Use this whenever possible.</para></listitem>
<listitem><para>$ - matches the ending of a line. Use this whenever possible.</para></listitem>
<listitem><para>() - makes regex remember what it matched, and assign into an appropriate $(number) variable.</para></listitem>
<listitem><para>[A-Za-z] or \w - matches any word.</para></listitem>
<listitem><para>[0-9] or \d - matches any numbers.</para></listitem>
<listitem><para>? - a quantifier, makes it so the previous thing may, or may not match. For example, ^You( happily)? jump\.$ will match both "You happily jump." and "You jump." (remember your spaces also).</para></listitem>
<listitem><para>+ - another quantifier, matches the previous item one or more times.</para></listitem>
<listitem><para>* - another quantifier, matches the previous item none or more times.</para></listitem>
<listitem><para>| - special characeter, which means "or". For example, "^You take (his|her) stuff\.$" will match "You take his stuff." and "You take her stuff."</para></listitem>
</itemizedlist>
<para>
Back-references are parts of a regular expression that are in parentheses. They are
counted in the order in which they appear. For example, consider the regular expression
<userinput>a((b)+)c</userinput> . Back-reference 0 is the whole expression.
Backreference 1 is <userinput>(b)+</userinput> and backreference 2 is
<userinput>b</userinput> . If matching text is abbbbcdd, then backref 0 is abbbbc
(matching part), backref 1 is bbbb, backref 2 is b. Easy, isn't it?
</para>
</sect3>
<sect3 id="pseudovars">
<title>Pseudo-variables</title>
<para>
<emphasis>Pseudo-variables</emphasis> are special strings that expand into parts
of text being matched. Pseudo-variables are most useful in conjunction with regular
expressions. The following pseudo-variables are available:
</para>
<para>
<userinput>$matched</userinput> - part of the string that matched the alias/trigger
text or expression.
</para>
<para>
<userinput>$prefix</userinput> - everything that is before the matching part.
</para>
<para>
<userinput>$suffix</userinput> - everything that is after the matching part.
</para>
<para>
<userinput>$prefixtrim</userinput> - $prefix with leading/trailing spaces omitted.
</para>
<para>
<userinput>$suffixtrim</userinput> - $suffix with leading/trailing spaces omitted.
</para>
<para>
<userinput>$0, $1, $2, ...</userinput> - back-reference with that number. See
previous section for more information on back-references. These pseudo-variables
only exist if you use regular expression matching.
</para>
<para>
<userinput>$line</userinput> - a special variable that always contains the current line
number at the point where the trigger or alias was executed.  It does NOT require the
use of regular expressions as it is a variable in its own right and is always available.
</para>
<para>
Pseudo-variables can be used in the alias replacement text and in the triggered
command; they will expand to the value that they hold.
</para>
<para>
IMPORTANT: Note that an improper setting
of this may allow other players to make you execute any command they want, so
be prepared for this. The best way to prevent this is to disallow matching when
separator character (';') is in the text (in some trigger that gets matched before
the critical one, maybe?).
</para>
<para>
Remember that you can experiment with all these in the alias/trigger test area.
There you can also look at which pseudo-variables are available and what value they will
have for the text you've entered.
</para>
</sect3>
<sect3>
<title>Global matching and conditional triggers</title>
<para>Normally, each trigger only matches once per line. This sometimes isn't desirable, especially with colorization triggers, where you often want to have all occurences of a certain word colored. In this situation, you can enable the "Global matching" option. This will make the trigger execute multiple times on one line, if there are multiple matches of the trigger pattern within said line.</para>
<para>Conditional triggers allow you to specify a condition that must be met for the trigger to execute. You can use <link linkend="pseudovars">pseudo-variables</link> within the condition. For more information regarding the condition syntax, refer to section about <link linkend="expressions">expressions</link>. Note that you must not include the "[" and "]" separators for the condition - these are assumed automatically.</para>
</sect3>

</sect2>
<sect2 id="spectriggers">
<title>Special-purpose triggers</title>
<para>
In addition to its standard trigger, each trigger can also have a specialized function(s):
</para>
<sect3 id="color_triggers">
<title>Color triggers</title>
<para>
Color triggers can be used to colorize text that's received from the server. When a trigger match
occurs, instead of sending some text, you can have the matched text colorized any way you want.
Of course, you can also do both - send a command and colorize the text.
</para>
<para>
The colorization dialog itself should be pretty self-explanatory. You simply enter a list of items that
should be re-colorized and the desired colors. Some parts may be overlapping; in that case, these parts
are colorized in order in which they are specified. "Keep" means keep original color, neutralizing effect
of previous colorization entries on the appropriate portion of the string (useful for things like
colorize backref1 but not backref2 that's a substring of backref1). If you want to select a custom color, select the "Other" option, and then click on the little color box below to select your color. Once you're done picking what colors you want, click on the <guimenuitem>Add</guimenuitem> button to add the colorization.
</para>
<para>You will usually want to enable the Global matching option for colorization triggers, so that other non-colotization triggers can still match on that line.</para>
</sect3>
<sect3 id="gag_triggers">
<title>Gagging</title>
<para>
Gagging is a feature that allows you to have some text not displayed at all. But you should be careful
when setting up a gagging trigger, so that it doesn't hide more than you expect. Information is power,
you know. :P. To select the gagging option for a trigger, check off the "Don't show (gag) the line" option under the <guimenuitem>Special trigger</guimenuitem> tab in the edit trigger dialog.
</para>
</sect3>
<sect3 id="notify_triggers">
<title>Notification triggers</title>
<para>
Notification triggers are useful, if you want to have notification support, but only for certain
events. You need to have <emphasis>Always notify</emphasis> disabled for this to work. Then, when
&kmuddy; and/or the connection is inactive, and the notification trigger matches, a notification
event will occur.
</para>
</sect3>
<sect3 id="prompt_triggers">
<title>Prompt-detection triggers</title>
<para>
Since version 0.5.1, incoming lines are only displayed after a newline character has been received.
This makes problems when a prompt arrives, because it won't be displayed until next end-line character,
but it won't be received until you send another command. To have a prompt displayed, two possible
approaches are available. First of them is the Go-Ahead signal; if your MUD supports it, you can ask
it to send you the GA signal after each prompt; &kmuddy; will detect this and display the prompt
correctly.
</para>
<para>
The GA signal is a great thing, however, lots of MUDs just don't support it properly or not at all.
The prompt-detection triggers exist to handle this problem. When an unfinished line is received, it's
matched against all P-D triggers; if some trigger matches, then the text is considered a prompt and
displayed as such.
</para>
<para>
Most other trigger options don't take effect for P-D triggers. Also, standard lines don't get matched
against P-D triggers.
</para>
<para>
The prompt will be displayed even if none of these mechanisms are used, because
&kmuddy; automatically assumes that a string that remains in the buffer for
at least one second, without anything more received, is treated as a prompt
and displayed as such. This is helpful in case of various unpredictable
prompts - when creating a new character, for example -- you'll see the
prompt, but you'll have to wait a bit for it.
</para>
<para>
Please note that there can be only one prompt per line. Thus, when something was considered a prompt and
some more text is received (without end-of-line char), it will not be tested if it's a prompt (even if
the GA signal arrives), so be careful when writing these triggers.
</para>
<para>
Example of a prompt-detecting trigger, that should be enough to get you started:
</para>
<para>
Let the prompt look like this: <userinput>[50hp 50mp 50mv] </userinput> (with one trailing space).
Then the trigger that detects this type of prompt, but nothing else, will look like this (using
regexp matching): <userinput>^\[[0-9]+hp [0-9]+mp [0-9]+mv\] $</userinput>.
The <userinput>[0-9]+</userinput> sequence matches any number, <userinput>^, $</userinput> characters
mean that nothing more is allowed on the line, backslashes are needed before [] chars, so that they're
not interpreted by the regexp matcher.
</para>
</sect3>
<sect3 id="sound_triggers">
<title>Sound triggers</title>
<para>
Sound triggers allow you to have a sound played on certain events. Note that this has nothing to do
with the MSP protocol; this is handled completely on the client-side. Also note that sound triggers are only
available is you have sound support built in.
</para>
</sect3>
<sect3 id="rewrite_triggers">
<title>Rewrite triggers</title>
<para>
Rewrite triggers allow you to alter how text received from the MUD is displayed to you.  So if your MUD
sends "You fall over and end up on the ground" you could change it to appear as "You stumble and fall". To use this option, head over to the <guimenuitem>Rewrite text</guimenuitem> tab of the edit trigger dialog, and enable the "Text rewrite trigger." option. Then simply select what part of the line you want to change (if it's a backreference - $1-9 regex things - then select it's number below), write the new text you want the line to be replaced with, and select <guimenuitem>Ok</guimenuitem>!
</para>
</sect3>
</sect2>
<sect2 id="atgroups">
<title>Alias/trigger groups</title>
<para>
The purpose of alias/trigger groups is to split all aliases and triggers into several
manageable groups, with the possibility to activate and deactivate individual groups.
The groups can be administered in <guimenu>View</guimenu> / <guimenuitem>Show alias groups</guimenuitem>
and <guimenu>View</guimenu> / <guimenuitem>Show trigger groups</guimenuitem>. These dialogs
are non-modal, so you can keep them open and activate/deactivate groups as needed.
</para>
<para>
Please Note that alias and trigger groups are completely separate. You can have different
groups of each type. They are documented together, as their principle and usage is the same.
</para>
<para>
By default, there is a single group called BASE. This group contains aliases or
triggers that are not allocated anywhere else. It can not be removed nor renamed.
</para>
<para>
By un-checking the checkbox next to a group name, you deactivate that group. By checking
it you re-activate it. The add/rename/delete buttons can be used to manipulate the
list of groups.
</para>
<para>
Adding an alias/trigger to a group is simple - just go to the Aliases or Triggers dialog
box, and change the group of the relevant appropriate alias/trigger.
</para>
</sect2>
<sect2 id="toolbar">
<title>Action toolbar</title>
<para>
Actions let you define buttons on a toolbar that execute a command when clicked.
Handy if you don't like typing much.
</para>
<para>
Actions are only available for profile-based connections in <guimenu>Profile</guimenu>
/ <guimenuitem>Actions</guimenuitem>. Here you can manage your actions.
</para>
<para>
Note that you can show/hide the action toolbar with <guimenu>View</guimenu> /
<guimenuitem>Show action toolbar</guimenuitem>
</para>
</sect2>
<sect2 id="output_windows">
<title>Output Windows</title>
<para>
Output windows are external windows that can store various text from the MUD - like tells, channels, or anything else.
</para>
<para>
To view which output windows do you currently have, and to show/hide/delete any, go to <guimenu>Profile</guimenu> -
<guimenuitem>Output Windows...</guimenuitem>. From there, you can either delete them, hide them (so they aren't shown, but still exist), or show them (if they were hidden).
</para>
<para>
You can create a new output window via the <guimenu>Edit Trigger</guimenu> dialog. Simply create a new trigger, or modify an existing one, and click the <guimenuitem>Output Windows</guimenuitem> tab on top. Select the <emphasis>Send output to a separate window</emphasis> option, then fill in the desired window name, and click <emphasis>Create window</emphasis>.
</para>
<para>
To be able to actually use the output windows though, you need to make a trigger that'll send the text to your window. For that to work, select the <emphasis>Send output to a separate window</emphasis> and pick a window to which you want the text to be sent to under <emphasis>Select window</emphasis>. Optionally, you can select the <emphasis>Gag output in main window</emphasis> option if you want the text to be only displayed in the output window, and not in the main &kmuddy; window also.
</para>
<para>
<emphasis role="bold">Sample output window:</emphasis>
</para>
<para>
Let's say you want to have an output window that'll store all information about people coming into your room, with a sample entrance being the following: <emphasis>Anna arrives from north.</emphasis>.
</para>
<para>
To start, create a new trigger, with regex (<emphasis role="bold">reg</emphasis>ular <emphasis role="bold">ex</emphasis>pression) pattern of <emphasis role="bold">^[A-Za-z]+ arrives from [a-z]+\.$</emphasis>. This trigger will match any lines where people come in. Next, head over to the <emphasis>Output windows</emphasis> tab. Check off the <emphasis>Send output to a separate window</emphasis> box, and create a new output window - type in it's name in the <emphasis>Window name</emphasis> box, and click the <emphasis>Create window</emphasis> button. After that, you can select the newly-created window in the <emphasis>Select window</emphasis> drop-down box. Now, all lines will be directed to the output window also. You can optionally check off the <emphasis>Gag output in main window</emphasis> option if you want the line to only appear in the output window, and not in both the output and main windows.
</para>
</sect2>
<sect2 id="timers">
<title>Timers</title>
<para>
Timers allow you to schedule a command to be run periodically, or once at some time in the future
(well, provided that we define future as "anything that will happen in less that one hour", for that's
the limit).
</para>
<para>
Timers are only available for profile-based connections in <guimenu>Profile</guimenu>
/ <guimenuitem>Timers</guimenuitem>. Here you can add, modify, delete, activate or deactivate your timers.
</para>
<para>
To add a new timer, click the <emphasis>Add</emphasis> button. Type the command you want the timer to execute in the <emphasis>Command</emphasis> field. Optionally, you can also use the \n string to separate your commands, or have the timer call an alias you made for more advanced scripting abilities. Select the interval at which you want the timer to fire, and if you want the timer to go off only once, select the 'Single-shot' option.
</para>
<para>
It's also possible to disable timers entirely, if desired, by unselecting
<guimenu>Profile</guimenu> / <guimenuitem>Timers enabled</guimenuitem>.
</para>
</sect2>
<sect2 id="tick_timer">
<title>Tick timer</title>
<para>
Some MUDs have a single timer, upon which a number of events happen (such as mobs respawning, weather changes, etc.). A tick timer helps you approximate when that time comes, and &kmuddy; provides and helps you with that.</para>
<para>
To get started, go to <guimenu>Profile</guimenu> - <guimenuitem>Tick timer...</guimenuitem>. The <emphasis>Tick interval</emphasis> option sets the time (in seconds) at which the tick timer expires and starts counting down again, and the <emphasis>Timeout margin</emphasis> option sets time, at which when the timer reaches it it'll execute the <emphasis>Command</emphasis>.
</para>
</sect2>
<sect2 id="macrokeys">
<title>Macro keys</title>
<para>
Macro keys allow you to define a command that will be sent to the MUD (or placed in the input-line)
whenever a key or a combination of keys are pressed. Macro's are often used for things like numpad walking
(assigning direction commands to the numpad keys).
</para>
<para>
Note: avoid assigning Macro keys that are used for actions in menu or elsewhere.
Macro keys are evaluated before actions, so you would be unable to use the key combination for that
purpose (you'll still be able to use the mouse to access the actions, of course).
Also, assigning a character is not very wise, as you'll be unable to type text that includes that
character. It is generally recommended to add a modifier such as Alt or Ctrl to avoid clashes.
</para>
<para>
Macro keys are only available for profile-based connections in <guimenu>Profile</guimenu>
/ <guimenuitem>Macro keys</guimenuitem>. Here you can manage your macro keys.
</para>
<para>
It's also possible to disable macro keys entirely, if desired, by using
<guimenu>Profile</guimenu> / <guimenuitem>Macro keys enabled</guimenuitem>.
</para>
</sect2>
<sect2 id="variable_triggers">
<title>Variable triggers</title>
<para>
Variable triggers lets you create a monitoring condition for a variable, such that when it is changed, the command you set to be executed will be called.
</para>
</sect2>
<sect2 id="status_variables">
<title>Status variables</title>
<para>
They're variables who's status can be displayed at the bottom of the status bar.
</para>
</sect2>
<sect2 id="gauges">
<title>Gauges</title>
<para>
Fun things like health gauges and all.
</para>
</sect2>

</sect1>


<sect1 id="external_script">
<title>External Scripting</title>
<sect2 id="scripts_introduction">
<title>Introduction to scripting</title>
<para>
<emphasis>External scripting</emphasis> is probably the most powerful feature in &kmuddy; (in my
opinion at least). It allows you to write programs or scripts that can help you play,
perform some actions for you, or even play entirely for you! (if you know enough about AI,
that is).
</para>
<para>Note that scripting will only work if you have the scripting plug-in installed and enabled. It comes with the standard KMuddy distribution, so you likely do have it running.</para>
<para>
First of all, you should be aware of one risk involved - many MUDs don't like using
scripting too much, especially when it's used to raise some skills and so forth. I
recommend reading the rules of your MUD before using scripts for anything of this sort.
I take no responsibility for your deleted characters or anything else. But don't worry,
scripting can be very useful without violating any rules, so read on! (frustrating
paragraph, isn't it? ;-) )
</para>
<para>
In order to use scripting, you have to know some programming language. No matter which
one, the only condition is that it must support standard input/output (almost all available
languages meet this criteria, maybe Smalltalk is an exception, but who would write
scripts in Smalltalk?). You can also use interpreted languages, like Perl or Python,
and you can even use shell scripts.
</para>
<para>You no longer need to use external scripting for simple tasks, as KMuddy now also offers its own internal scripting language. It is relatively simple, but new features will be added in future versions. Refer to the section about <link linkend="internalscripting">internal scripting</link> for more information.</para>
</sect2>
<sect2 id="scripting_define">
<title>Defining scripts</title>
<para>
Enough of theory, let's go scripting! You can only define scripts for profile-based
connections. The most important thing is the
<guimenu>Profile</guimenu> / <guimenuitem>Scripts</guimenuitem> dialog box. Here you can
define all the scripts you'll be using. Important options are:
</para>
<para>
<emphasis>Script name</emphasis> defines a name for this script. You can use it later
to invoke this script from the input line or from an alias or a trigger.
</para>
<para>
<emphasis>Command to execute</emphasis> defines a command that is to be executed.
If the executable/path contains spaces, you can use backslashes or quoting, as usual.
This can also include parameters. Note that if you want to be able to specify
additional parameters when launching this script from the input line, you'll have to
enable the <emphasis>Allow custom parameters</emphasis> option.
Remember that you have to write the script first. Depending on the language you choose,
you may also need to compile it prior to using it.
</para>
<para>
<emphasis>Working directory</emphasis> defines a working directory for your script.
This is only needed if your script works with other files.
</para>
<para>
The default script location and default working directory can be set in
<guimenu>Profile</guimenu> / <guimenuitem>MUD preferences</guimenuitem>.
</para>
<para>
<emphasis>Enable script input</emphasis> enables sending of mud server output to the script.
If you also enable <emphasis>Send user commands</emphasis>, then both server output
and your commands will be sent to the script. To distinguish between these, you may
want to <emphasis>Enable adv. communication</emphasis>, which allows your script to
identify lines by prepending the numbers 1, 2, and 3 in front of them. Lines of server output
have number 1, user commands have number 2. If your MUD supports sending of GA (go-ahead) signal,
then you'll also receive lines with number 3, containing the prompt. Note that the following 1-line
will include that prompt as well, so keep this in mind.
Also note that your script has to support this type of identification.
</para>
<para>
The GA (go-ahead) signal means that the server is ready to accept new input, so you can use the 3-lines
for that purpose. Also note that you may need to use some server command to ask it to send you GA
signals. Even if the server does this by default, older versions of &kmuddy; (up to 0.4.1) were sending
the SUPPRESS-GA option to the server. It's therefore likely that you will have GA-sending disabled if
you used the older versions with that MUD.
</para>
<para>
IMPORTANT: If your script reads anything from its standard input, you must
either enable script output or use shell expansion and let it read input from a file.
Otherwise results may not be as expected.
</para>
<para>
<emphasis>Enable script output</emphasis> will catch output from the script and either
display it to you or send it as a command to the MUD, depending on the
<emphasis>Send script output</emphasis> option. Note that script output may have
two different parts - standard output and error output. Error output will only be
included if you enable the <emphasis>Include error output</emphasis> option.
</para>
<para>
<emphasis>No flow control</emphasis> disables the flow control mechanism for this script.  Flow
control is applied by default to all scripts and will carefully control how information is fed
into scripts to make sure they are all processing the same line received from the MUD at the same
time.  This prevents the situation where one script is processing line 10 while another is processing
line 5, which can cause a lot of headaches.  A flow controlled script must process all input quickly,
to prevent holding up all other running flow controlled scripts.
</para>
<para>
<emphasis>Communicate variables</emphasis> allows the script to create, read and alter the variables defined
in <guimenu>Profile</guimenu> / <guimenuitem>Variables</guimenuitem>.  You MUST set this option if you plan
on using the <userinput>getVariable()</userinput>
and <userinput>setVariable()</userinput> functions in your script.
</para>

<para>
<emphasis>Output prefix</emphasis> and <emphasis>Output suffix</emphasis> specify
strings that will be prepended / appended to every line of script output prior to
displaying or sending it. Note that if you want to separate the prefix/suffix with a space,
you have to include that space too.
</para>
<para>
<emphasis>Enable shell expansion</emphasis> will run your command via shell, allowing
you to use all sorts of shell expansion like wildcards or pipes.
</para>
<para>
<emphasis>Single-instance script</emphasis> allows only one instance of the script to
be running at any time. Please note, if you maintain multiple connections using the same profile
(strange, but could happen), then every connection can have a single instance of the script
running.
</para>
<para>
<emphasis>Matching text</emphasis> and <emphasis>Comparison type</emphasis> can be
used to filter text/commands that are sent to the script. Their usage is comparable to
similar options available for aliases and triggers. The <emphasis>Positive matching</emphasis>
option determines whether the text is sent when it matches the test (option ON), or
when it does not match it (option OFF).
</para>
</sect2>
<sect2 id="scripts_running">
<title>Running and controlling scripts</title>
<para>
There are two ways how to run a script. The first one is to use the Run! button in
<guimenu>Profile</guimenu> / <guimenuitem>Scripts</guimenuitem>. This is quick and
efficient, but you cannot pass any parameters to the scripts.
</para>
<para>
The second way (which you will probably use much more frequently), is to run it from
the input line - like any other command. This way can also be used to launch the script
from an alias or a trigger (this is where all those possibilities begin).
To execute a script, you just type a script-launching character ('/' by default) followed
with the script name, and, optionally, some parameters. For example, if you want to run
a script called foobar (a very popular name indeed), passing it parameter hello,
you just type <userinput>/foobar hello</userinput> and it's off and running!
Note that there mustn't be any space between the script character and the script name.
</para>
<para>
As an alternative to those who disable the script-launching character for any reason,
the <userinput>\m</userinput> sequence can be used instead of that character.
</para>
<para>
If you want to see a list of all running scripts, you can find it under
<guimenu>View</guimenu> / <guimenuitem>Show running scripts</guimenuitem>.
This will display a list of all running scripts. Several options are available:
</para>
<para>
<emphasis>Suspend</emphasis> and <emphasis>Resume</emphasis> can be used to suspend
and/or resume the script. Note that this is done by sending the SIGSTOP and SIGCONT
signals, so it may not work properly if your script installs a handler for these
(I'm not sure if it is possible to ignore the SIGSTOP signal, but who knows?)
</para>
<para>
<emphasis>Terminate</emphasis> will terminate your script. The script can install
a signal handler that will ignore the SIGTERM signal, so this may not always work.
The <emphasis>Kill</emphasis> command, on the other hand, always kills the script,
there is no resistance :). Please note that it is better to try terminate first and
only use kill as a last option, as it can lead to a loss of script data (if any).
</para>
</sect2>
<sect2 id="notify">
<title>Communicating with scripts using /notify</title>
<para>
One of the commands you can execute as the result of an action, trigger or a command
typed from the input line is the
<emphasis>/notify</emphasis> command.  This will send a line of text to a TCP/IP
port on the local machine.  The general format of the command is:
</para>
<para>
<userinput>/notify portnum data</userinput>
</para>
<para>
The <userinput>portnum</userinput> is just a TCP/IP port number (a number between 1500 and 65535) that your
script is listening to, or a variable
which you have set to a port number, so it's possible to do <userinput>/notify $myport hello there</userinput>,
for instance and <userinput>hello there</userinput> will be transmitted to whatever $myport is set to.
</para>
<para>One reason to use <userinput>/notify</userinput> is efficiency - you can set up triggers in KMuddy
to identify important events and then use <userinput>/notify</userinput> to communicate them to your script. When your
script needs to send information back to KMuddy it can do it using the <userinput>sendCommand()</userinput>
function, described in the
<link linkend="scripts_sendcommand">Sending commands to KMuddy from your own scripts</link> section.
</para>

<para>
Using <userinput>/notify</userinput> makes your scripts shorter and easier to write because you only need
to have them process the important information and not have to sift through many lines of unimportant rubbish.
This helps a lot if you are programming in a language that isn't very good at checking for text patterns
and doesn't directly support regular expressions.  It also provides a clean mechanism to separate the task
of identifying important lines from the MUD (KMuddy triggers) and working out what to do with them (your scripts).
</para>
<para>The <userinput>/notify</userinput> mechanism also has less latency than the
<emphasis>Enable script input</emphasis> / <emphasis>Enable script output</emphasis> method of
communicating with scripts.
</para>
</sect2>
<sect2 id="scripts_tcpip">
<title>Handling /notify in your scripts</title>
<para>
If you are writing your scripts in C, C++, Perl or Ruby, there are example scripts you can use as templates
for receiving data sent using the <emphasis>/notify</emphasis> feature in the <userinput>scripting/</userinput>
directory of the KMuddy package.  More information can be found by reading the comments in the scripts themselves,
but the basic idea is you call the <userinput>initIPPort()</userinput> function to set up which port your script
will listen to, then you call <userinput>getEvent()</userinput> every time you wish to receive an event.  Your
script will go into a highly efficient sleep mode while waiting for an event, using up no CPU time until it
actually has something useful to do.
</para>
</sect2>
<sect2 id="scripts_variables">
<title>Accessing KMuddy variables from your own scripts</title>
<para>
KMuddy has its own set of variables you might wish to manipulate in your own scripts.  If you are writing
your scripts in C, C++, Perl or Ruby, there are example scripts in the <userinput>scripting/</userinput> directory
of the KMuddy package you can read through to get an idea of how it's done.
</para>
</sect2>
<sect2 id="scripts_sendcommand">
<title>Sending commands to KMuddy from your own scripts</title>
<para>
If you are exclusively using <userinput>/notify</userinput> to communicate with your scripts, you should
not use <emphasis>Enable script input</emphasis>, <emphasis>Enable script output</emphasis> or <emphasis>Send script output</emphasis> feature to send commands to KMuddy.  Instead there is
the <userinput>sendCommand()</userinput> function provided in the example scripts in the <userinput>scripting/</userinput>
directory of the KMuddy package.
</para>
<para>The <userinput>sendCommand()</userinput> function uses a similar transport mechanism to
<userinput>/notify</userinput> to communicate
commands to be sent to the MUD.  It has all the same benefits of <userinput>/notify</userinput> - it is more efficient
and less prone to latency. In addition it will halt the running of your script until the command
has actually been sent, which helps keep your scripts syncronised and maximises overall system performance.
</para>
</sect2>
<sect2 id="variables_scripts">
<title>Using variables in external scripts</title>
<para>
&kmuddy; can communicate variable values/changes with external scripts. UNIX domain sockets are used for this purpose. The scripting/ directory in &kmuddy;'s source distribution contains some sample scripts in C, as well as a header file useful for writing other C/C++ scripts. Similar files for perl, python and ruby are available as well.
</para>
</sect2>
</sect1>
</chapter>

<chapter id="FAQs">
<title>Questions and Answers</title>

&reporting.bugs;

<para>
No questions/answers are currently available...
</para>

<!--
<qandaset id="faqlist">
<qandaentry>
<question>
<para>My Mouse doesn't work. How do I quit &kmuddy;?</para>
</question>
<answer>
<para>You silly goose! Check out the <link linkend="commands">Commands
Section</link> for the answer.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>Why can't I twiddle my documents?</para>
</question>
<answer>
<para>You can only twiddle your documents if you have the foobar.lib
installed.</para>
</answer>
</qandaentry>
</qandaset>
-->
</chapter>

<chapter id="credits">

<title>Credits and License</title>

<para>
&kmuddy;
</para>
<para>
Program copyright 2002-2007 Tomas Mecir <email>kmuddy@kmuddy.com</email>
</para>

<para>
Documentation copyright 2002-2007 Tomas Mecir <email>kmuddy@kmuddy.com</email>.
Documentation copyright 2007 Vadim Peretokin <email>vadimuses@gmail.com</email>.
</para>

<!-- TRANS:CREDIT_FOR_TRANSLATORS -->

&underGPL;
&underFDL;

</chapter>

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

<sect1 id="getting-kmuddy">
<title>How to obtain &kmuddy;</title>

<para>
&kmuddy; can be found on its homepage at
<ulink url="http://www.kmuddy.com">http://www.kmuddy.com</ulink>,
where you can also find the most recent information concerning &kmuddy;.
</para>

<para>
If you want to report some problem or to suggest some feature, you can use
the <guimenuitem>Report Bug</guimenuitem> item in the <guimenu>Help</guimenu>
menu. You can also e-mail me at <email>kmuddy@kmuddy.com</email> or use the &kmuddy; forums.
</para>

</sect1>

<sect1 id="requirements">
<title>Requirements</title>

<para>
In order to successfully use &kmuddy;, you need KDE 3.x. You also need
some connection to the internet and a desire to play some MUDs.
</para>

<para>
&kmuddy; can be found on <ulink url="http://www.kmuddy.com">The &kmuddy; home page</ulink>.
</para>

<para>
You can find a list of changes at <ulink
url="http://www.kmuddy.com/changelog.php">http://www.kmuddy.com/changelog.php</ulink>
or in the CHANGELOG file included in the source distribution.
</para>
</sect1>

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

<para>
In order to compile and install &kmuddy; on your system, type the following in the base
directory of the &kmuddy; distribution:
<screen width="40">
<prompt>%</prompt> <userinput>./configure</userinput>
<prompt>%</prompt> <userinput>make</userinput>
<prompt>%</prompt> <userinput>make install</userinput>
</screen>
</para>

<para>
You may want to use some configure options, but that shouldn't be necessary, as all options are
auto-detected. You may want to use --disable-sound or --with-sdl options though, if you don't want
sound support or if you want to use SDL instead of aRts (but that will be done automatically if you don't
have anything needed to compile aRts support).
</para>

<para>Since &kmuddy; uses autoconf and automake you should have not trouble compiling it.
Should you run into problems please report them to <email>kmuddy@kmuddy.com</email>, or
at the &kmuddy; forums..</para>

</sect1>

</appendix>

&documentation.index;
</book>
<!--
Local Variables:
mode: sgml
sgml-minimize-attributes:nil
sgml-general-insert-case:lower
sgml-indent-step:0
sgml-indent-data:nil
End:
-->