=== User Pref Files ===

        Unangband allows you to change various aspects of the game to suit
your tastes.  You may define keymaps (changing the way Unangband maps your
keypresses to underlying commands), create macros (allowing you to map a
single keypress to a series of keypresses), modify the visuals (allowing
you to change the appearance of monsters, objects, or terrain features),
change the colors (allowing you to make a given color brighter, darker,
or even completely different), or set options (turning them off or on).

        Unangband stores your preferences in files called "user pref files",
which contain comments and "user pref commands", which are simple strings
describing one aspect of the system about which the user has a preference.
There are many ways to load a user pref file, and in fact, some of these
files are automatically loaded for you by the game.  All of the files are
kept in the "lib/user/" directory, though you may have to use one of the
command line arguments to redirect this directory, especially on multiuser
systems.  You may also enter single user pref commands directly, using the
special "Enter a user pref command" command, activated by "double quote".
You may have to use the "redraw" command (^R) after changing certain of
the aspects of the game, to allow Unangband to adapt to your changes.

        When the game starts up, after you have loaded an old character,
or created a new character, some user pref files are loaded automatically.
First, the "pref.prf" file is loaded.  This file contains some user pref
commands which will work on all platforms.  Then one of "font-xxx.prf"
(for normal usage) or "graf-xxx.prf" (for bitmap usage) is loaded.  These
files contain attr/char changes to allow the monsters, objects, and/or
terrain features to look "better" on your system.  Then the "pref-xxx.prf"
file is loaded.  This file contains pre-defined system specific stuff
(macros, color definitions, etc).  Then, the "user-xxx.prf" file is loaded.
This file contains user-defined system specific stuff.  The "user-xxx.prf"
file is used as the "default" user pref file in many places.  The "xxx" is
the "system suffix" for your system, taken from the "main-xxx.c" file which
was used to generate your executable.  Finally, the "Race.prf", "Class.prf",
and "Name.prf" files are loaded, where "Race", "Class", and "Name" are
replaced by the actual race, class, and name of the current character.

        Several commands allow you to both load existing user pref files,
create new user pref files, append information to existing user pref files,
and/or interact with various of the user preferences in a more intuitive
way than the user pref commands allow.  The commands include "Interact with
macros" (@), "Interact with visuals" (%), and "Interact with colors" (&),
described below.

--- User Pref Files (Macros) ---

        The "Interact with macros" command allows you to define or remove
"macros", which are mappings from a single logical keypress to a sequence
of keypresses, allowing you to use special keys on the keyboard, such as
function keys or keypad keys, possibly in conjunction with modifier keys,
to "automate" repetitive multi-keypress commands that you use a lot.

        Since macros represent keypress sequences, and not all keypresses
have a printable representation, macro triggers and actions must often be
"encoded" into a human readible form.  This is done using several types
of encoding, including "\xHH" for character number HH in hexidecimal, "\e"
for the "escape" code, "\n" for the "newline" code, "\r" for the "return"
code, "\s" for the "space" code, "\\" for backslash, "\^" for caret, and
"^X" for the code for any "control" key "ctrl-X".  Note that the "action"
of a macro will not be checked against other macro triggers (unless the
macro action contains a "control-backslash"), so you cannot make infinite
loops.  You may specify extremely long macros, but you are limited in
length by the underlying input mechanisms, which in general limit you
to about 1024 keys in both triggers and actions.

        The special "\" command (which must be encoded in macros as "\\")
is very useful in macros, since it bypasses all keymaps and allows the next
keystroke to be considered a command in the underlying Unangband command set.
For a list of the Unangband command set, see the "command.txt" help file.
For example, a macro which maps Shift-KP6 to "\" + "." + "6" will induce
the "run east" behavior, regardless of what keyset the user has chosen, and
regardless of what keymaps have been defined.

	Macros can be specified in user pref files as a pair of lines, one
of the form "A:<str>", which defines the encoded macro action, and one of
the form "P:<str>", which defines the encoded macro trigger.

--- User Pref Files (Keymaps) ---

        The "Interact with macros" command also allows you to define
"keymaps", which are vaguely related to macros.  A keymap maps a single
keypress to a series of keypresses, which bypass both other keymaps and
any macros.  Unangband uses keymaps to map the original and the roguelike
keysets to the underlying command set, and allows the user to modify or
add keymaps of their own.  Note that all keymap actions must be specified
using underlying commands, not keypresses from the original or roguelike
keysets.  The original keyset is almost identical to the underlying keyset,
except that "numbers" are mapped to ";" plus a direction, "5" is mapped to
",", and a few control-keys are mapped to various things.  See "command.txt"
for the full set of underlying commands.  Some uses for keymaps include the
ability to "disable" a command by mapping it to "\x00", 

	Keymaps can be specified in user pref files as line of the form
"M:<T> <key> <str>", where <T> is the keyset (0/1 for original/roguelike),
<key> is the encoded trigger key, and <str> is the encoded keymap action.

--- User Pref Files (Visuals) ---

        You can use the "Interact with visuals" command to change various
visual information, currently including the choice of what attr/char values
are used to represent various monsters, objects, or terrain features.  Note
that in combination appropriate support in "main-xxx.c", and with the use of
the "use_graphics" flag, you may be able to specify that "graphic bitmaps"
should be used instead of normal "colored characters" for various things.

        When interactively modifying the attr/char values for monsters,
objects, or terrain features, pressing "n" or "N" will change which entry
you are changing, pressing "a" or "A" will rotate through the available
attr values, and pressing "c" or "C" will rotate though the available char
values.  Note that attr/char values with the "high bit" set may induce the
display of special "graphic" pictures if the "use_graphics" flag is set,
and your system supports the "use_graphics" flag.

        Note that this command can be abused in various ways, and if you
must do so, remember that you are only cheating yourself.

	Keymaps can be specified in user pref files as line of the form
"R:<N>:<A>/<C>" or "K:<N>:<A>/<C>" or "F:<N>:<A>/<C>" or "U:<N>:<A>/<C>".

--- User Pref Files (Colors) ---

        The "Interact with colors" command allows you to change the actual
internal values used to display various colors.  This command may or may
not have any effect on your machine.  Advanced machines may allow you to
change the actual RGB values used to represent each of the 16 colors used
by Unangband, and perhaps even allow you to define new colors which are not
currently used by Unangband.

	Colors can be specified in user pref files as line of the form
"V:<N>:<V>:<R>:<G>:<B>".

--- User Pref Files (Options) ---

        The "Interact with options" command allows you to turn options
on or off.  You may turn options off or on using the user pref commands
of the form "X:<option>" or "Y:<option>" respectively.

