Update README files (courtesy of David), some minor tutorial

corrections, and make Xom ignore your attempts to amuse him by
deliberately casting spells at yourself. (Rebounding lightning bolts
will still amuse him.)


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

7 files changed, 223 insertions, 122 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/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/fight.cc b/crawl-ref/source/fight.cc
index bb1d18b778..f5821ebb84 100644
--- a/crawl-ref/source/fight.cc
+++ b/crawl-ref/source/fight.cc
@@ -4082,18 +4082,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}