Rename part of the documentation:

tables.txt        -> aptitudes.txt
crawl_macros.txt  -> macros_guide.txt
crawl_options.txt -> options_guide.txt

And while I already was at it, I added windows style linebreaks
for ssh_guide.txt and monster_speech.txt, as well. Since I've
somehow managed to uninstall my notepad (ages ago), opening 
and changing such files is always a bit fiddly, and I hope this
change doesn't hurt anyone else.

crawl_manual.txt will also eventually need these, but we haven't 
yet decided on the new name.

Also update monster_speech.txt (yet again), and add hounds 
sniffing the ground to monspeak.txt as an in-game hint for blood 
scent.


git-svn-id: https://crawl-ref.svn.sourceforge.net/svnroot/crawl-ref/trunk@3937 c06c8d41-db1a-0410-9941-cceddc491573

1 files changed, 152 insertions, 0 deletions

diff --git a/crawl-ref/docs/macros_guide.txt b/crawl-ref/docs/macros_guide.txt
new file mode 100644
index 0000000000..252db61abc
--- /dev/null
+++ b/crawl-ref/docs/macros_guide.txt
@@ -0,0 +1,152 @@
+Macros and Keymaps
+==================
+
+What are macros and keymaps? The simple explanation is:
+
+Command macros make keys into commands.
+Keymaps make keys into other keys.
+
+Or a bit more verbose:
+
+For the most part, people will probably want command macros. They allow
+for things like making a key run a sequence of commands (e.g.
+associating a key stroke to the casting of a certain spell) without
+having to worry about messing up what that key does at prompts (e.g.
+you can macro a number or letter without worrying about it making the
+substitution when you're trying to drop an item).
+
+Keymaps are for when you want to fix layout and behavioural problems on
+your keyboard (i.e. unrecognised numpad sequences can by mapped into
+their numbers, foreign keyboard layouts can be modified to be more
+comfortable). There are also special sets of keymaps for the level map,
+the targeting mode and confirmation prompts, which allow for mappings
+that are restricted to just those situations.
+
+
+How to create macros and keymaps?
+=================================
+
+The simplest way is in-game: Press either the '~' key or Ctrl-D, select
+'m' to define a macro, then choose a key to assign for your macro and
+enter the command sequence. For some keys (or key combinations), Crawl
+will display a strange number (for example \{13} for the Return key).
+These numbers are the key codes for certain non-alpanumeric keys and
+can vary between different systems.
+
+By default, most upper- and lowercase alphanumeric keys are already
+assigned functions in Crawl. While you are free to remap those keys as
+well, it might be best to start with some of the currently unused keys,
+such as Tab or the function keys (F1 to F12), possibly combined with
+Ctrl, Shift or both. On some systems, it may also be possible to
+incorporate the Alt (Meta) key.
+
+Defining keymaps works in exactly the same way. Just press 'k'
+(default), 'x' (level-map), 't' (targeting) or 'c' (confirmation)
+instead of 'm' after pressing '~'.
+
+After defining such a macro or keymap, you should test it. If you are 
+comfortable with it, you should then save the macro. To save all macros 
+and keymaps, press '~' and then 's' to save macros at the tilde prompt).
+
+
+The macro.txt file
+==================
+
+Macros and keymaps are stored in a file called macro.txt in your main
+Crawl directory or your home directory. You can change where the file
+is read from and written to by specifying an alternate directory on
+the command line with -macro <dir> or with the crawl_dir option in your
+init file (see crawl_options.txt for details). The macro.txt file is
+human readable and editable, but you might have to figure out the key
+codes for non-alphanumeric keys through in-game experimentation or
+external utilities.
+
+Lines beginning with the '#' are comments and will be ignored. Note
+that Crawl won't necessarily preserve your comments when saving macros
+and keymaps to the macro.txt file.
+
+Each macro definition consists of exactly two lines. The first one
+describes the macro trigger key and consists of "M:" followed by the
+character or keycode of that key (for example 'a', 'A' or \{9} for
+the A, Shift-A or Tab keys). The second one describes the macro action
+and consists of "A:" followed by the command sequence to be associated
+with the above key (for example "zap" for zapping the spell in slot a
+at the previous target). Individual macro definitions should be
+separated by empty lines.
+
+For keymaps just replace the "M:" on the first line of the definiton
+with one of the following:
+"K:"  default, 
+"K1:" level-map, 
+"K2:" targeting or 
+"K3:" confirmation.
+
+
+Examples
+========
+
+This section contains some examples to give you an idea what macros and
+keymaps can be used for. Note that for the sake of completeness, both
+key line and command line are given, but that you should probably
+substitute your own keys here as these may not always work for you.
+
+
+'@' is a character that may not work by default on some keyboard
+layouts. The following should remedy that by mapping '@' to '@'.
+
+# @: display character status
+K:\{17}
+A:@
+
+
+Playing a summoner can be annoying because you often need to cast the
+same spells multiple times in a row, each casting requiring multiple
+keystrokes. This macro allows casting the spell in slot 'a' with a
+single keystroke. Note that you can redefine spell slots with the '='
+key. We emphasise again that the F1 key may get a different code on
+your system.
+
+# F1: cast spell 'a'
+M:\{368}
+A:za
+
+
+Now that we've taken care of summoning, we still need to command our
+summoned creatures. The following macro should make that easier as
+well. Note that this macro assumes that the default_target option is
+set to true (it is by default; see crawl_options.txt for details).
+
+# Tab: Order allies to attack your previous or the nearest target
+M:\{9}
+A:!a.
+
+
+Conjurers need a slightly different macros for casting, such as this
+one, as they need to press '.' or Return to confirm firing at a target.
+Again, this macro assumes that the default_target option is set to
+true.
+
+# F1: cast spell 'a' at your previous or the nearest target
+M:\{368}
+A:za.
+
+
+However, even conjurers might not always want to fire at their previous
+target, so the following set of macros allows them to cast the spell
+in slot 'a' and then cycle through the available targets with the same
+key and then confirming with the same key we used for firing in the
+previous macro. This example also tries to illustrate how to take
+advantage of the fact that keys can have different functions in the
+different keymaps.
+
+# Shift-F1: cast spell 'a'
+M:\{1392}
+A:za
+
+# Shift-F1: cycle through targets when in targetting mode
+K2:\{1392}
+A:+
+
+# F1: fire at target when in targetting mode
+K2:\{368}
+A:.
\ No newline at end of file