Update documentation for 0.4.

Apply recent commits.


git-svn-id: https://crawl-ref.svn.sourceforge.net/svnroot/crawl-ref/branches/stone_soup-0.4@6458 c06c8d41-db1a-0410-9941-cceddc491573

13 files changed, 347 insertions, 206 deletions

diff --git a/crawl-ref/README.pdf b/crawl-ref/README.pdf
index ed2ed6fbed..06411e178f 100644
--- a/crawl-ref/README.pdf
+++ b/crawl-ref/README.pdf
diff --git a/crawl-ref/README.txt b/crawl-ref/README.txt
index e6b9749d63..688e94597d 100644
--- a/crawl-ref/README.txt
+++ b/crawl-ref/README.txt
@@ -8,7 +8,7 @@ prevail against overwhelming odds.
 
 Players of versions 0.3.4 and older beware: please read the file
    034_changes.txt
-in the /docs directory for a list of the interface changes, and how 
+in the docs/ directory for a list of the interface changes, and how 
 you could possibly retrieve the 0.3.4 standards.
 
 Contents:
@@ -25,22 +25,26 @@ If you'd like to dive in immediately, your best bets are to
 * read quickstart.txt (in the /docs directory), or
 * for studious readers, browse the manual (see below for all doc files).
 
-If you're used to playing an older version, you might want to print out the 
-file key_changes.pdf from the /docs for an easy reference of new commands
-and changed key settings.
-Note that you can read quickstart.txt and the manual when playing; pressing '?' 
-brings up a menu for that.
+Internet play:
+You can play Crawl online, both competing with other players and watching 
+them. Check the homepage at crawl.akrasiac.org for details, including 
+information about additional servers. You just need a ssh or telnet console; 
+on Windows, the \key{PuTTY} program works very well. Read docs/ssh_guide.txt
+for a step by step guide on how to set this up.
+
+Tiles:
+Crawl features an alternative to the classical ASCII display; Tile-based
+Crawl is often a lot more accessible by new players. Tiles are available for 
+Linux, Windows and OS X.
+Unfortunately, it is not yet possible to combine tiles and internet play.
 
 
 2. File system
 --------------
 The following files in the Crawl's main folder are essential:
 
-* crawl           These start the game. (The actual name depends on your
-* crawl.exe       operating system.)
-
-* macro.txt       Playing Crawl can be made even more convenient by
-                  redefining keys and assigning macros. Ignore early on.
+* crawl              These start the game. (The actual name depends on your
+* crawl.exe          operating system.)
 
 The docs/ folder contains the following helpful texts (all of which can be 
 read in-game by bringing up the help menu with '?'):
@@ -50,26 +54,20 @@ read in-game by bringing up the help menu with '?'):
 * options_guide.txt  Describes all options in detail. The structure of
                      init.txt follows this text.
 * macros_guide.txt   A how-to on using macros and keymappings, with examples.
-* aptitudes.txt      Some numbers defining certain aspects of the races.
-                     Helpful, but not needed for winning.
-* quickstart.txt     A short introduction for new players.
-* quickstart.pdf     The same file, in pdf format.
-* ssh_guide.txt      An elaborate introduction on how to get internet play
-                     to work. For Windows only.
 * tiles_help.txt     An explanation of the Tiles interface.
-* key_changes.pdf    A printable document, listing all new commands and 
-                     changed key settings.
 
 The settings/ folder contains, among others, the following files:
 
-* init.txt        These contain the options for the game. The defaults
-* .crawlrc        play well, so don't bother with this in the beginning.
-                  Permanent death is not an option, but a feature!
+* init.txt           These contain the options for the game. The defaults
+* .crawlrc           play well, so don't bother with this in the beginning.
+                     Permanent death is not an option, but a feature!
+* macro.txt          Playing Crawl can be made even more convenient by
+                     redefining keys and assigning macros. Ignore early on.
 
 
 3. Contact and reporting bugs
 -----------------------------
-The official webpage is
+The official webpage is at
       http://crawl-ref.sourceforge.net/
 and there you can find both trackers to add bug reports, feature requests, or 
 upload patches, as well as sources and binaries. This is the best way to report 
@@ -81,12 +79,6 @@ It is polite to flag your post with -crawl- as other games are discussed over
 there as well. This is a good place to ask general questions, both from new 
 players as well as for spoilers, or to announce spectacular wins.
 
-You can play Crawl online, together with many others. The main server has its 
-homepage at
-      http://crawl.akrasiac.org/
-where you can also read how to connect. That page also has links to spoiler 
-sites etc.
-
 If you want to chime in with development, you can read the mailing list
       crawl-ref-discuss@lists.sourceforge.net
 which can get pretty busy on the occasion.
@@ -97,7 +89,7 @@ which can get pretty busy on the occasion.
 What you have downloaded is a descendant of Linley's Dungeon Crawl. Development
 of the main branch stalled at version 4.0.0b26, with a final alpha of 4.1 being
 released by Brent Ross in 2005. Since 2006, the Dungeon Crawl Stone Soup team 
-has been continuing the development. See the CREDITS in the mail folder for a
+has been continuing the development. See the CREDITS in the main folder for a
 myriad of contributors, past and present; license.txt contains the legal blurb.
 
 Dungeon Crawl Stone Soup is an open source, freeware roguelike. It is supported 
diff --git a/crawl-ref/docs/034_changes.txt b/crawl-ref/docs/034_changes.txt
index 2fc88b6405..a6c2521d34 100644
--- a/crawl-ref/docs/034_changes.txt
+++ b/crawl-ref/docs/034_changes.txt
@@ -1,77 +1,89 @@
-Information for players of versions 0.3.4 or earlier
-----------------------------------------------------
-
-There have been many changes to the interface in the new version. Among
-them:
-
-* Swapped some command keys around:
-   G         auto-travel      (was Ctrl-G)
-   z         cast spell       (was Z)
-   Z         zap wand         (was z)
-   o         auto-explore     (was Ctrl-O)
-   Ctrl-O    dungeon overview (was O)
-   O         open door        (was o)
-   C         close door       (was c)
-   c         chop up          (was D, dissect)
-   E         show experience  (was C)
-   v         evoke            (was E)
-   f, F      fire/throw       (was t)
-   t         tell/yell        (was !)
-   Ctrl-V    Tiles settings   (was Ctrl-Q)
-   Ctrl-Q    quit             (was Q)
-
-* Added some new commands:
-   `         repeat previous command
-   0         repeat next command # of times
-   !         annotate dungeon level
-             (If your annotation contains '!' you'll be prompted whenever 
-             you attempt to enter the level.)
-   (         cycle the quiver to the next appropriate item
-   Ctrl-D    define macros (synonym to '~')
-   Ctrl-G    verbose list of monsters in sight
-   Ctrl-T    change your allies' pickup behaviour
-             (only available to some characters)
-   Q         quiver an item for firing
-
-   There is a file called "key_changes.pdf" in the /docs directory that
-   lists all of these command changes on a printable reference sheet.
-
-* Removed the v command (view item in inventory). Its functionality is
-   provided by pressing i (showing the inventory) and the letter for the
-   item, at the same number of key presses.
-
-* The chop up (formerly dissect) interface is modified: there is no
-   prompt anymore for single corpses. In case of several corpses on the
-   square, you may use 'c' as a synonym for yes, and 'a' will answer yes
-   to this and all further corpses. In particular, all corpses in a square
-   can be sacrificed with 'pca'.
-
-* The colours of many monsters have been changed. Most notably, there are
-   no darkgrey monsters anymore. In case darkgrey is actually better
-   visible than blue on your system, you can swap these colours using
-     colour: darkblue = darkgrey
-   in init.txt.
-   Apart from that, more dangerous monsters are now generally displayed in
-   lighter colours.
-
-We are content that all of these changes are genuine improvements. Should
-your brain be hardwired to the old settings, you can effectively enforce
-the 0.3.4 state by using the following options:
-   include                 = 034_monster_glyphs.txt
-   additional_macro_file   = 034_command_keys.txt
-   always_confirm_butcher  = true
-
-Note that the header of init.txt contains these lines. (It contains some 
-more options for using other old settings.) The options are commented out, 
-so you just need to remove the # in front in order to activate them. You 
-can choose to use only part of these options. In case you decide to use 
-the old keyset, be aware that D is also a synonym for 'yes' in the 
-butcher interface.
-
-If you choose to go with the new keyset or the new butcher interface and
-you intend to use your old macros, you'll need to look through your 
-macro.txt file.
-
-There are a number of new options, some of them outsourced into various
-files in the /settings folder, so if you intend to use your old init file,
-you may still want to at least look through the new one.
+Information for players of versions 0.3.4 or earlier

+----------------------------------------------------

+

+There have been many changes to the interface in the new version. Among

+them:

+

+* Swapped some command keys around:

+   G         auto-travel      (was Ctrl-G)

+   z         cast spell       (was Z)

+   Z         zap wand         (was z)

+   o         auto-explore     (was Ctrl-O)

+   Ctrl-O    dungeon overview (was O)

+   O         open door        (was o)

+   C         close door       (was c)

+   c         chop up          (was D, dissect)

+   E         show experience  (was C)

+   v         evoke            (was E)

+   f, F      fire/throw       (was t)

+   t         tell/yell        (was !)

+   Ctrl-V    Tiles settings   (was Ctrl-Q)

+   Ctrl-Q    quit             (was Q)

+

+* Added some new commands:

+   !         annotate dungeon level

+             (If your annotation contains '!' you'll be prompted whenever 

+             you attempt to enter the level.)

+   (         cycle the quiver to the next appropriate item

+   Q         quiver an item for firing

+   `         repeat previous command

+   0         repeat next command # of times

+   Ctrl-D    define macros (synonym to '~')

+   Ctrl-G    verbose list of monsters in sight

+   Ctrl-T    change your allies' pickup behaviour

+             (only available to some characters)

+

+

+   There is a file called "key_changes.pdf" in the /docs directory that

+   lists all of these command changes on a printable reference sheet.

+

+* Removed the 'v' command (view item in inventory). Its functionality is

+  provided by pressing 'i' (showing the inventory) and the letter for the

+  item, at the same number of key presses.

+

+* The chop up (formerly dissect) interface is modified: there is no

+  prompt anymore for single corpses. In case of several corpses on the

+  square, you may use 'c' as a synonym for yes, and 'a' will answer yes

+  to this and all further corpses. In particular, all corpses in a square

+  can be sacrificed with 'pca'.

+

+* When targeting, the functions of '!' and '.' have been swapped. Thus

+  firing with '.' will now stop at the target, whereas '!' will shoot 

+  further if the target was missed. Enter etc. still behave as in 0.3.4.

+  You can now target using the monster list; Cltr-L toggles this option.

+  You can quiver an item, meaning that you will preferably fire this

+  ammunition (and keep doing so even if you run out of it temporarily).

+  Quivering is done via 'Q' (quiver the currently fired item) or 'fi'

+  (choose an item for firing and quiver it) or also by using '(' which

+  cycles appropriate ammunition. 'F' lets you select an item to be thrown

+  without affecting the quiver.

+

+* The colours of many monsters have been changed. Most notably, there are

+  no darkgrey monsters anymore. In case darkgrey is actually better

+  visible than blue on your system, you can swap these colours using

+     colour: darkblue = darkgrey

+  in init.txt.

+  Apart from that, more dangerous monsters are now generally displayed in

+  lighter colours.

+

+We are content that all of these changes are genuine improvements. Should

+your brain be hardwired to the old settings, you can effectively enforce

+the 0.3.4 state by using the following options:

+   include                 = 034_monster_glyphs.txt

+   additional_macro_file   = 034_command_keys.txt

+   always_confirm_butcher  = true

+

+Note that the header of init.txt contains these lines. (It contains some 

+more options for using other old settings.) The options are commented out, 

+so you just need to remove the # in front in order to activate them. You 

+can choose to use only part of these options. In case you decide to use 

+the old keyset, be aware that D is also a synonym for 'yes' in the 

+butcher interface.

+

+If you choose to go with the new keyset or the new butcher interface and

+you intend to use your old macros, you'll need to look through your 

+macro.txt file.

+

+There are a number of new options, some of them outsourced into various

+files in the /settings folder, so if you intend to use your old init file,

+you may still want to at least look through the new one.

diff --git a/crawl-ref/docs/key_changes.pdf b/crawl-ref/docs/key_changes.pdf
index c439fd607a..b0f14e2aa7 100644
--- a/crawl-ref/docs/key_changes.pdf
+++ b/crawl-ref/docs/key_changes.pdf
diff --git a/crawl-ref/docs/options_guide.txt b/crawl-ref/docs/options_guide.txt
index 421fdc9d90..041ec3f567 100644
--- a/crawl-ref/docs/options_guide.txt
+++ b/crawl-ref/docs/options_guide.txt
@@ -659,7 +659,7 @@ trap_item_brand = none
 
 level_map_cursor_step = 7
         How many squares the cursor moves on the level map when using 
-        Shift-direction or * direction.
+        Shift-direction.
 
 level_map_title = true
         Whether to show the level name at the top of the level map 
diff --git a/crawl-ref/source/acr.cc b/crawl-ref/source/acr.cc
index 2e7a26b559..92f6ba80ef 100644
--- a/crawl-ref/source/acr.cc
+++ b/crawl-ref/source/acr.cc
@@ -1168,7 +1168,8 @@ static void _handle_wizard_command( void )
 static void _start_running( int dir, int mode )
 {
     if (Options.tutorial_events[TUT_SHIFT_RUN] && mode == RMODE_START)
-        Options.tutorial_events[TUT_SHIFT_RUN] = 0;
+        Options.tutorial_events[TUT_SHIFT_RUN] = false;
+
     if (i_feel_safe(true))
         you.running.initialise(dir, mode);
 }
@@ -2266,7 +2267,8 @@ void process_command( command_type cmd )
 
     case CMD_DISPLAY_MAP:
         if (Options.tutorial_events[TUT_MAP_VIEW])
-            Options.tutorial_events[TUT_MAP_VIEW] = 0;
+            Options.tutorial_events[TUT_MAP_VIEW] = false;
+
 #if (!DEBUG_DIAGNOSTICS)
         if (!player_in_mappable_area())
         {
@@ -2909,7 +2911,7 @@ static void _decrement_durations()
     // For now, though, keep information about what happened hidden.
     if (you.duration[DUR_PIETY_POOL] && one_chance_in(5))
     {
-        you.duration[DUR_PIETY_POOL]--; // decrease even if piety at maximum
+        you.duration[DUR_PIETY_POOL]--; // Decrease even if piety at maximum.
         gain_piety(1);
 
 #if DEBUG_DIAGNOSTICS || DEBUG_SACRIFICE || DEBUG_PIETY
diff --git a/crawl-ref/source/beam.cc b/crawl-ref/source/beam.cc
index def9eea4b0..4726f60cc7 100644
--- a/crawl-ref/source/beam.cc
+++ b/crawl-ref/source/beam.cc
@@ -3987,7 +3987,8 @@ static int _affect_player( bolt &beam, item_def *item )
                 if (beam.beam_source == NON_MONSTER)
                 {
                     // Beam from player rebounded and hit player.
-                    xom_is_stimulated(255);
+                    if (!beam.aimed_at_feet)
+                        xom_is_stimulated(255);
                 }
                 else
                 {
@@ -4169,7 +4170,10 @@ static int _affect_player( bolt &beam, item_def *item )
             // Xom's amusement at the player's being damaged is handled
             // elsewhere.
             if (beam.beam_source == NON_MONSTER)
-                xom_is_stimulated(255);
+            {
+                if (!beam.aimed_at_feet)
+                    xom_is_stimulated(255);
+            }
             else if (was_affected)
                 xom_is_stimulated(128);
         }
diff --git a/crawl-ref/source/dat/database/help.txt b/crawl-ref/source/dat/database/help.txt
index 01f36ee211..1c03077767 100644
--- a/crawl-ref/source/dat/database/help.txt
+++ b/crawl-ref/source/dat/database/help.txt
@@ -63,10 +63,10 @@ level-map
 <h>Level Map ('<w>X</w><h>' in the main screen):
 <w>Esc</w>    : Leave level map (also <w>Space</w> or any unused key).
 <w>Dir.</w>   : Move the cursor.
-<w>/ Dir.</w> : Move the cursor in larger steps (also <w>Shift-Dir.</w>).
+<w>Shift-Dir.</w> : Move the cursor in larger steps (7 by default).
 <w>-</w>/<w>+</w>    : Scroll level map 20 grids up/down.
 <w>.</w>      : Start travel (also <w>Enter</w> and <w>,</w> and <w>;</w>).
-                (Moves cursor to the last travel destination if still on @.)
+         (Moves cursor to the last travel destination if still on @.)
 <w><<</w>/<w>></w>    : Cycle through up/down stairs.
 <w>^</w>      : Cycle through traps.
 <w>Tab</w>    : Cycle through shops and portals.
diff --git a/crawl-ref/source/dat/lab.des b/crawl-ref/source/dat/lab.des
index 4bd4f7a4d3..efc90b9b62 100644
--- a/crawl-ref/source/dat/lab.des
+++ b/crawl-ref/source/dat/lab.des
@@ -103,8 +103,8 @@ ENDMAP
 # Hidden exit, and trapped loot
 NAME:   labyrinth_hidden_loot
 TAGS:   minotaur generate_loot allow_dup
-MONS:   patrolling minotaur
-NSUBST: d = 1 / %
+MONS:   patrolling minotaur, minotaur zombie
+SUBST:  d = 2%
 SUBST:  c : cvv
 MAP
 ............
diff --git a/crawl-ref/source/fight.cc b/crawl-ref/source/fight.cc
index c0973cad93..38ae378f58 100644
--- a/crawl-ref/source/fight.cc
+++ b/crawl-ref/source/fight.cc
@@ -4083,18 +4083,13 @@ static bool wielded_weapon_check(const item_def *weapon)
                && (weapon->base_type != OBJ_WEAPONS || is_range_weapon(*weapon))
             || you.attribute[ATTR_WEAPON_SWAP_INTERRUPTED]))
     {
-        if (item_cursed(*weapon))
-        {
-            mpr("You might want to wield a more suitable implement when "
-                "attacking monsters.", MSGCH_WARN);
-        }
+        std::string prompt  = "Really attack while ";
+        if (!weapon)
+            prompt += "being unarmed?";
         else
-        {
-            std::string prompt  = "Really attack while wielding "
-                                  + weapon->name(DESC_NOCAP_YOUR) + "? ";
+            prompt += "wielding " + weapon->name(DESC_NOCAP_YOUR) + "? ";
 
-            result = yesno(prompt.c_str(), true, 'n');
-        }
+        result = yesno(prompt.c_str(), true, 'n');
 
         learned_something_new(TUT_WIELD_WEAPON); // for tutorial Rangers
 
diff --git a/crawl-ref/source/tutorial.cc b/crawl-ref/source/tutorial.cc
index 66beec0fa4..1507ade82a 100644
--- a/crawl-ref/source/tutorial.cc
+++ b/crawl-ref/source/tutorial.cc
@@ -73,7 +73,7 @@ void save_tutorial(writer& outf)
     marshallLong( outf, TUTORIAL_VERSION);
     marshallShort( outf, Options.tutorial_type);
     for (long i = 0; i < TUT_EVENTS_NUM; ++i)
-        marshallShort( outf, Options.tutorial_events[i] );
+        marshallBoolean( outf, Options.tutorial_events[i] );
 }
 
 void load_tutorial(reader& inf)
@@ -87,7 +87,7 @@ void load_tutorial(reader& inf)
     Options.tutorial_type = unmarshallShort(inf);
     for (long i = 0; i < TUT_EVENTS_NUM; ++i)
     {
-        Options.tutorial_events[i] = unmarshallShort(inf);
+        Options.tutorial_events[i] = unmarshallBoolean(inf);
         Options.tutorial_left += Options.tutorial_events[i];
     }
 }
@@ -150,6 +150,8 @@ bool pick_tutorial()
             you.char_class = _get_tutorial_job(Options.tutorial_type);
 
             // Activate all triggers.
+            // This is rather backwards: If (true) an event still needs to be
+            // triggered, if (false) the relevant message was already printed.
             Options.tutorial_events.init(true);
             Options.tutorial_left = TUT_EVENTS_NUM;
 
@@ -465,8 +467,10 @@ static formatted_string _tutorial_debug()
     result += "<lightblue>";
     for (i = 0; i < TUT_EVENTS_NUM; i++)
     {
-        snprintf(info, INFO_SIZE, "%d: %d (%s)",
-                 i, Options.tutorial_events[i], _tut_debug_list(i).c_str());
+        snprintf(info, INFO_SIZE, "%d: %s (%s)",
+                 i, _tut_debug_list(i).c_str(),
+                 Options.tutorial_events[i] ? "true" : "false");
+
         result += info;
 
         // Break text into 2 columns where possible.
@@ -1188,7 +1192,7 @@ void tutorial_first_monster(const monsters &mon)
 
     stop_running();
 
-    Options.tutorial_events[TUT_SEEN_MONSTER] = 0;
+    Options.tutorial_events[TUT_SEEN_MONSTER] = false;
     Options.tutorial_left--;
     Options.tut_just_triggered = true;
 
@@ -1308,7 +1312,7 @@ void tutorial_first_item(const item_def &item)
 
     stop_running();
 
-    Options.tutorial_events[TUT_SEEN_FIRST_OBJECT] = 0;
+    Options.tutorial_events[TUT_SEEN_FIRST_OBJECT] = false;
     Options.tutorial_left--;
     Options.tut_just_triggered = true;
 
@@ -1415,7 +1419,7 @@ static void _new_god_conduct()
 
 #define DELAY_EVENT \
 { \
-    Options.tutorial_events[seen_what] = 1; \
+    Options.tutorial_events[seen_what] = true; \
     Options.tutorial_left++; \
     return; \
 }
@@ -1444,7 +1448,7 @@ void learned_something_new(tutorial_event_type seen_what, int x, int y)
 #endif
 
     Options.tut_just_triggered = true;
-    Options.tutorial_events[seen_what] = 0;
+    Options.tutorial_events[seen_what] = false;
     Options.tutorial_left--;
 
     switch (seen_what)
@@ -2571,14 +2575,33 @@ void learned_something_new(tutorial_event_type seen_what, int x, int y)
     }
 
     case TUT_WIELD_WEAPON:
-        if (Options.tutorial_type == TUT_RANGER_CHAR
-            && you.inv[ you.equip[EQ_WEAPON] ].sub_type == WPN_BOW)
+    {
+        int wpn = you.equip[EQ_WEAPON];
+        if (wpn != -1
+            && you.inv[wpn].base_type == OBJ_WEAPONS
+            && item_cursed(you.inv[wpn]))
+        {
+            // Don't trigger if the wielded weapon is cursed.
+            Options.tutorial_events[seen_what] = true;
+            Options.tutorial_left++;
+            return;
+        }
+
+        if (Options.tutorial_type == TUT_RANGER_CHAR && wpn != -1
+            && you.inv[wpn].base_type == OBJ_WEAPONS
+            && you.inv[wpn].sub_type == WPN_BOW)
         {
             text << "You can easily switch between weapons in slots a and "
                     "b by pressing <w>'</w>.";
         }
+        else
+        {
+            text << "You can easily switch back to your weapon in slot a by "
+                    "pressing <w>'</w>. To change the slot of an item, type "
+                    "<w>=i</w> and choose the appropriate slots.";
+        }
         break;
-
+    }
     case TUT_FLEEING_MONSTER:
         if (Options.tutorial_type != TUT_BERSERK_CHAR)
             break;
@@ -2972,7 +2995,7 @@ void tutorial_describe_item(const item_def &item)
                      << "The rarer the description, the greater the potential "
                      << "value of an item.";
 
-                Options.tutorial_events[TUT_SEEN_RANDART] = 0;
+                Options.tutorial_events[TUT_SEEN_RANDART] = false;
             }
             if (item_known_cursed( item ) && !long_text)
             {
@@ -2984,9 +3007,9 @@ void tutorial_describe_item(const item_def &item)
                 if (!wielded && is_throwable(item, you.body_size()))
                     ostr << " (Throwing it is safe, though.)";
 
-                Options.tutorial_events[TUT_YOU_CURSED] = 0;
+                Options.tutorial_events[TUT_YOU_CURSED] = false;
             }
-            Options.tutorial_events[TUT_SEEN_WEAPON] = 0;
+            Options.tutorial_events[TUT_SEEN_WEAPON] = false;
             break;
        }
        case OBJ_MISSILES:
@@ -3015,7 +3038,7 @@ void tutorial_describe_item(const item_def &item)
                      << ", first you need to <w>w</w>ield an appropriate "
                         "launcher.";
             }
-            Options.tutorial_events[TUT_SEEN_MISSILES] = 0;
+            Options.tutorial_events[TUT_SEEN_MISSILES] = false;
             break;
 
        case OBJ_ARMOUR:
@@ -3072,7 +3095,7 @@ void tutorial_describe_item(const item_def &item)
                      << "The rarer the description, the greater the potential "
                      << "value of an item.";
 
-                Options.tutorial_events[TUT_SEEN_RANDART] = 0;
+                Options.tutorial_events[TUT_SEEN_RANDART] = false;
             }
             if (wearable)
             {
@@ -3101,7 +3124,7 @@ void tutorial_describe_item(const item_def &item)
                     ostr << _tut_abilities();
                 }
             }
-            Options.tutorial_events[TUT_SEEN_ARMOUR] = 0;
+            Options.tutorial_events[TUT_SEEN_ARMOUR] = false;
             break;
        }
        case OBJ_WANDS:
@@ -3109,7 +3132,7 @@ void tutorial_describe_item(const item_def &item)
 #ifdef USE_TILE
             ostr << " Alternatively, simply click on its tile.";
 #endif
-            Options.tutorial_events[TUT_SEEN_WAND] = 0;
+            Options.tutorial_events[TUT_SEEN_WAND] = false;
             break;
 
        case OBJ_FOOD:
@@ -3129,7 +3152,7 @@ void tutorial_describe_item(const item_def &item)
                             "you're probably not part of that group.";
                 }
             }
-            Options.tutorial_events[TUT_SEEN_FOOD] = 0;
+            Options.tutorial_events[TUT_SEEN_FOOD] = false;
             break;
 
        case OBJ_SCROLLS:
@@ -3139,7 +3162,7 @@ void tutorial_describe_item(const item_def &item)
 #endif
                     ".";
 
-            Options.tutorial_events[TUT_SEEN_SCROLL] = 0;
+            Options.tutorial_events[TUT_SEEN_SCROLL] = false;
             break;
 
        case OBJ_JEWELLERY:
@@ -3178,7 +3201,7 @@ void tutorial_describe_item(const item_def &item)
                         "one) offer certain abilities you can activate. ";
                 ostr << _tut_abilities();
             }
-            Options.tutorial_events[TUT_SEEN_JEWELLERY] = 0;
+            Options.tutorial_events[TUT_SEEN_JEWELLERY] = false;
             break;
        }
        case OBJ_POTIONS:
@@ -3187,7 +3210,7 @@ void tutorial_describe_item(const item_def &item)
                     "or simply click on it with your <w>left mouse button</w>"
 #endif
                     ".";
-            Options.tutorial_events[TUT_SEEN_POTION] = 0;
+            Options.tutorial_events[TUT_SEEN_POTION] = false;
             break;
 
        case OBJ_BOOKS:
@@ -3269,7 +3292,7 @@ void tutorial_describe_item(const item_def &item)
                 }
             }
             ostr << "\n";
-            Options.tutorial_events[TUT_SEEN_SPBOOK] = 0;
+            Options.tutorial_events[TUT_SEEN_SPBOOK] = false;
             break;
 
        case OBJ_CORPSES:
@@ -3312,7 +3335,7 @@ void tutorial_describe_item(const item_def &item)
                         "valid synonym for <w>y</w>es or you can directly chop "
                         "<w>a</w>ll corpses.";
             }
-            Options.tutorial_events[TUT_SEEN_CARRION] = 0;
+            Options.tutorial_events[TUT_SEEN_CARRION] = false;
             break;
 
        case OBJ_STAVES:
@@ -3374,7 +3397,7 @@ void tutorial_describe_item(const item_def &item)
                             "<w>d</w>rop it now.";
                 }
             }
-            Options.tutorial_events[TUT_SEEN_STAFF] = 0;
+            Options.tutorial_events[TUT_SEEN_STAFF] = false;
             break;
 
        case OBJ_MISCELLANY:
@@ -3385,7 +3408,7 @@ void tutorial_describe_item(const item_def &item)
 #endif
                     ".";
 
-            Options.tutorial_events[TUT_SEEN_MISC] = 0;
+            Options.tutorial_events[TUT_SEEN_MISC] = false;
             break;
 
        default:
@@ -3520,7 +3543,7 @@ void tutorial_describe_feature(dungeon_feature_type feat)
                         "mechanical traps you can't avoid tripping them "
                         "by levitating or flying over them.";
             }
-            Options.tutorial_events[TUT_SEEN_TRAP] = 0;
+            Options.tutorial_events[TUT_SEEN_TRAP] = false;
             break;
 
        case DNGN_TRAP_NATURAL: // only shafts for now
@@ -3528,7 +3551,7 @@ void tutorial_describe_feature(dungeon_feature_type feat)
                     "as shafts, which lead one to three levels down. They "
                     "can't be disarmed, but you can safely pass over them "
                     "if you're levitating or flying.";
-            Options.tutorial_events[TUT_SEEN_TRAP] = 0;
+            Options.tutorial_events[TUT_SEEN_TRAP] = false;
             break;
 
        case DNGN_STONE_STAIRS_DOWN_I:
@@ -3542,7 +3565,7 @@ void tutorial_describe_feature(dungeon_feature_type feat)
                     "by clicking the <w>left mouse button</w> while pressing "
                     "<w>Shift</w>. ";
 #endif
-            Options.tutorial_events[TUT_SEEN_STAIRS] = 0;
+            Options.tutorial_events[TUT_SEEN_STAIRS] = false;
             break;
 
        case DNGN_STONE_STAIRS_UP_I:
@@ -3570,7 +3593,7 @@ void tutorial_describe_feature(dungeon_feature_type feat)
                         "<w>Shift</w> instead. ";
 #endif
             }
-            Options.tutorial_events[TUT_SEEN_STAIRS] = 0;
+            Options.tutorial_events[TUT_SEEN_STAIRS] = false;
             break;
 
        case DNGN_ESCAPE_HATCH_DOWN:
@@ -3579,7 +3602,7 @@ void tutorial_describe_feature(dungeon_feature_type feat)
                     "<w><<</w> and <w>></w>, respectively. Note that you will "
                     "usually be unable to return right away.";
 
-            Options.tutorial_events[TUT_SEEN_ESCAPE_HATCH] = 0;
+            Options.tutorial_events[TUT_SEEN_ESCAPE_HATCH] = false;
             break;
 
        default:
@@ -3636,7 +3659,7 @@ void tutorial_describe_feature(dungeon_feature_type feat)
 #endif
                             ".";
                 }
-                Options.tutorial_events[TUT_SEEN_ALTAR] = 0;
+                Options.tutorial_events[TUT_SEEN_ALTAR] = false;
                 break;
             }
             else if (feat >= DNGN_ENTER_FIRST_BRANCH
diff --git a/crawl-ref/source/util/docs/README.tex b/crawl-ref/source/util/docs/README.tex
index fbe7b286c9..3654108a16 100644
--- a/crawl-ref/source/util/docs/README.tex
+++ b/crawl-ref/source/util/docs/README.tex
@@ -9,8 +9,10 @@
 \newcommand{\key}[1]{{{\texttt{\textbf{#1}}}}} % this does nasty things to underscores
 \newcommand{\sex}[1]{{{\textbf{#1}}}} % \sec already defined
 
+
 \newcommand{\crawl}{\textsc{Crawl}}
 \newcommand{\dungeon}{\textsc{Dungeon}}
+\newcommand{\soup}{\textsc{Stone Soup}}
 
 \newcommand{\spacecolumn}{\begin{minipage}[t]{2cm}\phantom{xxxx}\end{minipage}}
 \newcommand{\para}{\vspace{1.5ex}}
@@ -38,33 +40,57 @@
 
 
 \begin{center}\textbf{\LARGE
-\dungeon\ \crawl: Files and Contact
+\dungeon\ \crawl: Introduction, Files  and Contact
 }\end{center}
 
 This is the reference sheet for the roguelike game \dungeon\ \crawl,
-specifically for the current version of the \textsc{Stone Soup} branch. 
-\crawl\ is a game of dungeon exploration, fighting and magic that is
-renowned for its intricate skills and religion systems. Success requires
-tactics, strategy, and perseverance. Though \crawl's reputation is 
-close to devilish, victories were reported\dots
+specifically for the current version of the \soup\ branch. 
+\crawl\ is a game of dungeon exploration, combat and magic, involving
+characters of diverse skills, worshipping deities of great power and
+caprice. To win, you'll need to be a master of tactics and strategy,
+and prevail against overwhelming odds.
 
 \para
 
-This page explains the various important files. The next page lists a 
-number of important changes introduced in version 0.4. The last two 
-pages give a very brief introduction to the game, which should be 
-enough to get you started. If you are completely new to this type of 
-game and still want to plunge right in, start up a new game and select 
-a tutorial (press \key{T} when asked for a species).
+Players of versions 0.3.4 and older beware: please read the file 
+\key{034\_changes.pdf} in the \key{docs} directory for a list of
+interface changes, and how you could possibly retrieve the 0.3.4
+standards.
 
-\para\para
+\subsection*{How to get started? (Information for new players)}
 
-\sex{The most important files}
+If you'd like to dive in immediately, your best bets are to either
+start up a game and choose one of the tutorials (press \key{T} when 
+asked for race), or print \key{quickstart.pdf} (in the \key{docs} 
+directory). Studious readers might want to browse the manual  (see 
+below). Note that you can read both the quickstart text and the
+manual in-game; pressing \key{?} brings up a menu for that.
 
 \para
 
+\sex{Internet play}
+
+You can play \crawl\ online, both competing with other players and watching 
+them. Check the homepage \key{crawl.akrasiac.org} for details, including 
+information about additional servers. You just need a \texttt{ssh} or 
+\texttt{telnet} console; on Windows, the \key{PuTTY} program works very 
+well. Read \key{ssh\_guide.txt} in the \key{docs} folder for a step by step 
+guide on how to set this up.
+
+\para 
+
+\sex{Tiles}
+
+\crawl\ features an alternative to the classical ASCII display; Tile-based
+Crawl is often a lot more accessible by new players. Tiles are available for 
+Linux, Windows and OS X.
+Unfortunately, it is not yet possible to combine tiles and internet play.
+
+\subsection*{The most important files}
+
 \begin{minipage}[t]{7cm}
-The file \key{crawl.exe} in \crawl's main folder starts the game.
+The file \key{crawl.exe} (just \key{crawl} if on Unix) in \crawl's main 
+folder starts the game.
 \\ \\
 The \sex{settings/} directory contains \key{init.txt}, the options file for
 \crawl\ (on linux systems there may also be a \key{.crawlrc} in your home
@@ -80,12 +106,12 @@ spent some time playing the game.
 \spacecolumn
 %
 \begin{minipage}[t]{7cm}
-The following files in the \sex{docs/} directory may be helpful:
+The following files in the \sex{docs/} directory may be helpful, all of
+which can be read in-game (press \key{?}):
 \\
 \key{crawl\_manual.txt} is the full manual. It explains all races, classes, 
 item types etc. If you do not delight in manuals, you can put off the 
-reading this file until later. You can browse the manual while playing 
-(press \key{?}).
+reading this file until later.
 \\
 \key{options\_guide.txt} describes all the options in minute detail. While
 tweaking these can improve your \crawl\ experience, you will probably prefer
@@ -97,50 +123,109 @@ ignore this at first, too.
  % look at the keymaps section.)
 \end{minipage}
 
-\para\para
-
-\sex{Contact}
-
-\para
+\subsection*{Contact}
 	    
 If you have questions concerning the game, or think you have found a bug, 
-there are several places to contact the developers. First, there is the 
-newsgroup \key{rec.games.roguelike.misc}. Since other games are 
-discussed there as well, it is polite to flag your post with \key{-crawl-}.
-If you are not familiar with Usenet netiquette, you might want to check 
-that first, too.
-Also try to maintain netiquette to the benefit of your addresses.
-\\
-Next, you are encouraged to file bug reports and feature requests on the 
+there are several places to contact the developers. 
+
+First, you are encouraged to file bug reports and feature requests on the 
 \crawl\ homepage at \key{http://crawl-ref.sourceforge.net}. From there, you 
 can also download the most recent version (both binaries or source, for 
 Unix, Windows, OS X, and DOS).
 \\
+Next, there is the newsgroup \key{rec.games.roguelike.misc}. Since other 
+games are discussed there as well, it is polite to flag your post with 
+\key{-crawl-}. If you are not familiar with Usenet netiquette, you might 
+want to check that first, too. Also try to maintain netiquette to the 
+benefit of your addresses.
+\\
 Finally, you can use the mailing list 
 \key{crawl-ref-discuss@lists.sourceforge.net}
 to discuss specific details of the game's design and implementation.
 
-\para \para
+\subsection*{License and history information}
 
-\sex{Internet play}
+What you have downloaded is a descendant of Linley's \dungeon\ \crawl. 
+Development of the main branch stalled at version 4.0.0b26, with a final 
+alpha of 4.1 being released by Brent Ross in 2005. Since 2006, the 
+\dungeon \crawl\ \soup\ team has been continuing the 
+development. See the \key{CREDITS} in the main folder for a myriad of 
+contributors, past and present; \key{license.txt} contains the legal blurb.
+
+\dungeon\ \crawl\ \soup\ is an open source, freeware roguelike. It is 
+supported on Linux, Windows, OS/X  and, to a lesser extent, on DOS. The 
+source should compile and run on any reasonably modern Unix. \soup\ 
+features both ASCII and graphical (Tiles) display.
+
+\crawl\ gladly and gratuitously uses the following open-source packages: \\
+The \textbf{Lua} script language, see \key{docs/lualicense.txt}.\\
+The \textbf{PCRE} library for regular expressions, see 
+    \key{docs/pcre\_license.txt}.\\
+The \textbf{Mersenne Twister} for random number generation, 
+    \key{docs/mt19937.txt}.\\
+The \textbf{SQLite} library as database engine; it is properly public domain.\\
+The \textbf{ReST} light markup language for the documentation.
+
+\subsection*{How you can help}
+
+If you like the game and you want to help making it better, there are a number 
+of ways to do so:
 
 \para
 
-You can play \crawl\ online, both competing with other players and watching 
-them. Check the homepage \key{crawl.akrasiac.org} for details, including 
-information about additional servers. You just need a \texttt{ssh} or 
-\texttt{telnet} console; on Windows, the \texttt{PuTTY} program works very 
-well. Read \key{ssh\_guide.txt} in the \key{docs} folder for a step by step 
-guide on how to set this up.
+\textbf{Playtesting:}
+At any time, there will be bugs --- playing and reporting these is a great 
+help. There is a beta server around hosting the most recent version of the 
+current code; the akrasiac page links to it. Besides finding bugs, ideas on 
+how to improve interface or gameplay are welcome as well.
 
-\para \para
+\para
 
-\sex{Tiles}
+\textbf{Vault making:}
+Crawl uses many hand-drawn (but often randomised) maps. Making them is fun 
+and easy. It's best to start with simple entry vaults (glance through 
+\key{dat/entry.des} for a first impression). Later, you may want to read 
+\key{docs/level\_design.txt} for the full power. If you're ambitious, new 
+maps for branch ends are possible, as well.
+If you've made some maps, you can test them on your system (no compiling 
+needed) and then just mail them to the mailing list.
 
 \para
 
-\crawl\ features an alternative to the classical ASCII display; Tile-based
-Crawl is often a lot more accessible by new players. Tiles are available for 
-Linux, Windows and OS X.
-Unfortunately, it is not yet possible to combine tiles and internet play.
+\textbf{Speech:}
+Monster talking provides a lot of flavour. Just like vaults, speech depends 
+upon a large set of entries. Since most of the speech has been outsourced, 
+you can add new prose. The syntax is effective, but slightly strange, so you 
+may want to read \key{docs/monster\_speech.txt}.
+Again, changing or adding speech is possible on your local game. If you 
+have added something, send the files to the list.
+
+\para
+
+\textbf{Monster descriptions:}
+You can look up the current monster descriptions in-game with \key{?/} or 
+just read them in \key{dat/descript/monsters.txt}. The following conventions 
+should be more or less obeyed: descriptions ought to contain flavour text, 
+ideally pointing out major weaknesses/strengths. No numbers, please. 
+Citations are okay, but try to stay away from the most generic ones.
+If you like, you can similarly modify the descriptions for features, items or
+branches.
+
+\para
+
+\textbf{Tiles:}
+Since version 0.4, tiles are integrated within \crawl. Having variants of 
+often-used glyphs is always good. If you want to give this a shot, please 
+contact us via the mailing list.
+
+\para
+
+\textbf{Patches:}
+If you like to, you can download the source code and apply patches. Both 
+patches for bug fixes as well as implementation of new features are very 
+much welcome. Please be sure to read \key{docs/coding\_conventions.txt} first.
+
+\para\para\para
+
+Thank you, and have fun crawling!
 \end{document}
diff --git a/crawl-ref/source/util/docs/key_changes.txt b/crawl-ref/source/util/docs/key_changes.tex
index b19b9c6928..1d791d724d 100644
--- a/crawl-ref/source/util/docs/key_changes.txt
+++ b/crawl-ref/source/util/docs/key_changes.tex
@@ -6,7 +6,7 @@
 
 \usepackage{graphicx}
 
-\newcommand{\key}[1]{{{\texttt{\textbf{#1}}}}} % this does nasty things to underscores
+\newcommand{\key}[1]{{\texttt{#1}}} % this does nasty things to underscores
 \newcommand{\sex}[1]{{{\textbf{#1}}}} % \sec already defined
 
 \newcommand{\crawl}{\textsc{Crawl}}
@@ -45,7 +45,7 @@ a small number of new commands were introduced. The tables below list all
 of these. If you have been playing an older version and want to restore 
 the old key set, do so by adding this line to the 
 \texttt{init.txt} file: \\
-\texttt{additional\_macro\_file = 034\_command\_keys.txt} 
+\verb$additional_macro_file = 034_command_keys.txt$ 
 
 \para
 
@@ -108,4 +108,32 @@ Quivering is done via \key{Q} (quiver the currently fired item) or
 \key{fi} (choose an item and quiver it) or also by using \key{(} (cycling 
 appropriate ammunition) and then firing. \key{F} also lets you select an 
 item to be thrown, but this command does not affect the quiver.
+
+\newpage
+
+The colours of many monsters have been changed. Most notably, there are
+no darkgrey monsters anymore. In case darkgrey is actually better visible 
+than blue on your system, you can swap these colours using the line \\
+\verb#   colour: darkblue = darkgrey #\\
+in \key{init.txt}. Apart from that, more dangerous monsters are now 
+generally displayed in lighter colours.
+
+\para
+
+We are content that all of these changes are genuine improvements. Should
+your brain be hardwired to the old settings, you can effectively enforce
+the 0.3.4 state by using the following options:
+\begin{verbatim}
+   include                 = 034_monster_glyphs.txt
+   additional_macro_file   = 034_command_keys.txt
+   always_confirm_butcher  = true
+\end{verbatim}
+
+Note that the header of \key{init.txt} contains these lines. (It contains 
+some more options for using other old settings.) The options are commented 
+out, so you just need to remove the \key{\#} in front in order to activate 
+them. You can choose to use only part of these options. In case you decide 
+to use the old keyset, be aware that \key{D} and \key{d} are synonyms for 
+'yes' in the butcher interface.
+
 \end{document}