Fspell 2.10
~~~~~~~~~~~

What is it?
-----------
	Fspell is a utility to automate the production of '.prf' files
mapping prayers/spells onto function keys for Angband.  The source file
is much easier to setup and alter than the raw .prf files.

How to use it?
--------------
	At the command line, or in a TaskWindow, type:
	fspell <invocation> <source> <dest>
Where <incovation> is the command used to invoke a prayer/spell (ie. p for
priests/paladins or m for mages/rangers/rogues), <source> is the filename
of the source fspell file and <dest> is the filename you want the resulting
.prf file to be saved with.

How do I use the .prf file?
---------------------------
	Well, if you look inside the !Angband application, you'll see a
subdirectory called 'lib'.  Open this and then the directory 'user' inside
it.  This is where Angband looks for .prf files when loading.  The rules
about which files are used when are a bit complex, but briefly, Angband looks
for 'paladin/prf' whenever you play a paladin, 'mage/prf' when you play a mage,
etc. (note that due to the 10 character limit on filenames, 'paladin/prf'
should actually be 'paladin/pr', etc).

Okay, but how do I set up the source file?
------------------------------------------
	The syntax of the source file is simple.  Each line has a 'key
mapping' on it (or is a comment prefixed by '#', or is blank).
A 'key mapping' consists of a (possibly modified) function key and the
book/spell that you want that key to invoke.
The keys are specified as 'f9', etc.  You can prefix the 'f9' with 's' for
Shift, 'c' for Control, or 'sc' for Shift-Control.  Thus, shift-F5 is
written 'sf5' (case insensitive).  You may not use F12, if you try to
then fspell will complain.
Next there's a ':', and then the book/spell information as two characters.
The first character is the book, and should preferably be a number (see
the note on inscriptions).  The second character is the spell within the
book and should be the letter used when selecting that spell (eg. 'a'
for magic missile in the first book).
Then there's another :, and optionally the name of the spell.  This is
only used to put comments in the generated .prf file.

	So, to map key F1 to invoke a magic missile, you'd say (assuming your
spell books are inscribed as recommended below:
	f1:1a:Magic Missile
or,
	f1:1a
etc.

	If the keycode part of the line (the 'f1' bit) is missing, then no
mapping will be made.  Thus, ':1a:Magic missile' does nothing.  If you really
want, you can use '!' as the key name to denote 'unmapped'.

	It's an error to map more than one spell onto a single key, but
perfectly okay to map a single spell onto multiple keys.

	In the Examples directory there are two source files called
'~eeekle' and '~moogle'.  These are examples of key mappings.  Actually,
they're the mappings that I use for my rangers and my wife uses for her
paladins.


But I can't remember all those spell letters!
---------------------------------------------
	No, neither can I.  So, if you look in the Examples directory you'll
see two files called 'priest' and 'mage'.  These contain 'blank' source
files that you can simply insert your desired key-mappings into.  You'll
have to inscribe your books as detailed below and in those files for them
to work though.  Note that the books are the same for paldins and priests,
and also the same for mages, rangers and rogues, although some classes
can't use certain spells (eg. rangers can't cast 'genocide').

What's all this about inscription?
----------------------------------
	Well, books can move around in your pack.  For example, if you
lose all your books in slot 'b', the books in slot 'c' will drop down
into the now empty slot.  Obviously, if you've set the mapping up
so that a key uses the book in slot 'b', you'll get the wrong results.
(Of course, if you have the inventory options set so that objects
can't move around in your inventory, this doesn't apply.  Even then
it's preferable to refer to books by number so that it doesn't matter
what slot a book gets put in when you pick it up).

	So how do you get around it?  Well, it's simple.  Angband allows
you to 'inscribe' objects with descriptions.  The descriptions can be
special sequences that have meaning to the game.  I shan't go into
the whole gory details, but it's well worth looking at the help files
to find out all the wonderful things you can do.  The upshot of all this
is that if you inscribe a book with @p1 (or @m1 for mages, etc), then whenever
Angband asks 'use which book', you can say '1' and the book will be used
regardless of which slot it's actually in.

	Thus, priests/paladins should inscribe their books:
Beginners handbook - @p1
Words of Wisdom - @p2
Chants & Blessings - @p3
Exorcisms and Dispellings - @p4
Ethereal Openings - @p5
Godly Insights - @p6
Purifications and Healing - @p7
Holy Infusions - @p8
Wrath of God - @p9

	And mages/rangers/rogues should inscribe their books:
Magic for Beginners - @m1
Conjuring & Tricks - @m2
Incantations & Illusions - @m3
Sorcery & Evocations - @m4
Resistance of Scarabtrices - @m5
Mordenkainen's Escapes - @m6
Kelek's Grimoire of Power - @m7
Tenser's Transformations - @m8
Raal's Tome of Destruction - @m9


So, there you have it!

Also, there's a drawfile 'keystrip' for a blank function key strip.
You could print this out then write on it, or put the text on it
with Draw (the boxes are all invidual objects.  This is so that
you can use the justification facilities of draw to tidy your
keystrip nicely :-)

Disclaimer
~~~~~~~~~~
Use of this software is completely at your own risk. The author can accept no
responsibility for any damage/loss arising from the use, or inability to use
this software. No warranty, express or implied, applies to this software.
This is not PD: the Copyright in this software belongs at all times to the
author. However, permission is granted for unrestricted distribution
prodividing that *no* charge is made for the distribution [a charge may be made
for handling/media] and that the whole of the software is supplied intact and
unaltered. Permission is also granted for unrestricted use and alteration of
the software [but if you fix a bug / add anything nice, let me know so I can
patch the 'master' version].

Bug reports / comments / etc to:

e-mail: mailto:musus@argonet.co.uk
   web: http://www.argonet.co.uk/users/musus/
 snail: Adny Holdsworth,
        c/o 23 Baronsway,
        Whitkirk,
        Leeds,
        LS15 7AW,
        England.


