<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "/usr/share/xml/docbook/schema/dtd/4.3/docbookx.dtd">
<!-- Define some entities
<!ENTITY ggrtfver "v0.6.0">
<!ENTITY jeskko "<ulink url='http://jeskko.pupunen.net/'>Jarkko Vääräniemi</ulink> (<ulink url='http://www.bat.org/help/finger.php?str=jeskko'>Jeskko</ulink>)">
<!ENTITY ggr "<ulink url='http://ccr.tnsp.org/'>Matti Hämäläinen</ulink> (<ulink url='http://www.bat.org/help/finger.php?str=ggr'>Ggr</ulink>)">
<!ENTITY tfurl "<ulink url='http://tf.tcp.com/'>TinyFugue</ulink>">
<!ENTITY homeurl "<ulink url='http://ccr.tnsp.org/ggrtf/'>http://ccr.tnsp.org/ggrtf/</ulink>">
<!ENTITY svnrepo "<ulink url='http://svn.pupunen.net/public/ggrtf/trunk/'>Subversion-repository</ulink>">
<!ENTITY svnurl "<ulink url='http://subversion.tigris.org/'>Subversion</ulink>">
<!ENTITY batmudurl "<ulink url='http://www.bat.org/'>BatMUD</ulink>">
<!ENTITY pupuneturl "<ulink url='http://www.pupunen.net/'>Pupunen.net</ulink>">
<!ENTITY gnupgurl "<ulink url='http://www.gnupg.org/'>GnuPG</ulink>">
<!ENTITY trackerurl "<ulink url='http://svn.pupunen.net/mantis/'>bugtracker</ulink>">

<!ENTITY exampletfrc "<section><title>Example configuration</title>">
<!ENTITY validval "Valid values:">
<!ENTITY validonoff "<emphasis>on</emphasis>, <emphasis>off</emphasis>">

<!ENTITY colourexplanation "
Colours described here may deviate from what you actually
see due to differences in terminal emulation programs.
">

<!ENTITY sectmacros "<title>Macro commands</title>
<para>&lt;&gt; = required argument, [] = optional argument">

<!ENTITY paravariables "Variables and user-replaceable macros defined
by this module are described in a table below. They have specific
defaults, which you can override in your configuration if you
re-set/re-define them after loading the module. Please refer to
<link linkend='inst-config'>Setup</link>-section of this manual
or see the example configuration for this module.
">

<!ENTITY sectvariables "<title>Settings and user-replaceable macros</title>
<para>
&paravariables;
</para>

<table><title></title>
 <tgroup cols='2' align='left'>
  <thead>
   <row>
    <entry>Variable / macro name</entry>
    <entry>Description</entry>
   </row>
  </thead>
  <tbody>
">

<!ENTITY sectvariablesend "
  </tbody>
 </tgroup>
</table>
">

-->
<book>
<bookinfo>
 <title>The GgrTF User's Guide</title>
 <authorgroup>
  <author><firstname>Matti</firstname><surname>Hämäläinen</surname></author>
  <author><firstname>Jarkko</firstname><surname>Vääräniemi</surname></author>
 </authorgroup>
 <copyright>
  <year>2006-2007</year>
  <holder>Matti Hämäläinen (Ggr Pupunen)</holder>
 </copyright>
 <pubdate>2007</pubdate>

<legalnotice>
<para>
This document is distributed under
<ulink url="http://creativecommons.org/licenses/by-sa/2.5/legalcode">Creative Commons Attribution-ShareAlike 2.5 license</ulink>,
of which full version can be found from <ulink url="http://creativecommons.org/">Creative Commons website</ulink>.
</para>

<para>
THE WORK (AS DEFINED BELOW) IS PROVIDED UNDER THE TERMS OF THIS CREATIVE
COMMONS PUBLIC LICENSE ("CCPL" OR "LICENSE"). THE WORK IS PROTECTED BY
COPYRIGHT AND/OR OTHER APPLICABLE LAW. ANY USE OF THE WORK OTHER THAN AS
AUTHORIZED UNDER THIS LICENSE OR COPYRIGHT LAW IS PROHIBITED.
</para>

<para>
BY EXERCISING ANY RIGHTS TO THE WORK PROVIDED HERE, YOU ACCEPT AND AGREE
TO BE BOUND BY THE TERMS OF THIS LICENSE. THE LICENSOR GRANTS YOU THE
RIGHTS CONTAINED HERE IN CONSIDERATION OF YOUR ACCEPTANCE OF SUCH TERMS
AND CONDITIONS.
</para>
</legalnotice>
</bookinfo>

<!-- *************************************************************** -->

<chapter id="preface"><title>Preface</title>

<section id="whatisggrtf"><title>What is GgrTF?</title>

<para>
GgrTF is a <emphasis>framework</emphasis> of AND for triggers to
ease playing of &batmudurl; with &tfurl; MUD-client. GgrTF is designed for
modularity and easy development. Our primary development goals
are good overall quality of code and maintainability.
These are also some of the key elements, that differentiate
GgrTF from most other publicly available scripts.
</para>

<para>
GgrTF is being developed and tested simultaneously on versions 4
and 5 of &tfurl; MUD client under Linux and Solaris platforms.
There are some features that are only available to users of
&tfurl; 5, though. Users of GgrTF are mostly users of UNIX-like
systems, but there are several who run TF under Microsoft Windows
operating system.
</para>

<para>
The current version (as of &ggrtfver; release) has modules
for following character classes:
</para>
<itemizedlist>
 <listitem><para><link linkend="usage-magical">Mages</link> (<ulink url="http://www.bat.org/help/guilds.php?str=The+Brotherhood+of+Wizardry">The Brotherhood of Wizardry</ulink>)</para></listitem>
 <listitem><para><link linkend="usage-chann">Channellers</link> (<ulink url="http://www.bat.org/help/guilds.php?str=The+Guild+of+Channellers">The Guild of Channellers</ulink>)</para></listitem>
 <listitem><para><link linkend="usage-merchant">Merchants</link> (<ulink url="http://www.bat.org/help/guilds.php?str=The+Master+Merchants">The Master Merchants</ulink>)</para></listitem>
 <listitem><para><link linkend="usage-barb">Barbarians</link> (<ulink url="http://www.bat.org/help/guilds.php?str=Barbarian+Guild">Barbarian Guild</ulink>)</para></listitem>
 <listitem><para><link linkend="usage-loc">LoCs</link> (<ulink url="http://www.bat.org/help/guilds.php?str=Lords+of+Chaos">Lords of Chaos</ulink>)</para></listitem>
 <listitem><para><link linkend="usage-tarma">Tarmalens</link> (<ulink url="http://www.bat.org/help/guilds.php?str=The+Followers+of+Tarmalen">The Followers of Tarmalen</ulink>)</para></listitem>
 <listitem><para><link linkend="usage-druid">Druids</link> (<ulink url="http://www.bat.org/help/guilds.php?str=The+Humble+Druids">The Humble Druids</ulink>)</para></listitem>
 <listitem><para><link linkend="usage-nun">Nuns</link> (<ulink url="http://www.bat.org/help/guilds.php?str=Sisters+of+Las">Sisters of Las</ulink>)</para></listitem>
</itemizedlist>
<!--
<para>
Also a somewhat old module for <link linkend="usage-alch">alchemists</link> exists, but has not been updated/tested for a while.
</para>
-->

<para>
In non-guild related sense, GgrTF has most of the basics expected from
such triggerset. There is a <link linkend="usage-general-prots">prot-management and reporting
system</link>, <link linkend="usage-general-skillspell">spell- and skill-handling</link>, way to
easily <link linkend="usage-general-commands">run commands on each battle round</link>
(and more), <link linkend="usage-pssmangle">pss-output mangling</link>,
<link linkend="usage-spellnames">spellwords to names translator</link> and more.
</para>

</section>

<!-- ================================================ -->

<section id="isggrtfforme"><title>Is GgrTF for Me?</title>
<para>
It is impossible to tell, really. You may have just to give it
a try.
</para>

<para>
When I started working on GgrTF,
I was just "scratching an itch", and that itch still continues,
though few others have joined my efforts on scratching.
During the two years I have been developing GgrTF, most of that
time I've been scratching my own back, doing stuff mostly for myself.
Thus, if you like the design decisions and features I like,
play the same guilds as I (though some guilds which I haven't
ever touched are supported through efforts of other developers)
it is likely that you will like GgrTF.
</para>

<para>
It must be admitted that GgrTF is somewhat programmer-oriented,
at least in the sense that if you want something that is not already
there, it probably is your own responsibility to create it.
</para>

<para>
Also GgrTF is not all that well documented (although that is one
thing we are trying remedy) and <emphasis>requires basic knowledge of
how &tfurl;</emphasis> and its macro language works. As such GgrTF
is not a ready out-of-the-box experience for some users and never
will be. <emphasis>However, if you are able to crank it up and working,
and are content with what is readily offered, then it might be something
for you.</emphasis>
</para>

<para>
Some other scripts may offer more in the automation
and pre-made hook department, GgrTF's aims are different, however.
For example, one reason for this user's manual was created, was to
help you to understand basics of GgrTF and give a head start
in customizing it to suit your personal preferences.
</para>

<para>
All in all, GgrTF <emphasis>might</emphasis> be something for you,
especially if you like things the way I like them. But on the other
hand GgrTF might not be for you, and there are several alternatives
out there for those who do not find it satisfactory. Below I have
tried to list some pros and cons of using GgrTF.
</para>

<itemizedlist>
 <listitem><para>Pros:</para>
  <itemizedlist>
   <listitem><para>Good general quality of code. As somebody put it,
"you do not instantly get a headache from just looking at the code."</para></listitem>
   <listitem><para>Modularity, easily extendable for most part.</para></listitem>
   <listitem><para>Updated regularly, most bugs get fixed in upstream.</para></listitem>
   <listitem><para>User-level documentation exists.</para></listitem>
  </itemizedlist>
 </listitem>

 <listitem><para>Cons:</para>
  <itemizedlist>
   <listitem><para>Only small number of &batmudurl;'s guilds are specifically supported.</para></listitem>
   <listitem><para>Requires more knowledge about programming some other solutions.</para></listitem>
   <listitem><para>Due to nature of the developer's reincs, is biased
towards caster-type functionality than tanks. Thus the support for tank
guilds is not very good, although there is some.</para></listitem>
  </itemizedlist>
 </listitem>

</itemizedlist>
</section>

<!-- ================================================ -->

<section id="ggrtfhistory"><title>History of GgrTF</title>
<subtitle>As told by Ggr</subtitle>

<para>
About two years ago, in march of 2004, I made one of the worst
mistakes in my life - I created a character in &batmudurl;.
I never thought of myself to be much of a gamer, I've always
been more interested in more technical things, programming
and a little bit of hardware (not analog, though), so
mostly my gaming experience consisted of some c64 games,
Nethack and some other CRPGs. I guess the RPG statmania
was one reason that got me hooked in the first place, plus
the multiplayer interaction and social aspects.
</para>

<para>
Started off playing with plain telnet for the first month
or so, then installed &tfurl;, because it seemed to be
the most popular of the clients available for UNIXish platforms.
First I didn't use any triggers at all, TF was just there
to work as better terminal and separating the input from
output .. and the game was confusing enough to start with,
triggers would have just complicated things. At least I felt so
back then.
</para>

<para>
At some point, however, my playing style advanced and need
for automating some things became apparent. I googled for
some available scripts, but most of the available ones
were either badly designed, full of very apparent mistakes and
bugs, or not maintained anymore.
</para>

<para>
Fancying myself as a programmer of some sort, off I went,
developing my own piece of turf, starting out very simple,
expanding and improving when needed. That continued for about
a year or a bit over, then the situation got out of hand -
I started "releasing" GgrTF periodically on my &batmudurl; related
web-page.
</para>

<para>
The first ever released version of GgrTF was v0.3.0, which
was still pretty simple. It just supported channeller/mage
stuff and had a broken prots management system. The 0.3.x-series
continued up to 0.3.13 or so, after which some major changes
were made and 0.4.0 was released.
</para>

<para>
At some point of 0.4.x-series development, people started
noticing GgrTF. I believe some even started using it, or
at least "stole" parts of it. v0.4.x was somewhat short-lived,
soon additional major restructuring was made into the prot
management system and it was time for 0.5.0, which is
the current tree as of writing, though this manual is
being written for v0.6.0 release.
</para>

</section>

<!-- ================================================ -->

<section id="license"><title>GgrTF License</title>
<para>
GgrTF is copyrighted (except where mentioned otherwise)
by Matti Hämäläinen (aka Ggr Pupunen) and
distributed under the GNU General Public License version 2.
</para>

<para>
Complete text of the GNU GPL v2 is included with the code in a file
called COPYING.txt, and is also available
<ulink url="http://www.gnu.org/licenses/gpl.html">here</ulink>.
</para>
</section>

</chapter>

<!-- *************************************************************** -->

<chapter id="installation"><title>Installation</title>
<para>
This chapter assumes that you have already succesfully installed &tfurl;
in your system and you know how to use it (basic commands, loading of
macros, etc.) It is also assumed that you know how to use your operating
system of choice, be it some flavour of UNIX or Windows, although some
parts of the instructions are given in step-by-step manner.
</para>

<note>
<para>
Throughout this manual, when GgrTF files are referenced in configuration
examples etc., I have used <emphasis>tf/</emphasis> -directory as path
where the script files are located. You may need to substitute it
with whatever you have installed your copy of GgrTF in.
</para>
</note>

<!-- ================================================ -->

<section id="inst-getting"><title>Getting GgrTF</title>

<para>
There are basically two ways how to get GgrTF, release packages and
the Subversion-repository. Releases are considered as stable snapshots,
which should be relatively bug-free, but releases are done somewhat
infrequently and at least in this phase we don't backport bugfixes to
release versions.
</para>

<para>
Another way to get GgrTF is to go to the very source, the
development source repository. This repository contains the latest
bleeding edge features, but is also a fast moving target. Changes
are directly "pushed" (committed) by developers almost in real time,
sometimes what you download may be severely broken.
Also the documentation will not be updated for every little change,
so you may have to figure out and work around possible backward
incompatibilities yourself.
</para>

<para>
New features and new bugfixes may sometimes be worth taking the risk
of using the Subversion-repository. On the other hand, it is all up
to what you want and whether you can manage to handle the possibly
arising problems.
</para>


<section id="inst-releases"><title>Releases</title>
<para>
Stable releases are available from downloads-section of 
<ulink url="http://ccr.tnsp.org/ggrtf/">GgrTF's homepage</ulink>,
either as tar.gz or zip-packages. Both files also have equivalent
PGP/&gnupgurl; signature files (*.asc), which can be used to cryptographically
verify the authenticity of content, in case you want to be sure that you
are getting unmodified files directly from the author.
</para>

<para>
To verify the signatures with &gnupgurl;, you can use following commands:
</para>

<itemizedlist>
 <listitem><para>Retrieve Matti Hämäläinen's public key from a keyserver:</para>
<screen>
gpg --keyserver wwwkeys.pgp.net --recv-keys 0x1374C112
</screen>
</listitem>
 <listitem><para>Verify the package signature (assuming you have downloaded both the file and signature):</para>
<screen>
gpg --verify ggrtf-0.6.0.tar.gz
</screen>
<para>(Obviously you have to substitute the filename with the correct one.)</para></listitem>
</itemizedlist>

<para>
Please refer to GnuPG or PGP documentation for more information about
their usage. A great introduction to PKI, cryptography and public key
signing, the <ulink url="http://www.gnupg.org/gph/en/manual.html">
GNU Privacy Handbook</ulink> is available from GnuPG project.
(Versions in other languages and formats, including PDF, are available
from <ulink url="http://www.gnupg.org/(en)/documentation/guides.html">
http://www.gnupg.org/(en)/documentation/guides.html</ulink>.)
</para>
</section>


<section id="inst-subversion"><title>Subversion-repository</title>
<para>
We utilize &svnurl; (SVN) for GgrTF's version management. &svnurl;
is a freely available Open Source version control system, for which
there are clients available for most common platforms, including
Windows, Linux and other flavours of UNIX.
</para>

<para>
GgrTF's Subversion repository is graciously hosted by &jeskko;
at &pupuneturl;, and is available from following location:
</para>

<itemizedlist>
 <listitem>
  <para>Trunk-repository, all the latest stuff goes here:</para>
  <para><ulink url="http://svn.pupunen.net/public/ggrtf/trunk/">http://svn.pupunen.net/public/ggrtf/trunk/</ulink></para>
 </listitem>
 <listitem>
  <para>You can browse the repository more easily via &pupuneturl;'s ViewCVS interface:</para>
  <para><ulink url="http://svn.pupunen.net/viewcvs.py/ggrtf/trunk/">http://svn.pupunen.net/viewcvs.py/ggrtf/trunk/</ulink></para>
 </listitem>
</itemizedlist>

<section id="intro-checking-out"><title>Checking out</title>
<para>
You can download ("checkout") the GgrTF repository with command line
Subversion client with following command:
</para>

<screen>
svn co http://svn.pupunen.net/public/ggrtf/trunk/ tf
</screen>

<para>
In which <emphasis>"co"</emphasis> stands for "checkout", after which
comes URL of the repository and finally path to directory ("tf")
which the files will be checked out into.
</para>

<para>
You will most probably want to download the repository to some
specific place, personally I prefer to use $HOME/tf/ (aka "tf/"
subdirectory under user's homedir) under UNIX.
<!--
If you are using TF for Windows, it is probably wisest to place
GgrTF's files under ... ????
-->
</para>
</section>

<section id="intro-updating"><title>Keeping up to date</title>
<para>
After you have checked out your own copy of GgrTF's code repository,
you usually wish to periodically update it. This is done easily with 
Subversion's "update" command. First go to the repository directory
and then issue "svn update" or the shorthand "svn up", as follows:
</para>

<screen>
cd tf
svn up
</screen>

<para>
If you have made changes to the files, Subversion tries to merge them
with changes that have occured in the main repository. Sometimes the
changes may be interfering with each other and this causes a merging
error. You must fix these problems by hand, please refer to Subversion
documentation for more information and tips.
</para>
</section>

</section>

</section>

<!-- ================================================ -->

<section id="inst-config"><title>Configuration</title>
<para>
After getting GgrTF and installing/copying the files to appropriate
directory folder, you need to setup your configuration for &tfurl;
and possibly change some of your settings in &batmudurl;.
</para>

<para>
If you are upgrading GgrTF from a previous version, it is probable
that you do not have to change your configuration. But in case of
odd problems you may wish to skim through this section,
the ChangeLog and module-specific sections of this manual in
case of any significant, backwards incompatible changes.
</para>


<section id="inst-config-ggrtf"><title>TF configuration</title>
<para>
First, we have to set up TF's configuration. Location of the file
containing the startup script for TF depends on your operating
system environment.
</para>

<itemizedlist>
 <listitem><para>
  UNIX- and compatibles and CygWin-based Win32 ports:
  <emphasis>~/.tfrc</emphasis>
  (File named ".tfrc" in your user's home directory)
 </para></listitem>

<!--
 <listitem><para>DruWare Win32 port of TF:
<emphasis></emphasis>
</para></listitem>
-->
</itemizedlist>

<para>

</para>

<!--
- intro
- layout of recommended configuration
- discussion about modules
- simple example configuration
- bindings or not?
- state saving
-->
</section>


<section id="inst-config-batmud"><title>BatMUD settings</title>
<para>
Next, log on in BatMUD and change following settings:
</para>

<itemizedlist>
 <listitem><para>Line 'cutter' setting:</para>
<screen>cutter 9999</screen>
<para>Theoretically, '<emphasis>cutter off</emphasis>'
should be better, but in practice I have noticed that
in certain things it simply does not work as expected.</para>
</listitem>

 <listitem><para>Short score format for regular BatMUD:</para>
<screen>sc set H:{colorhp}/&lt;maxhp&gt; [{diffhp}] S:{colorsp}/&lt;maxsp&gt; [{diffsp}] E:{colorep}/&lt;maxep&gt; [{diffep}] $:&lt;cash&gt; [{diffcash}] exp:&lt;exp&gt; [{diffexp}]</screen>
</listitem>

 <listitem><para>Short score format for HardCore BatMUD (HCBat):</para>
<screen>sc set H:{colorhp}/&lt;maxhp&gt; S:{colorsp}/&lt;maxsp&gt; E:{colorep}/&lt;maxep&gt; $:&lt;cash&gt; exp:&lt;exp&gt;</screen>
</listitem>

 <listitem><para>Prompt:</para>
<screen>prompt H:&lt;hp&gt;/&lt;maxhp&gt; S:&lt;sp&gt;/&lt;maxsp&gt; E:&lt;ep&gt;/&lt;maxep&gt; &gt;</screen>
</listitem>

 <listitem><para>Listen to battle round flags:</para>
<screen>battle rounds</screen>
<para>This setting is a toggle, make sure that you set it ON
("Listening to round flags.") instead of off!
</para>
</listitem>

 <listitem><para>Battle listen-level:</para>
<screen>battle listen all 2</screen>
<para>Listen level should be 2 or 3, if you are using hitstats.
Otherwise it can be 1 or 0, if you prefer silence.
</para>
</listitem>
</itemizedlist>

<para>
In case you do NOT want to change your settings to the way GgrTF needs
them to be, your only option is to change the regular expression patterns
in GgrTF's code to match your preferences (and possibly redo the changes
when/if you upgrade GgrTF.)
</para>
</section>

</section>

</chapter>

<!-- *************************************************************** -->

<chapter id="usage-intro"><title>Usage</title>
<para>
This chapter describes the structure of GgrTF, what the 
different modules included in GgrTF are and what functionality
they provide. There are basically three flavours of modules: generic
modules that are either required or optional and provide
functionality unrelated to specific guilds; then there are
guild-related modules, containing guild-specialties.
</para>

<para>
Each module section has short introduction about what is provided
and section with macro commands and variables available. Some modules
also have additional information about usage and configuration
with examples.
</para>

<para>
Following block-diagram represents the structure of GgrTF and
how different components approximately relate to each other:
</para>

<screenshot>
 <mediaobject>
  <imageobject><imagedata fileref="blockdiagram.eps" format="EPS" /></imageobject>
  <imageobject><imagedata fileref="blockdiagram.png" format="PNG" /></imageobject>
  <textobject>
   <phrase>GgrTF's internal structure</phrase>
  </textobject>
  <caption>
   <para>Internal structure and relations of GgrTF components represented as
block-diagram.</para>
  </caption>
 </mediaobject>
</screenshot>

<!-- ================================================ -->

<section id="usage-general"><title>GgrTF core (ggrtf.tf)</title>
<para>
This is the main module and core of GgrTF. It contains helper
macro functions used by all the other modules and is thus
always required to be loaded.
It also provides much of the basic functionality, such as:
</para>

<itemizedlist>
 <listitem><para>
<link linkend="usage-general-statusline">Statusline</link>.
Provides nice, realtimeish view of your character's current
condition, applied prots and other such information.
</para></listitem>

 <listitem><para>
<link linkend="usage-general-prots">Prot management</link>.
Keeps note of what prots have been cast at you, and provides this
information in various ways.
</para></listitem>

 <listitem><para>Battle round handling. Enables commands to be
executed each battle round and autopss functionality.
</para></listitem>

 <listitem><para>Functions for binding command strings to macros,
or to cast spells and use skills, with or without reporting to
party channel. See <link linkend="usage-general-binds">bindings</link>
section for more information.
</para></listitem>

 <listitem><para>Support for <link linkend="usage-general-saves">
state-saving</link>. Most GgrTF settings can be saved to files
and reloaded later (for example at startup) with /gsave and /gload
commands.
</para></listitem>

 <listitem><para>Prompt gagging. Optional skill/spell viewing in
 prompt, which shows the currently ongoing skill or spell in your
 prompt.
</para></listitem>

 <listitem><para>Spell round reporting. Enables you to optionally
 spam your fellow players with information how many rounds are left
 until your spell goes off.
 </para></listitem>

 <listitem><para>Automatic "ripaction", which is performed when
 your opponent (monster) dies. This way you can automate small
 inconveniencies like looting and digging of graves.
 </para></listitem>

 <listitem><para>Keyboard movement handling and mapping. Bind your
numpad keys to move around, either by walking, walking with peering
in adjacent rooms (useful for merchants) or guiding your ship.
Additional modes may be provided by other optional modules.
</para></listitem>

 <listitem><para>Enemy shape string highlighting and reformatting.
You can make GgrTF mangle 'scan' command's output into
more readable and convenient form.
</para></listitem>

 <listitem><para>Keep and display statistics about skills, spells
 and whatnots. ("/stats" command)
</para></listitem>
</itemizedlist>


<section id="usage-general-commands">
&sectmacros;
</para>
<para>
Each of these commands will print current setting/value and
usage information if executed without arguments (or in some cases,
with incorrect arguments).
</para>

<table><title>Macro commands</title>
 <tgroup cols="2" align="left">
  <thead>
   <row>
    <entry>Command</entry>
    <entry>Description</entry>
   </row>
  </thead>
  <tbody>
   <row>
    <entry>/opts</entry>
    <entry>Lists all the run-time changeable settings of GgrTF,
with short descriptions and current values.
</entry>
   </row>
   <row>
    <entry>/stats</entry>
    <entry>Display miscellaneous statistics about skills, spells, etc.</entry>
   </row>
   <row>
    <entry>/move &lt;type&gt;</entry>
    <entry>Change the meaning of
     <link linkend="usage-general-prmove">keyboard movement hooks</link>.
    </entry>
   </row>
   <row>
    <entry>/ripaction &lt;action&gt;</entry>
    <entry>
Set the action performed at opponent RIP. Possible additional settings
may be provided by other loaded modules. Functions provided by base
GgrTF are:
<emphasis>off</emphasis> (no special action performed),
<emphasis>dig</emphasis> (dig grave for corpse),
<emphasis>eat</emphasis> (get and eat corpse),
<emphasis>get</emphasis> (get corpse) and
<emphasis>cmd</emphasis> (execute mud command(s) specified with
/ripcommand setting, see /ripcommand)
    </entry>
   </row>
   <row>
    <entry>/ripcommand &lt;commands&gt;</entry>
    <entry>
Sets the MUD command(s) to be executed if /ripaction is
set to "cmd". This string is sent to the MUD at opponent R.I.P,
if /ripaction is "cmd".
</entry>
   </row>
   <row>
    <entry>/round &lt;commands&gt;</entry>
    <entry>
Sets the BatMUD command(s) to be executed on each battle round.
The string of commands is sent to the MUD when battle round flag
is received.
</entry>
   </row>
   <row>
    <entry>/locaction &lt;action&gt;</entry>
    <entry>
Sets action taken after a Lord of Chaos performs "blood corpse".
This is useful for automating corpse handling, if you are a LoC
yourself, or are partying with one.
</entry>
   </row>
   <row>
    <entry>/lichaction &lt;action&gt;</entry>
    <entry>
Sets action taken after a Lich performs "soul sucking".
</entry>
   </row>
   <row>
    <entry>/prots</entry>
    <entry>
Show any currently active prots on you. The output is only echoed
locally, use BatMUD 'tweak me' emote to list prots to party
report-channel.
</entry>
   </row>
   <row>
    <entry>/cprots</entry>
    <entry>
This command clears all prots on you. It is meant for those cases
where GgrTF is either bugging and does not notice a prot dropping,
or any other reason when you need to remove all prots at your
discretion.
</entry>
   </row>
   <row>
    <entry>/shape</entry>
    <entry>
Reports the last catched shape of a opponent (monster) in battle.
This does not work too well if you were fighting more than one opponents.
</entry>
   </row>
   <row>
    <entry>/gver</entry>
    <entry>
Prints (or returns, if called as function) a short version string of GgrTF.
</entry>
   </row>
   <row>
    <entry>/gversion</entry>
    <entry>
Prints (or returns, if called as function) a long version string of
GgrTF with copyright- and TinyFugue version information.
</entry>
   </row>
   <row>
    <entry>/autopss</entry>
    <entry>
Toggle autopss-functionality on/off. If enabled, /pss macro is executed
on each battle round flag. By default, /pss is 'party short status', but
some modules (like <link linkend="usage-pssmangle">PSS-mangler</link>) override this to
provide additional functionality.
</entry>
   </row>
   <row>
    <entry>/binds</entry>
    <entry>
List all currently defined GgrTF command bindings. Refer to
<link linkend="usage-general-binds">bindings</link> section for
more information and example output.
</entry>
   </row>
   <row>
    <entry>/gsave</entry>
    <entry>
Save all GgrTF settings. Refer to <link linkend="usage-general-saves">
state saving</link> section for more information.
</entry>
   </row>
   <row>
    <entry>/gload</entry>
    <entry>
Load GgrTF settings. Refer to <link linkend="usage-general-saves">
state saving</link> section for more information.
</entry>
   </row>
   <row>
    <entry>/greset</entry>
    <entry>
Reset all skill/spell counters and statistics. Notice that issuing
this command also requires executing of "/gsave" if you want to save
the zeroed statistics, otherwise the old saved statistics will be
loaded on next /gload.
</entry>
   </row>
<!--
   <row>
    <entry></entry>
    <entry></entry>
   </row>
-->
  </tbody>
 </tgroup>
</table>
</section>

</section>

<!-- ================================================ -->

<section id="usage-general-statusline"><title>Statusline</title>
<para>
Probably one of the first things that you notice in GgrTF
is the statusline (or "statusbar" as some prefer). In GgrTF the
&tfurl; statusline is used to display information that we've
considered to be important enough for nearly real-time view.
</para>

<para>
The basic one-row statusline of GgrTF is meant for TF4 compatibility,
though it works with TF5 too. <link linkend="usage-tf5">TF5 support
module</link> provides another version, enhanced to take advantage
of &tfurl; 5's new features.
</para>

<para>
Statusline is updated synchronously at ticks, skill- and spell
castings and certain other events.
</para>

<screenshot>
 <mediaobject>
  <imageobject><imagedata fileref="statusbar.gif" format="GIF" /></imageobject>
  <imageobject><imagedata fileref="statusbar.eps" format="EPS" /></imageobject>
  <textobject>
   <phrase>GgrTF statusline</phrase>
  </textobject>
  <caption>
   <para>Example of typical basic GgrTF statusline in TF4.</para>
  </caption>
 </mediaobject>
</screenshot>

<orderedlist>
 <listitem><para>Current hit points / hit points maximum.</para></listitem>
 <listitem><para>Current spell points / spell points maximum.</para></listitem>
 <listitem><para>Current endurance points / endurance points maximum.</para></listitem>
 <listitem><para>[2 light green characters] Last moved direction.</para></listitem>
 <listitem><para>["C"] Ceremony status. (Dark blue = inactive/no ceremony; White = ceremony active)</para></listitem>
 <listitem><para>["S"] Spell status. (Dark blue = no spell going; White = spellcasting)</para></listitem>
 <listitem><para>["K"] Skill status. (Dark blue = no skill going; White = using a skill)</para></listitem>
 <listitem><para>["c"] Camping status. (Light green = ready to camp; Red = camping active/skill ongoing; Yellow = camping not available, or recovering from previous camping.)</para></listitem>
 <listitem><para><link linkend="usage-general-prots">Currently active prots</link> in short format.</para></listitem>
</orderedlist>

<para>
First three elements of the statusbar describe your character's
current hit-, spell- and endurance-points. These values are
color-coded for better visual clarity. One element shows
current value and maximum value, as shown in screenshot below:
</para>

<screenshot>
 <mediaobject>
  <imageobject><imagedata fileref="statusbar_ep.gif" format="GIF" /></imageobject>
  <imageobject><imagedata fileref="statusbar_ep.eps" format="EPS" /></imageobject>
  <textobject>
   <phrase>Endurance Points-part of statusline</phrase>
  </textobject>
  <caption>
   <para>Example of how endurance points are shown. "E:" denotes Endurance,
   "134" is the current value (colorcoded) and "246" is the maximum
   endurance your character has.
   </para>
  </caption>
 </mediaobject>
</screenshot>


</section>

<!-- ================================================ -->

<section id="usage-general-saves"><title>State-saving</title>
<para>
State-saving is an awfully awkward name for GgrTF's functionality for
saving your settings and other interesting data for later
retrieval. Settings get saved and thus can be loaded,
but this functionality is not automatic by default, you have to set it
up so if you wish - GgrTF only provides you the functions for loading
and saving, making it to happen automagically is up to you.
(How to do this is discussed further below.)
</para>

<section id="usage-general-saves-whatis"><title>What is saved?</title>
<para>
<emphasis>Almost</emphasis> all settings (hidden or visible)
get saved, but there are certain global settings that you
have to set yourself in your TF configuration. These
settings are discussed in sub-section below.
</para>

<para>
It should also be noted, that there are actually <emphasis>two
different types of data (or variables) that is saved into two
different files</emphasis>. In GgrTF, these two types of data
are called <emphasis>pre- and post-init settings</emphasis>, and the
two savefiles are named accordingly. Pre-init settings are
variables that need to be defined before the main modules
of GgrTF are loaded in TF's startup configuration (certain
functionality depends on this). Post-init variables can
(and sometimes <emphasis>must</emphasis>) be set after loading
of all modules.
</para>
</section>

<section id="usage-general-saves-special"><title>Special, non-saved variables</title>
<para>
There are currently three special GgrTF variables, which you have to
set yourself in your TF's startup configuration (".tfrc"-file).
These variables <emphasis>MUST</emphasis> be set before loading
of ANY GgrTF modules, otherwise things start breaking and the
state-saving system does not work correctly.
</para>

<table><title>Variables</title>
 <tgroup cols="3" align="left">
  <thead>
   <row>
    <entry>Variable</entry>
    <entry>Description</entry>
    <entry>Example</entry>
   </row>
  </thead>
  <tbody>
   <row>
    <entry>set_plrname</entry>
    <entry>
    Your character's name, written in correct case.
    </entry>
    <entry>/set set_plrname=Ggr</entry>
   </row>

   <row>
    <entry>set_datapath</entry>
    <entry>Path to the directory where you want your savefiles to reside. If
left empty, current working directory is used (the directory you started TF
from.)</entry>
    <entry>/set set_datapath=</entry>
   </row>

   <row>
    <entry>set_saveprefix</entry>
    <entry>
     This string is used as prefix of the two savefiles, so the actual
     savefiles are "<emphasis>&lt;prefix&gt;pre.tf</emphasis>" and
     "<emphasis>&lt;prefix&gt;post.tf</emphasis>". This is useful,
     if you play regular BatMUD and HCBat, so you can use different values
     for either.
    </entry>
    <entry>/set set_saveprefix=bat-</entry>
   </row>

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

</section>


<section id="usage-general-saves-setup"><title>How to setup TF for state-saving</title>
<para>
Getting GgrTF's state-saving to work requires some changes to your
TF configuration, namely the ".tfrc"-file. First of all, you need to
set the special variables, so that the loading and initialization
work correctly. Secondly, a special module ggrtf-pre.tf must be
set to load before any other GgrTF components are to be loaded
(this special module loads the pre-init settings). Third, after
all GgrTF modules have been loaded, /gload macro must
be issued so that previously saved settings will be restored.
</para>

<para>
A simplified example configuration layout is presented below, please
refer to <link linkend="inst-config-ggrtf">setup</link>-section of this
manual for a more detailed example. Pay close attention to the order
how things are done, it is very important!
</para>

<screen>
;; Set special variables before loading scripts

;; Player character name (notice the case, "Ggr" instead of "ggr" or "GGR")
/set set_plrname=Ggr

;; Path of directory where savefiles will be stored, empty is CWD
/eval /set set_datapath=%{HOME}/tf/
/def -i gloadmod = /eval /load %{HOME}/tf/%{*}

;; Prefix string for savefile names
/set set_saveprefix=bat-


;; Load the special pre-init module
/gloadmod ggrtf-pre.tf

;; Load GgrTF core
/gloadmod ggrtf.tf

;; Load other additional modules
/gloadmod ggrtf-misc.tf
/gloadmod ggrtf-magical.tf
/gloadmod ggrtf-rais.tf
/gloadmod ggrtf-tarma.tf
/gloadmod ggrtf-druid.tf
/gloadmod ggrtf-pssmangle.tf
/gloadmod ggrtf-pplacer.tf
/gloadmod ggrtf-spellnames.tf
/gloadmod ggrtf-tf5.tf

;; Perhaps load some key bindings
/gloadmod kbd-xterm.tf

;; Restore previously saved settings
/gload
</screen>

<para>
When you have edited your TF configuration, you need to (re-)start
it, change settings the way you want them to be and finally issue
"/gsave" command to get settings saved. <emphasis>After saving,
you may also want to examine the pre-init -savefile, because it
contains certain settings that cannot be changed run-time
</emphasis>. So, here are the steps in short again:
</para>

<orderedlist>
 <listitem><para>
  <emphasis>Edit TF configuration</emphasis>:
  Add required settings, "ggrtf-pre.tf"-module and /gload directive.
 </para></listitem>
 <listitem><para>
  <emphasis>Re-start TF</emphasis>:
  In order to save initial settings, you need to (re-)start
  TF, so that the save-state system is enabled.
 </para></listitem>
 <listitem><para>
  <emphasis>Change settings</emphasis>:
  Change GgrTF settings (listed via /opts etc.) to accommodate
  your desires.
 </para></listitem>
 <listitem><para>
  <emphasis>Save initial settings</emphasis>:
  Issue "/gsave" to get settings saved.
 </para></listitem>
 <listitem><para>
  <emphasis>Optionally edit pre-init settings</emphasis>:
  Certain settings are saved into the pre-init savefile (actual
  filename is dependant on what you set "set_saveprefix" to).
  GgrTF does not offer any special interface to change these settings,
  you have to edit this file by hand, if you wish to change the defaults.
 </para></listitem>
</orderedlist>

</section>

<section><title>How to make state-saving automatic</title>
<para>
In previous example, I only described how settings get restored
(as TF loads and initializes GgrTF), but how to get settings
saved automatically too?
</para>

<para>
The answer lies in &tfurl;'s event hooks. It is possible to
define a hook, which is executed when TF disconnects from a world.
By setting this hook to perform "/gsave", we can automatize the
process of saving settings. Add following line to your TF configuration:
</para>

<screen>
/def -hDISCONNECT mydisconnect = /gsave
</screen>

<para>
There is one gotcha: if you don't want to keep saving the statistical
values, but only the settings, you may want to add a "/greset" in the soup:
</para>

<screen>
/def -hDISCONNECT mydisconnect = /greset%;/gsave
</screen>

</section>


<section>
&sectmacros;
</para>

<table><title>Macro commands</title>
 <tgroup cols="2" align="left">
  <thead>
   <row>
    <entry>Command</entry>
    <entry>Description</entry>
   </row>
  </thead>
  <tbody>
   <row>
    <entry>/gsave</entry>
    <entry>
Save all GgrTF settings and other certain variables.
</entry>
   </row>
   <row>
    <entry>/gload</entry>
    <entry>
Load GgrTF settings.
</entry>
   </row>
   <row>
    <entry>/greset</entry>
    <entry>
Reset all skill/spell counters and statistics. Notice that issuing
this command also requires executing of "/gsave" if you want to save
the zeroed statistics, otherwise the currently saved statistics will be
loaded on next /gload.
</entry>
   </row>
  </tbody>
 </tgroup>
</table>
</section>

</section>

<!-- ================================================ -->

<section id="usage-general-binds"><title>Command bindings</title>
<para>
GgrTF's core provides few macros for defining "bindings", which
are a way to create commands that look like normal MUD commands
but are actually intercepted by &tfurl; and executed appropriately.
These bindings can be used to easily define shorthands for casting
spells, using skills, executing macros, etc. GgrTF bindings offer
an easy way to define skill/spell commands with automatic party
reporting (or without it).
</para>

<para>
In GgrTF, there are <emphasis>optional pre-defined bindings</emphasis>,
which can be enabled at your consideration. These pre-defined bindings
are defined in the relevant modules, and enabled at load-time
with a special setting ("opt_bindings"), please refer to
<link linkend="inst-config">setup</link>- and <link
linkend="usage-general-saves">state saving</link>- sections
for more information.
</para>

<para>
Now, you might be asking <emphasis>why would anyone need bindings</emphasis>?
Indeed, you can already use BatMUD's command aliases for such things, but
the number of command aliases in BatMUD is limited and if you run out of
space, you have to remove some less used ones. Sometimes you have to
redefine lots just because you are reincarnating... and you can not execute
macros with command aliases.
</para>

<para>
There are many benefits to using bindings, but they do have some
drawbacks:
</para>

<itemizedlist>
 <listitem><para>
  <emphasis>Limitations of TF's parsing</emphasis>:
  Because of the nature how bindings are defined and parsed,
  you can only use one binded command per line.
  For example, let's assume "aoa" is binding to cast Armour of Aether
  and "clair" is a binding to use clairvoyance. Thus, someone
  might want to command:
  </para>
  <screen>
  aoa ggr%;clair
  </screen>
  <para>
  Unfortunately, this does not work as might be expected. Because TF does
  not evaluate binding as an expression, the "ggr%;clair"-part
  is used as a literal argument to "aoa" binding. In effect the
  command would try to cast Armour of Aether at player "ggr%;clair".
 </para></listitem>

 <listitem><para>
  <emphasis>BatMUD commands and GgrTF bindings cannot be mixed</emphasis>:
  Because the bindings are actually intercepted by TF before the line gets
  passed to BatMUD's parser, you can't combine multiple bindings or BatMUD
  commands on the line. For example, assuming "aoa" is again a binding
  and "hop" is an emote:
  </para>
  <screen>
  hop jeskko;aoa ggr
  </screen>
  <para>
  One might easily assume, that the result would be to first hop
  around player or thing named Jeskko, and then cast Armour of Aether
  at Ggr. Unfortunately the latter would just produce an error, as
  it would be instead passed to BatMUD's interpreter and not handled
  as a binding by TF!
 </para></listitem>

 <listitem><para>
  <emphasis>Limitations of GgrTF's binding system</emphasis>:
  There are certain limitations what kind of bindings you can define
  with the current functionality provided by GgrTF. Bindings that
  require complex parameters (more than one optional argument),
  are not possible - you are better off using BatMUD's command
  aliases for those.
 </para></listitem>
</itemizedlist>


<section><title>Defining bindings</title>
<para>
Now we know the limitations of this system - let's see how to define some basic
command bindings!
</para>

<screen>
/prdefgbind -s"cere"    -c"/ceremony" -n
/prdefcbind -s"nf"      -c"Neutralize Field" -n
/prdefsbind -s"fire"    -c"Fire Building" -n
</screen>

<para>
Above we have have listed all three (3) classes of binding defination
macros supported by GgrTF. First defines a generic command binding
to execute "/ceremony" macro when user commands "cere".
Second binding defines a spell casting command to cast "Neutralize Field"
when user commands "nf". And the third binding defines a skill
usage command to use "Fire Building". So basically we have
three types of bindings:
</para>

<itemizedlist>
 <listitem><para>
  <emphasis>/prdefgbind</emphasis>:
  Defines a generic binding, in which the action ("-c" parameter)
  can be almost anything, like a TF macro, or BatMUD command.
 </para></listitem>

 <listitem><para>
  <emphasis>/prdefcbind</emphasis>:
  Defines a casting binding, the action is the name of the spell
  to be casted.
 </para></listitem>

 <listitem><para>
  <emphasis>/prdefsbind</emphasis>:
  Defines a skill usage binding, action argument being name of the
  skill to be executed.
 </para></listitem>
</itemizedlist>

<para>
Each of these defination macros require at least two arguments:
the name for the binding command ("-s" option) and the action ("-c" option).
There are other optional arguments, which affect aspects of the
command binding to be defined. The argument options and their
meanings are listed below:
</para>

<table><title>Arguments common to all binding defination macros</title>
 <tgroup cols="2" align="left">
  <thead>
   <row>
    <entry>Option</entry>
    <entry>Description</entry>
   </row>
  </thead>
  <tbody>
   <row>
    <entry>-s"name"</entry>
    <entry>Specifies the name of the command binding.
    This is basically the string you type to use the command,
    after which come the optional arguments.
    </entry>
   </row>
   <row>
    <entry>-n</entry>
    <entry>
    Tells GgrTF that the binding does NOT accept arguments.
    Anything following the command binding invocation is ignored.
    This also affects the possible reporting output of the binding.
    </entry>
   </row>
  </tbody>
 </tgroup>
</table>

<table><title>Arguments specific to generic bindings (/prdefgbind)</title>
 <tgroup cols="2" align="left">
  <thead>
   <row>
    <entry>Option</entry>
    <entry>Description</entry>
   </row>
  </thead>
  <tbody>
   <row>
    <entry>-c"action"</entry>
    <entry>
    Specifies the action, aka what the binding <emphasis>does</emphasis>.
    For generic bindings, the action is a literal, so it can be a
    TF macro or BatMUD command. 
    </entry>
   </row>
  </tbody>
 </tgroup>
</table>

<table><title>Arguments specific to spell casting and skill usage bindings (/prdefcbind and /prdefsbind)</title>
 <tgroup cols="2" align="left">
  <thead>
   <row>
    <entry>Option</entry>
    <entry>Description</entry>
   </row>
  </thead>
  <tbody>
   <row>
    <entry>-c"action"</entry>
    <entry>
    Specifies name of the spell to be cast or skill to be used.
    </entry>
   </row>
   <row>
    <entry>-d"message"</entry>
    <entry>
    This option overrides the default message string used for reporting
    (see also option "-q" below).
    </entry>
   </row>
   <row>
    <entry>-q</entry>
    <entry>
    Makes the binding "quiet", suppresses any reporting. By default,
    spell casting binding reports the action on party report-channel,
    but specifying this option disables it.
    </entry>
   </row>
  </tbody>
 </tgroup>
</table>

<para>
More examples, now with short explanations:
</para>

<table><title>Binding defination examples</title>
 <tgroup cols="2" align="left">
  <thead>
   <row>
    <entry>Definition</entry>
    <entry>Description</entry>
   </row>
  </thead>
  <tbody>
   <row>
    <entry>/prdefgbind -s"repu"	-c"/showrep"		-n</entry>
    <entry>
     Generic binding, which executes /showrep macro and takes no arguments.
    </entry>
   </row>
   <row>
    <entry>/prdefsbind -s"er"	-c"Enrage"		-n</entry>
    <entry>
     Skill binding for barbarian "Enrage" skill. Also takes no
arguments.
    </entry>
   </row>
   <row>
    <entry>/prdefcbind -s"shelter"	-c"Shelter"		-n	-d"Sheltering ..."</entry>
    <entry>
     Spell casting binding, for casting conjurer spell "Shelter".
     Takes no arguments and uses specific reporting string (default
     would be "Shelter ...", but since it sounds bit stupid we want to
     use "Sheltering ..." instead.)
    </entry>
   </row>
   <row>
    <entry>/prdefcbind -s"dmp"	-c"Dispel Magical Protection"</entry>
    <entry>
     Another spell casting binding for a conjurer spell, which takes
     (and requires) a player's name as argument.
    </entry>
   </row>
   <row>
    <entry>/prdefcbind -s"sl"	-c"Star Light"		-q</entry>
    <entry>
     Yet another spell casting bind, this time for druid spell "Star Light".
     Since this is a blasting spell, it is not really useful to report
     that we are casting it, so we suppress any reporting. Argument is
     accepted.
    </entry>
   </row>
  </tbody>
 </tgroup>
</table>

<para>
As of now, you should be able to define bindings of your own. You can define
them in your .tfrc or make another file for them. Do remember, however, that
GgrTF provides lots of optionally loadable default bindings for you, if
you wish to take advantage of those.
</para>

</section>

</section>

<!-- ================================================ -->

<section id="usage-general-prmove"><title>Keyboard numpad movement hooks</title>
<para>
GgrTF provides a mechanism for routing keyboard numpad bindings so that
different functionality can be swapped in as needed. Core module offers
three modes: walk (normal walking around); peer (walking around with
automatic peering, useful for <link
linkend="usage-merchant">merchants</link>; ship (control ship's movement).
Certain other modules provide additional modes (see <link
linkend="usage-tarma">tarmalen module</link> for example.)
</para>

<section>
&sectmacros;
</para>

<table><title>Macro commands</title>
 <tgroup cols="2" align="left">
  <thead>
   <row>
    <entry>Command</entry>
    <entry>Description</entry>
   </row>
  </thead>
  <tbody>
   <row>
    <entry>/move [setting]</entry>
    <entry>Set the mode used for numpad bindings. Valid values are
     shown if command is given without arguments. Core GgrTF module
     provides following three modes: <emphasis>move</emphasis>,
     <emphasis>peer</emphasis> and <emphasis>ship</emphasis>
    </entry>
   </row>

   <row>
    <entry>/peer [regexp]</entry>
    <entry>
     Set the regular expression used for grepping the output of 'peer'
     command used in "/move peer" mode.
    </entry>
   </row>

   <row>
    <entry>/cruise</entry>
    <entry>Toggle ship cruising speed on/off (off = sail)</entry>
   </row>
  </tbody>
 </tgroup>
</table>
</section>
</section>

<!-- ================================================ -->

<section id="usage-general-prots"><title>Prot management</title>
<para>
One very important aspect of any script is the prot management.
GgrTF contains a flexible and easy to extend prot management system,
which supports basic, stacking and renewable prots. Special cases
are also supported, like unstun and conjurer typeprots.
</para>

<para>
For actually displaying the active prots information, GgrTF offers
various methods. The <link linkend="usage-general-statusline">
statusline</link> shows the currently active prots in short form
(without duration times). Macro command "/prots" can be invoked to
locally echo the active prots in long form.
Finally, a special BatMUD emote, 'tweak', can be used to trigger
reporting of active prots to party report-channel (the 'tweak' emote
was chosen for this purpose due to it being the de-facto standard
for prot reporting triggers.)
</para>

<para>
Classes of prots supported by GgrTF are roughly the following:
</para>

<itemizedlist>
 <listitem><para>Harmful effects/curses/handicaps</para></listitem>
 <listitem><para>Basic utility prots (infravision, water walking, floating, invisibility, etc.)</para></listitem>
 <listitem><para>Conjurer prots (minor- and major typeprots, stickyness)</para></listitem>
 <listitem><para>Evil priest (protection from good, paranoia)</para></listitem>
 <listitem><para>Tarmalen (unpain, blessing of tarmalen, lifelink, enhanced vitality)</para></listitem>
 <listitem><para>Nun (protection from evil, soul shield, heavenly protection, mana shield)</para></listitem>
 <listitem><para>Templar (shield of faith, blessing of faerwon)</para></listitem>
 <listitem><para>Psionicist (levitation, force shield)</para></listitem>
 <listitem><para>Druid (flex shield, earth power, earth skin, earth blood, vine mantle, regeneration)</para></listitem>
 <listitem><para>etc...</para></listitem>
</itemizedlist>

<para>
The string describing active prots consists of entries with
abbreviated name of the prot, current duration (from casting),
possible number of stackings and optional stickiness-indicator
for sticky conjuprots. The entries are separated with vertical
line character (sometimes called the pipe).
Some examples of prot entries are in table below.
</para>

<table><title>Prot entries</title>
 <tgroup cols="2" align="left">
  <thead>
   <row>
    <entry>Entry</entry>
    <entry>Description</entry>
   </row>
  </thead>
  <tbody>
   <row>
    <entry>Unst[1m9s]</entry>
    <entry>Unstun with duration of 1 minutes, 9 seconds.</entry>
   </row>
   <row>
    <entry>+FAbs[7m19s]</entry>
    <entry>Sticky Force Absorption.</entry>
   </row>
   <row>
    <entry>Infra(2)[0m2s]</entry>
    <entry>Infravision stacked at 2 levels.</entry>
   </row>
   <row>
    <entry>Unst&lt;2&gt;[7m19s]</entry>
    <entry>Unstun that has been weakened 2 times.</entry>
   </row>
   <row>
    <entry>-Forget[3m5s]</entry>
    <entry>'Forget' curse that has been active for 3 minutes and 5 seconds.</entry>
   </row>
  </tbody>
 </tgroup>
</table>

<para>
Simple example session featuring some protting action in GgrTF:
</para>

<screen>
<userinput>tweak jeskko</userinput>

You tweak Jeskko's nose mischievously.
Jeskko [report]: Unst[1h1m13s]

<userinput>unp jeskko</userinput>

Ggr [report]: Unpain -> jeskko
GgrTF:  ---- SPELL START ----  (393)
GgrTF: 'unpain' -> jeskko
Unpain: ##### [5]
You skillfully cast the spell with greater haste.
Unpain: ## [2]
Unpain: # [1]
GgrTF:  ---- SPELL DONE ----  in [3] rounds! [0m9s]
You utter the magic words (unpain)
You cast the spell successfully.
H:506/506 [] S:805/941 [-136] E:246/246 [] $:6499 [] exp:68202 []
Jeskko [report]: Unpain ON!

<userinput>tweak jeskko</userinput>

You tweak Jeskko's nose mischievously.
Jeskko [report]: Unst[1h4m25s] | Unp[2m35s]
</screen>


<section>
&sectmacros;
</para>

<table><title>Commands</title>
 <tgroup cols="2" align="left">
  <thead>
   <row>
    <entry>Command</entry>
    <entry>Description</entry>
   </row>
  </thead>
  <tbody>
   <row>
    <entry>/prots</entry>
    <entry>
Show any currently active prots on you. The output is only echoed
locally, use BatMUD 'tweak me' emote to list prots to party
report-channel.
</entry>
   </row>
   <row>
    <entry>/cprots</entry>
    <entry>
This command clears all prots on you. It is meant for those cases
where GgrTF is either bugging and does not notice a prot dropping,
or any other reason when you need to remove all prots at your
discretion.
</entry>
   </row>
   <row>
    <entry>tweak &lt;target&gt;</entry>
    <entry>
BatMUD's 'tweak' emote is used to report prots either to party
report-channel, or in case if the tweaker is not in same room,
via emote.
</entry>
   </row>
  </tbody>
 </tgroup>
</table>
</section>

</section>

<!-- ================================================ -->

<section id="usage-general-skillspell"><title>Skill and spell handling</title>
<para>
</para>
</section>

<!-- ================================================ -->

<section id="usage-misc"><title>Miscellaneous stuff (ggrtf-misc.tf)</title>
<para>
In the beginning of GgrTF's development, many features now residing
in misc-module were originally part of the core system. But as
the code grew, some features were deemed to be useful, but not to
be part of the basic core functionality nor part of any guild-specific
module either - thus the misc-module was created.
</para>

<itemizedlist>
 <listitem><para>
  <emphasis>Consider-skill reporting</emphasis>:
  Takes output of 'consider' skill and compresses the information
  into one prettyprinted line, which is reported. Output is
  name of the target, estimated experience worth and final
  estimation of target's toughness.
 </para></listitem>

 <listitem><para>
  <emphasis>Combat Damage Analysis reporting</emphasis>:
  Triggers for reporting results of CDA-skill to party report-channel.
 </para></listitem>

 <listitem><para>
  <emphasis>Simple hit statistics</emphasis>:
  Provides triggers for automatic gathering of melee hit statistics.
  This functionality is not even 50% perfect, but it gives  you some
  impression about how much damage you do. Only small portion of
  hit types are currently supported.
  Reporting is included, via /hstats -macro command.
 </para></listitem>

 <listitem><para>
  <emphasis>Purse contents prettyprinting</emphasis>:
  Highlites and colorizes the output of 'look at purse', and
  calculates total sum of money (in gold) contained in the purse.
 </para></listitem>

 <listitem><para>
  <emphasis>Camping status handling and reporting</emphasis>:
  Keeps note of whether you can use 'camping' skill. Reports
  the hp/sp/ep gained from resting.
 </para></listitem>

 <listitem><para>
  <emphasis>Ceremony status</emphasis>:
  Tracks status of ceremony, and provides macro "/ceremony",
  which executes ceremony skill only if ceremony is not active currently.
 </para></listitem>

 <listitem><para>
  <emphasis>Path compression for map.tf</emphasis>:
  TinyFugue distribution comes with map.tf, which
  enables easy creation of walkpaths (See "/help map" in TF).
  GgrTF adds an special purpose RLE compressor function, which
  reduces the length of the paths. Additional command to output
  the paths in format that is compatible with BatMUD's
  "command"-aliases is also provided.
 </para></listitem>

 <listitem><para>
  Plus numerous miscellaneous reporting- and helper-triggers.
 </para></listitem>

</itemizedlist>

<section>
&sectmacros;
</para>

<table><title>Commands</title>
 <tgroup cols="2" align="left">
  <thead>
   <row>
    <entry>Command</entry>
    <entry>Description</entry>
   </row>
  </thead>
  <tbody>

   <row>
    <entry>/rmisc</entry>
    <entry>
     Toggle general reporting features of this module. This setting
     affects the level of spam produced by features of misc-module.
    </entry>
   </row>

   <row>
    <entry>/hstats</entry>
    <entry>
     Print out current melee hit statistics.
    </entry>
   </row>

   <row>
    <entry>use consider at &lt;monster&gt;</entry>
    <entry>
     Whatever method you employ to use 'consider' skill,
     the output will be caught by consider-reporting trigger.
    </entry>
   </row>

   <row>
    <entry>/rcda</entry>
    <entry>
     Toggle reporting of Combat Damage Analysis. If set 'off',
     CDA reports are only displayed locally to you, if set 'on',
     reporting is done to party report channel.
    </entry>
   </row>

   <row>
    <entry>/ceremony</entry>
    <entry>
     Perform skill 'ceremony', but only if ceremony is not already "active".
    </entry>
   </row>
<!--
   <row>
    <entry></entry>
    <entry>
    </entry>
   </row>
-->
  </tbody>
 </tgroup>
</table>
</section>

</section>

<!-- ================================================ -->

<section id="usage-magical"><title>Magical guilds support (ggrtf-magical.tf)</title>
<para>
Base module for all things magical. This module is <emphasis>required</emphasis>
for supporting spells/casting. It is not necessary for being the receiving
end of prots or such. Several modules are dependant on this module, most
importantly those guild-specific modules that use magic.
</para>

<para>
Even in the case your guild does not use magic spells (nomad guilds), having
this module loaded is not harmful, so you can keep it in your configuration
at all times.
</para>

</section>

<!-- ================================================ -->

<section id="usage-pssmangle"><title>PSS-mangler (ggrtf-pssmangle.tf)</title>
<para>
This module provides support for filtering the output of
<emphasis>pss</emphasis> (<emphasis>party status short</emphasis>)
-command. It captures the status and prettyprints it out as a
3x3 table (as 9-man party formation) with player names and their
status information in compact format.
</para>

<para>
The HP/SP/EP values are coloured in accordance to what percentage the
player currently has of his maximum.  Additionally varying colouring of
player's name is used to indicate possible states of <emphasis>rest,
unconsciousness, stun and formation</emphasis>.
</para>

<para>
This module hooks to GgrTF's autopss-functionality (toggleable with
<link linkend="usage-general-commands">/autopss</link> option). A normally issued
'pss' command does not trigger the mangling functionality, but you can use
<emphasis>/pss</emphasis> macro or bind that to 'pss'. (See <link
linkend="usage-general-binds">Bindings</link>-section for more information.)
</para>

<screenshot>
 <mediaobject>
  <imageobject><imagedata fileref="pss_normal.gif" format="GIF" /></imageobject>
  <imageobject><imagedata fileref="pss_normal.eps" format="EPS" /></imageobject>
  <textobject>
   <phrase>Typical first row</phrase>
  </textobject>
  <caption>
   <para>
Typical output of PSS-mangler in a party with first row filled. Toivo
and Jeskko are near their maximum hp/sp/ep, but Ggr has taken some
damage (yellow HP) and is almost out of endurance points (red EP).
</para>
  </caption>
 </mediaobject>
</screenshot>

<screenshot>
 <mediaobject>
  <imageobject><imagedata fileref="pss_stun.gif" format="GIF" /></imageobject>
  <imageobject><imagedata fileref="pss_stun.eps" format="EPS" /></imageobject>
  <textobject>
   <phrase>Stunned</phrase>
  </textobject>
  <caption>
   <para>
In this screenshot example, Jeskko has become stunned (his name is
coloured in bright red). Also, Jeskko has lost some hitpoints
(dark green HP) and has only moderate amount of endurance left
(light yellow EP). <emphasis>(No Jeskkos were actually harmed
in producing this simulated situation.)</emphasis>
</para>
  </caption>
 </mediaobject>
</screenshot>

<screenshot>
 <mediaobject>
  <imageobject><imagedata fileref="pss_uncon.gif" format="GIF" /></imageobject>
  <imageobject><imagedata fileref="pss_uncon.eps" format="EPS" /></imageobject>
  <textobject>
   <phrase>Unconscious</phrase>
  </textobject>
  <caption>
   <para>
This screenshot shows how Toivo has taken some serious damage from
a blast to the backrow, and has become unconscious. White on bright
red background is used to highlight a unconscious player's name,
hopefully catching your attention.
</para>
  </caption>
 </mediaobject>
</screenshot>


<section><title>HP/SP/EP colours</title>
<para>
List of possible indicator colours and their meanings. &colourexplanation;
</para>


<table><title></title>
 <tgroup cols="2" align="left">
  <thead>
   <row>
    <entry>Colour</entry>
    <entry>Background</entry>
    <entry>Explanation</entry>
   </row>
  </thead>
  <tbody>
   <row>
    <entry>Bright White</entry>
    <entry>Bright Red</entry>
    <entry>Negative value (x &lt; 0)</entry>
   </row>
   <row>
    <entry>Bright Red</entry>
    <entry>-</entry>
    <entry>Less than 16% of max</entry>
   </row>
   <row>
    <entry>Red (dark)</entry>
    <entry>-</entry>
    <entry>Less than 33% of max</entry>
   </row>
   <row>
    <entry>Yellow (dark)</entry>
    <entry>-</entry>
    <entry>Less than 49% of max</entry>
   </row>
   <row>
    <entry>Bright Yellow</entry>
    <entry>-</entry>
    <entry>Less than 66% of max</entry>
   </row>
   <row>
    <entry>Green (dark)</entry>
    <entry>-</entry>
    <entry>Less than 85% of max</entry>
   </row>
   <row>
    <entry>Bright Green</entry>
    <entry>-</entry>
    <entry>More than 85% of max</entry>
   </row>
  </tbody>
 </tgroup>
</table>
</section>

<section><title>Player name colours</title>
<para>
List of possible name colours and their meanings. &colourexplanation;
</para>

<table><title></title>
 <tgroup cols="2" align="left">
  <thead>
   <row>
    <entry>Colour</entry>
    <entry>Background</entry>
    <entry>State description</entry>
   </row>
  </thead>
  <tbody>
   <row>
    <entry>Bright White</entry>
    <entry>-</entry>
    <entry>Normal</entry>
   </row>
   <row>
    <entry>Bright White</entry>
    <entry>Bright Red</entry>
    <entry>Unconscious (unc)</entry>
   </row>
   <row>
    <entry>Bright Red</entry>
    <entry>-</entry>
    <entry>Stunned (stun)</entry>
   </row>
   <row>
    <entry>Magenta</entry>
    <entry>-</entry>
    <entry>In form (form), member (mbr) or resting (rest)</entry>
   </row>
  </tbody>
 </tgroup>
</table>
</section>


<section>
&sectmacros;
</para>

<table><title>Macro commands</title>
 <tgroup cols="2" align="left">
  <thead>
   <row>
    <entry>Command</entry>
    <entry>Description</entry>
   </row>
  </thead>
  <tbody>
   <row>
    <entry>/pss</entry>
    <entry>Show party status in mangled format.</entry>
   </row>
   <row>
    <entry>/autopss</entry>
    <entry>Toggle automatic party status reporting. (Defined elsewhere)</entry>
   </row>
  </tbody>
 </tgroup>
</table>
</section>

</section>

<!-- ================================================ -->

<section id="usage-pplacer"><title>Party Placer (ggrtf-pplacer.tf)</title>
<para>
This module provides functionality for saving and restoring
party formation (places). Two simple to use macros can be
issued to save and restore.
</para>

<para>
<emphasis>NOTICE! This module requires
<link linkend="usage-pssmangle">PSS-mangler</link> module to be loaded!
</emphasis>
</para>

<section>
&sectmacros;
</para>

<table><title>Macro commands</title>
 <tgroup cols="2" align="left">
  <thead>
   <row>
    <entry>Command</entry>
    <entry>Description</entry>
   </row>
  </thead>
  <tbody>
   <row>
    <entry>/ppsave</entry>
    <entry>Save current party formation. Positions of party members
    in current formation are stored.
    </entry>
   </row>
   <row>
    <entry>/ppreset</entry>
    <entry>Resets or restores the party formation to the one saved
    previously. Restoring occurs fully automatically.
    </entry>
   </row>
  </tbody>
 </tgroup>
</table>
</section>

</section>

<!-- ================================================ -->

<section id="usage-spellnames"><title>Spellwords translator (ggrtf-spellnames.tf)</title>
<para>
This module adds in translating of spellwords to actual spell names.
It is very much based on original work of
<ulink url="http://www.bat.org/help/finger.php?str=cutter">Cutter</ulink>
and <ulink url="http://www.bat.org/help/finger.php?str=dazzt">Dazzt</ulink>,
well known highbie BatMUD players. Their code is used and re-licensed
under GPL with permission.
</para>

<para>
The translator works by printing the spell name in parentheses
on the line where the spellwords are. The translated name can
optionally replace the spellwords or it can be printed after them.
</para>

<para>
The spell name can be, if enabled, optionally printed in special
colour formatting, which is based on the general class/type of the spell.
This visual hinting can help you to notice if dangerous or 
otherwise interesting spells are cast.
</para>

<para>
Uncolorized examples of spellwords translator's output:
</para>

<screen>
You utter the magic words (unstun)

You utter the magic words 'Paxus' (unstun)

Acolyte waves his index finger while uttering (flame arrow)

Murrough throws a pinch of magic dust in air and chants (lightning storm)
</screen>

<section>
&sectmacros;
</para>
<para>
&paravariables;
</para>

<table><title>Macro commands</title>
 <tgroup cols="3" align="left">
  <thead>
   <row>
    <entry>Command</entry>
    <entry>Description</entry>
    <entry>Variable</entry>
    <entry>Values</entry>
   </row>
  </thead>
  <tbody>
   <row>
    <entry>/spwords</entry>
    <entry>Toggles showing of actual spell words on/off.</entry>
    <entry>opt_spwords</entry>
    <entry>&validonoff;</entry>
   </row>
   <row>
    <entry>/spcolorize</entry>
    <entry>Toggles colorization of spell name on/off.</entry>
    <entry>opt_spcolorize</entry>
    <entry>&validonoff;</entry>
   </row>
  </tbody>
 </tgroup>
</table>
</section>

</section>

<!-- ================================================ -->

<section id="usage-hc"><title>HCBat support (ggrtf-hc.tf)</title>
<para>
Due to the age of Hard Core BatMUD's current codebase and conceptual
differences, several exceptions and workarounds are needed to
improve GgrTF's compatibility with the HCBat environment.
This module tries to provide the glue to make it happen.
</para>

<para>
Purpose of this module is dissimilar to others, as it is meant
to contain almost everything related to peculiarities and
differences of HCBat. We do not have separate
guild-specific modules for HCBat, the code needed to
catch the differences is either in this module or in some
special cases in the guild-specific modules.
</para>

<para>
At the moment this module is rather simple, only replacing
GgrTF's output macros to work around the lack of 'party report'
-channel in HCBat. In future more functionality may be added,
feel free to report bugs/incompatibilities to us.
</para>

</section>

<!-- ================================================ -->

<section id="usage-tf5"><title>TinyFugue 5 support (ggrtf-tf5.tf)</title>
<para>
This is a special enhancement module for those who use GgrTF
with &tfurl; version 5. Although GgrTF should work with TF5
without this module, you may wish to take benefit of the
enhanced features designed for TF5 this module provides.
</para>

<itemizedlist>
 <listitem><para>
Enhanced 2-row statusline: First line contains HP/SP/EP- and
skill/spell/etc- information as usual. Prot status has been
moved to the second line.
</para></listitem>

</itemizedlist>

<!--
- example configuration
- document special variables
-->
</section>

<!-- ================================================ -->

<section id="usage-rais"><title>Raise/Resurrect/New Body/etc. (ggrtf-rais.tf)</title>
<para>
This module contains utility functionality for everyone who casts
different types of dead raising spells, including "raise dead",
"resurrect", "new body", "reincarnation", etc.
</para>

<para>
Automatic list is kept of people who have accepted some such service
from you, along with information what spell was requested. List can
be viewed, and you can launch a cast at the latest accept or by
specifying a player's name, cast his/her request.
</para>

<para>
You can either directly use the macros or use <link
linkend="usage-general-binds">command bindings</link>
to have shorthand commands instead.
</para>

<screenshot>
 <mediaobject>
  <imageobject><imagedata fileref="rais_list.gif" format="GIF" /></imageobject>
  <imageobject><imagedata fileref="rais_list.eps" format="EPS" /></imageobject>
  <textobject>
   <phrase>List of accepts</phrase>
  </textobject>
  <caption>
   <para>
An example output of "/aclist" macro, listing the players
who have accepted services from you and respective requested
spells for each. The time field shows how much
time has passed from the accept.
</para>
  </caption>
 </mediaobject>
</screenshot>


<section>
&sectmacros;
</para>

<table><title>Macro commands</title>
 <tgroup cols="3" align="left">
  <thead>
   <row>
    <entry>Command</entry>
    <entry>Default binding</entry>
    <entry>Description</entry>
   </row>
  </thead>
  <tbody>
   <row>
    <entry>/aclist</entry>
    <entry>acc</entry>
    <entry>
View list of people who have accepted something from you.
</entry>
   </row>
   <row>
    <entry>/accast [name]</entry>
    <entry>clast [name]</entry>
    <entry>
Cast Last-type functionality. Without arguments casts the LATEST
requested spell. Optionally you can specify a name of the player
and the spell requested by him/her is cast.
</entry>
   </row>
   <row>
    <entry>/acclear</entry>
    <entry>cclear</entry>
    <entry>
Clears the list. Useful, if the automatic removal
malfunctions for some reason. (For example, if target
uses 'pray' to become alive again, there is no message
provided to the caster.)
</entry>
   </row>
  </tbody>
 </tgroup>
</table>
</section>

</section>

<!-- ================================================ -->

<section id="usage-chann"><title>Guild: Channellers (ggrtf-chann.tf)</title>
<para>
Game-elements specific to channellers guild are supported and
enhanced by this module. At the moment, no special commands are
provided, all things are automagic.
</para>

<itemizedlist>
 <listitem><para>
  <emphasis>Channeller aura</emphasis>:
  Keeps note of your aura status and duration. If aura is up,
  it is notified in GgrTF's <link linkend="usage-general-statusline">statusline</link>.
  If your aura is weakening, that also is noted, reminding you
  to recharge.
 </para></listitem>
 <listitem><para>
  <emphasis>Blast resistance reporting</emphasis>:
  Adds support for channeller blasts into blast resistance
  reporting feature of <link linkend="usage-misc">miscellaneous module</link>.
 </para></listitem>
 <listitem><para>And other miscellaneous lesser features, such as
 fail and fumble handling, mana transfer cap reporting, etc.
 </para></listitem>
</itemizedlist>

</section>

<!-- ================================================ -->

<section id="usage-merchant"><title>Guild: Merchants (ggrtf-merchant.tf)</title>
<para>
This module provides, in addition to basic skill/spell fail/fumble
handling, several helper macros, which may ease your work as merchant.
</para>

<para>
Many of the command macros support "autotargetting", which basically
means that you can walk in outerworld and just type "/lj" for
lumberjacking and "/mine" for mining and GgrTF usually knows what
to do. Some macros require bit more specific arguments.
</para>

<para>
There is also support for merchant belt, which can be enabled if
you have one available. In case your belt is not complete or is
totally non-existent, the system has semi-automatic tool wielding
functionality: if you use /lj and then /mine, the macros will
automagically change to proper tools (saw -&gt; hammer/pick). The
system is not perfect, sometimes it may fail, but I'm working on it.
</para>

<para>
Notice that you probably MUST redefine some of these
macros and default settings in your TF configuration file!
(See <link linkend="usage-merchant-settings">Settings</link>-section below.)
</para>

<section>
&sectmacros;, (*) = autotargets, (!) = moves items to item target
</para>

<table><title>Macro commands</title>
 <tgroup cols="2" align="left">
  <thead>
   <row>
    <entry>Command</entry>
    <entry>Description</entry>
   </row>
  </thead>
  <tbody>
   <row>
    <entry>/havebelt</entry>
    <entry>Toggle support for merchant belt functionality on/off.</entry>
   </row>
   <row>
    <entry>/mdisc</entry>
    <entry>Change item move target to your floating disc.</entry>
   </row>
   <row>
    <entry>/mbox</entry>
    <entry>Change item move target to box (labeled as 'collect')</entry>
   </row>
   <row>
    <entry>/mdrop</entry>
    <entry>Change item move target to drop item.</entry>
   </row>
   <row>
    <entry>/lj [target]</entry>
    <entry>Use lumberjacking (at optional target, if no target given, autotargetting or previous specified target is used.) (*) (!)</entry>
   </row>
   <row>
    <entry>/mine [target]</entry>
    <entry>Use mining (at optional target, if no target given, autotargetting or previous specified target is used.) (*) (!)</entry>
   </row>
   <row>
    <entry>/mr &lt;material&gt;</entry>
    <entry>Make reagent from material.</entry>
   </row>
   <row>
    <entry>/gcut &lt;material&gt;</entry>
    <entry>Use gem cutting at material. (!)</entry>
   </row>
   <row>
    <entry>/amal &lt;material&gt;</entry>
    <entry>Amalgamate material.</entry>
   </row>
   <row>
    <entry>/refine &lt;material&gt;</entry>
    <entry>Refine material.</entry>
   </row>
   <row>
    <entry>/mcut &lt;material&gt; [size]</entry>
    <entry>Mineral cut material. Optional size can be give in grams.
If no size is specified, material is cut in half.</entry>
   </row>
  </tbody>
 </tgroup>
</table>

<table><title>Unfinished / buggy macros</title>
 <tgroup cols="2" align="left">
  <thead>
   <row>
    <entry>Command</entry>
    <entry>Description</entry>
   </row>
  </thead>
  <tbody>
   <row>
    <entry>/id &lt;item&gt; [target]</entry>
    <entry>Cast 'identify' spell at specified item and optionally
send output to target player. Example: /id ring jeskko</entry>
   </row>
   <row>
    <entry>/alloy &lt;materials&gt;</entry>
    <entry>Alloy given materials. Example: /alloy illumium,nullium</entry>
   </row>
  </tbody>
 </tgroup>
</table>
</section>

<section id="usage-merchant-settings">
&sectvariables;
   <row>
    <entry>opt_havebelt</entry>
    <entry>Enables merchant belt support. &validval; &validonoff;</entry>
   </row>
   <row>
    <entry>mtool_mine</entry>
    <entry>Tool(s) for mining. Example: <emphasis>/set mtool_mine=pick 1,pick 2</emphasis></entry>
   </row>
   <row>
    <entry>mtool_lj</entry>
    <entry>Tool(s) for lumberjacking. Example: <emphasis>/set mtool_lj=saw</emphasis></entry>
   </row>
   <row>
    <entry>mtool_bs</entry>
    <entry>Tool(s) for blacksmithing.</entry>
   </row>
   <row>
    <entry>mtool_cp</entry>
    <entry>Tool(s) for carpentry.</entry>
   </row>
   <row>
    <entry>mtool_gc</entry>
    <entry>Tool(s) for gem cutting.</entry>
   </row>
   <row>
    <entry>mtool_gb</entry>
    <entry>Tool(s) for glassblowing.</entry>
   </row>
   <row>
    <entry>mtool_ma</entry>
    <entry>Tool(s) for masonry.</entry>
   </row>
   <row>
    <entry>mtool_sw</entry>
    <entry>Tool(s) for sewing.</entry>
   </row>
   <row>
    <entry>mtool_sc</entry>
    <entry>Tool(s) for sculpture skill.</entry>
   </row>
   <row>
    <entry>mforge_*</entry>
    <entry>Forges/workbenches for skills (similar to mtool_* variables)</entry>
   </row>
&sectvariablesend;
</section>

</section>

<!-- ================================================ -->

<section id="usage-barb"><title>Guild: Barbarian (ggrtf-barb.tf)</title>
<para>
Provides a translator for barbarian reputation bar, reputation
difference calculator and handler for automated looting and burning.
</para>

<section>
&sectmacros;
</para>

<table><title>Macro commands</title>
 <tgroup cols="2" align="left">
  <thead>
   <row>
    <entry>Command</entry>
    <entry>Description</entry>
   </row>
  </thead>
  <tbody>
   <row>
    <entry>/repu</entry>
    <entry>
Prints your current reputation and reputation difference
from previous invoking of the command.
</entry>
   </row>
   <row>
    <entry>/lb</entry>
    <entry>
Starts looting and burning skill, lights a torch, waits for couple
of seconds and drops corpses from inventory. After burning the torch
is extinguished and current reputation printed out. Then action
determined by "/burnaction"-setting (see below) is executed.
If a skillbreak is detected, corpse dropping will be cancelled
immediately.
</entry>
   </row>
   <row>
    <entry>/burnaction &lt;action&gt;</entry>
    <entry>
Sets the action done after finished burning. Available options are:
<emphasis>none</emphasis>, <emphasis>cash</emphasis> (drop small coins)
and <emphasis>noeq</emphasis> (drop low coins and noeq).
</entry>
   </row>
  </tbody>
 </tgroup>
</table>
</section>
</section>

<!-- ================================================ -->

<section id="usage-spiders"><title>Guild: Spiders (ggrtf-spiders.tf)</title>
<para>
Provides basic support for managing spider demon, plus lites for spider
servants.
</para>

<section>
&sectmacros;
</para>

<table><title>Macro commands</title>
 <tgroup cols="2" align="left">
  <thead>
   <row>
    <entry>Command</entry>
    <entry>Description</entry>
   </row>
  </thead>
  <tbody>
   <row>
    <entry>/spidstatus</entry>
    <entry>Prints information about demon drains (and possibly other
status information in future).</entry>
   </row>
  </tbody>
 </tgroup>
</table>
</section>

</section>

<!-- ================================================ -->

<section id="usage-tarma"><title>Guild: Tarmalens (ggrtf-tarma.tf)</title>
<para>
</para>

</section>

<!-- ================================================ -->

<section id="usage-druid"><title>Guild: Druids (ggrtf-druid.tf)</title>
<para>
Barebones module with default bindings for some druid spells and
support for fails/fumbles.
</para>

</section>

<!-- ================================================ -->

<section id="usage-nun"><title>Guild: Nuns (ggrtf-nun.tf)</title>
<para>
</para>

</section>

<!-- ================================================ -->
<!--
<section id="usage-alch"><title>Guild: Alchemists (ggrtf-alch.tf)</title>

<para>This is (a slightly outdated) module with some helper macros for
Alchemists. The module has not been tested recently, so there may be
some problems with some of its features. Main features are can/jar
contents compressor and potion mixing helper macro.
</para>

<para>To use the potion mixer macro, you need to define your own
can/jar names and contents in the macro sources. Other
customization might be needed as well.
</para>

<section>
&sectmacros;
</para>

<table><title>Macro commands</title>
 <tgroup cols="2" align="left">
  <thead>
   <row>
    <entry>Command</entry>
    <entry>Description</entry>
   </row>
  </thead>
  <tbody>
   <row>
    <entry>/mixpot &lt;mineral&gt; &lt;organ&gt; &lt;herb&gt;</entry>
    <entry>Gets specified organ and herb from containers and tries to mix a potion with the specified components.</entry>
   </row>
  </tbody>
 </tgroup>
</table>
</section>
</section>
-->

<!-- ================================================ -->

<section id="usage-loc"><title>Guild: Lords of Chaos (ggrtf-loc.tf)</title>

<para>
Very barebones module with support for "blood" ripaction and
fail/fumble handling.
</para>

<section>
&sectmacros;
</para>

<table><title>Macro commands</title>
 <tgroup cols="2" align="left">
  <thead>
   <row>
    <entry>Command</entry>
    <entry>Description</entry>
   </row>
  </thead>
  <tbody>
   <row>
    <entry>/ripaction &lt;action&gt;</entry>
    <entry>LoC module adds option "blood" to /ripaction, which
automagically runs "lord_chaos blood corpse" on monster RIP.</entry>
   </row>
   <row>
    <entry>/locaction &lt;action&gt;</entry>
    <entry>This setting is related to LoCs, but defined in main
GgrTF module as also other than LoCs have use for this, if partying
with a LoC.</entry>
   </row>
  </tbody>
 </tgroup>
</table>
</section>
</section>

</chapter>

<!-- *************************************************************** -->

<chapter id="support"><title>Support</title>
<blockquote>
<attribution>The Matrix (parody of)</attribution>
<literallayout>
"Do not try to get support. That's impossible. Instead ... only try to realize the truth."
"What truth?"
"There is no support."
"There is no support?"
"Then you'll see that it is not the developer that bends, it is only yourself."
</literallayout>
</blockquote>

<itemizedlist>
 <listitem><para>Report bugs and feature-requests via our
&trackerurl;. A checklist for reporting bugs:</para>
  <itemizedlist>
  <listitem><para>Before reporting a problem, use the search
and browsing functionality of our &trackerurl; to check
if your issue is already reported.
</para></listitem>

   <listitem><para>Take your time to <emphasis>think</emphasis>
while writing, and before submitting your report. Good rule of
thumb is to include all information that you think might be
relevant, but no more than that!
</para></listitem>

  <listitem><para>
Remember to include information about your system and environment,
(*NIX/Linux/Windows), version of &tfurl; ("/ver" command in TF),
and of course the version of GgrTF ("/gver" command).
</para></listitem>

  </itemizedlist>
 </listitem>
 
 <listitem><para>We do not provide support for usage, please refer
to the user's manual and only in case the issue is not documented,
you might be eligible to ask about it.
</para></listitem>

 <listitem><para>Neither we provide technical support for extending
GgrTF, nor documentation of the internals. You'll have to figure out
the workings yourself.
</para></listitem>

 <listitem><para>Be ready to be contacted by developers, in case
help and/or more information is required with debugging your issue(s).
</para></listitem>

 <listitem><para>Remember not to bother the developers via tells
too much, we want to play the game too, instead of just answering
your questions and resolving problems.
</para></listitem>

<!--
 <listitem><para></para></listitem>
-->
</itemizedlist>

<section id="issues"><title>Known issues</title>
<itemizedlist>

 <listitem><para>This documentation sucks.</para></listitem>

 <listitem><para>GgrTF may or may not work very well together with other
trigger/scriptsets. Personally I only use only one triggerfile
not made by myself, your mileage may vary.</para></listitem>

 <listitem><para>Prots support generally is incomplete and occasionally
may not work as expected.</para></listitem>

 <listitem><para>Hitstats (/hstats) has some problems.</para></listitem>

 <listitem><para>There may still remain some incompabilities with TF5.</para></listitem>

<!--
 <listitem><para></para></listitem>
-->
</itemizedlist>
</section>

<!-- ================================================ -->

<section id="faq"><title>Frequently Asked Questions (FAQ)</title>
<qandaset>
  <qandaentry>
     <question>
       <para>Is "Grizzt" included in the documentation?</para>
     </question>
     <answer>
       <para>Unfortunately no. Grizzt may be included in some future version, though.</para>
     </answer>
  </qandaentry>

  <qandaentry>
     <question>
       <para>When will next version of GgrTF be released?</para>
     </question>
     <answer>
       <para>"When it's done."</para>
     </answer>
  </qandaentry>


  <qandaentry>
     <question>
       <para>How to get rid of the battle round flag/marker?</para>
     </question>
     <answer>
       <para>
The round marker (long line of asterisks "*") is required for GgrTF's
internal functionality, but you can gag it with following piece of
code (add it to your .tfrc or similar):
</para>
<screen>
/test prlist_insert("event_battle_round", "myroundgag")
/def -i myroundgag = /substitute -ag
</screen>
<para>
The first line adds macro "myroundgag" to be executed on each round marker,
the second line defines that macro and sets it to gag the round marker.
</para>
     </answer>
  </qandaentry>


  <qandaentry>
     <question>
       <para>My statusline is not updating, why?</para>
     </question>
     <answer>
       <para>
Maybe you haven't properly set up your 'short score' or 'prompt'
in BatMUD. See <link linkend="inst-config-batmud">setup-section</link>
for how to do that.
       </para>
     </answer>
  </qandaentry>

  <qandaentry>
     <question>
       <para>How can I get my settings saved automatically? Or can I?</para>
     </question>
     <answer>
       <para>Automatic saving and loading is possible, please refer to
       <link linkend="usage-general-saves">state-saving</link>
       and <link linkend="inst-config-ggrtf">setup</link> -sections of
       this manual for more information. 
       </para>
     </answer>
  </qandaentry>

  <qandaentry>
     <question>
       <para>A spell/prot cast by others at me registers in prot-reporting,
       but does not work when I cast it on myself!</para>
     </question>
     <answer>
       <para>
       This is most likely a bug, please report the issue on GgrTF's
       &trackerurl;. Remember to include the lines you get when you
       cast the spell on yourself (aka the "prot goes up"-line).
       </para>
       <para>
       Also see the next question below.
       </para>
     </answer>
  </qandaentry>

  <qandaentry>
<!--
     <question>
       <para>Some prots do not register / are not noticed by GgrTF</para>
     </question>
-->
     <question>
       <para>Sometimes the <link linkend="usage-spellnames">
       spellword translator</link> does not work, what gives?</para>
     </question>
     <answer>
       <para>Your 'cutter'-setting might be too small, the default
       in BatMUD is 80, which adds hard linefeeds too early on a line,
       thus breaking many triggers of GgrTF, including GgrTF::Spellnames
       module. 'cutter 9999' or 'cutter off' should fix this problem.
       </para>
       
       <para>Please refer to <link linkend="inst-config-batmud">
       BatMUD settings</link> -section of this manual for correct
       in-game settings.
       </para>
     </answer>
  </qandaentry>

<!--
  <qandaentry>
     <question>
       <para></para>
     </question>
     <answer>
       <para>
       </para>
     </answer>
  </qandaentry>
-->
</qandaset>
</section>

</chapter>

</book>