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

8 files changed, 235 insertions, 98 deletions

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}