Moved readme.txt to docs/quickstart.txt and updated it.

Removed README.stone_soup.txt and replaces it be readme.txt.
Note that ?^ (in-game reading of the old readme.txt) will
now show a completely different file. We may want to allow
both reading of readme.txt and docs/quickstart.txt.


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

3 files changed, 307 insertions, 220 deletions

diff --git a/crawl-ref/README.stone_soup.txt b/crawl-ref/README.stone_soup.txt
deleted file mode 100644
index 12de01c754..0000000000
--- a/crawl-ref/README.stone_soup.txt
+++ /dev/null
@@ -1,72 +0,0 @@
-Dungeon Crawl (Stone Soup)
-------- ----- ------ -----
-
-(If you'd like to dive in and start playing Crawl right away, see readme.txt.)
-
-What you have downloaded is *not* Linley's Dungeon Crawl. It's a parallel
-effort, currently not quite a fork.
-
-The goal of this version is to provide a stable base platform for further
-Crawl development during times when Dungeon Crawl's main maintainer is not
-available, and to collect experiments, patches, and ideas from the community
-of Dungeon Crawl players.
-
-Stone Soup is based on Dungeon Crawl 4.0.0 beta26, with additional changes
-gathered from Brent Ross's 4.1.2 alpha release. It incorporates several
-popular community patches and assorted local changes and improvements.
-
-Please do not send bug reports for this code to the main Dungeon Crawl
-maintainers -- the odds are good that the code that's causing you problems
-isn't code they wrote, and they won't be able to help you.
-
------------------------------------------------------------------------------
-
-Dungeon Crawl Stone Soup 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.
-
-The following files in your main Crawl directory are crucial:
-
-crawl     - Starts the game.
-crawl.exe
-
-init.txt  - These files (which one depends on your OS) contains the options of 
-.crawlrc    Crawl. Since the defaults are well suited for playing, don't bother 
-	    with this in the beginning.
-	    Note that 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. It is recommended that you fiddle with these 
-	    only after a couple of games.
-
-The docs directory contains the following helpful files:
-
-crawl_manual.txt - This is the complete manual; describing all species, classes,
-            types of items, etc.
-crawl_options.txt - Here all the options you can give Crawl are described in
-            detail; feel free to skip this until you feel comfortable with the 
-            game.
-crawl_macros.txt - It is wise to ignore this at first, too. (Unless you
-	    experience serious problems with some keys, in which case you may 
-	    want to have a look at the keymaps section.) 
-	    Just remember for later that you can improve your Crawl experience 
-	    by adjusting interface options and defining your own macros.
-tables.txt - Unlike some other roguelike games, winning in Crawl does not
-            require an exhaustive knowledge of the game's internals. However,
-            here are tables which may be interesting to players. The central
-            information therein can be deduced from other sources (like the 
-            manual), and it is perfectly possible to win without knowing 
-            these numbers.
-
-If you have questions concerning the game, or have found a bug, do not hesitate
-to inquire at the newsgroup
-	rec.games.roguelike.misc 
-with your problem. Since other games are discussed over there as well, it is 
-polite to flag your post with -crawl-. Please read the group for a while before
-posting to get a feel for the right way to post articles about Crawl.
-
-Stone Soup's homepage is
-	http://crawl-ref.sourceforge.net
-Look here for downloads of the most recent version (source and binaries).
-Stone Soup is supported on Linux, Windows, OS/X, and DOS, and will probably
-compile and run on any reasonably modern Unix.
diff --git a/crawl-ref/docs/quickstart.txt b/crawl-ref/docs/quickstart.txt
new file mode 100644
index 0000000000..824a2c7851
--- /dev/null
+++ b/crawl-ref/docs/quickstart.txt
@@ -0,0 +1,152 @@
+                            Crawl Quick-Start Guide
+                        (Copyright 1999 Linley Henzell)
+
+So, you want to start playing Crawl straight away without bothering with the 
+manual? Read this, the guide to starting Crawl with a minimum of preparation. 
+When you get some more time, you can read crawl_manual.txt in the Docs 
+directory for more detailed information.
+
+I suggest printing it out and following its instructions while playing your 
+first few games (you can also press '?' while playing for a list of commands). 
+
+ INTRODUCTION TO CRAWL 
+
+Crawl is a large and very random game of subterranean exploration in a fantasy 
+world of magic and frequent violence. Your quest is to travel into the depths 
+of the Dungeon (which is different each time you play) and retrieve the Orb of 
+Zot. 
+
+Crawl is an RPG of the 'rogue-like' type, one of the descendants of Rogue. Its 
+graphics are simple but highly informative, designed to be understood at a 
+glance, and control is exercised largely through one-keystroke commands. 
+
+ STARTING OUT 
+
+After starting the program you will be greeted with a message asking for your 
+name. Don't spend too much time over this, as your first character will *not* 
+last very long (sorry, but it's true). 
+
+Next you are given menus of species and character classes from which to 
+choose. A dwarf, orc, ogre or troll Fighter is a good bet. Elves are quite 
+fragile, humans are pretty average at everything, and the weirder species are 
+mostly too tricky for beginning players. Finally, you may be given a choice of 
+weapons. I suggest an axe (axes are fun). 
+
+Now you are in the game. The game screen has three parts:
+ - the Map takes up the upper left part of the screen. In its very centre is 
+   the @ sign which represents You. The coloured parts of the Map are the parts 
+   you can see, while places which you have visited before but cannot currently 
+   see are shown in grey.
+ - the Message box is the large part of the screen below the map. It describes 
+   events as they happen and asks you questions from time to time. 
+ - the Stats area (to the right of the Map) contains various indicators of 
+   your health and abilities. 
+
+ EXPLORING 
+
+Try walking around, using either the numeric keypad (try numlock off and on) or 
+the Rogue (hjklyubn) keys. To move in a given direction until you reach 
+something interesting or see a hostile creature, press shift and the direction. 
+
+If you want to know what a certain character on the screen represents, you can 
+use the 'x' (examine) command to get a short description. You use the 'O', 'C' 
+commands to open or close doors, and the '<' (up) and '>' (down) commands to 
+climb staircases. Sometimes doors are hidden, and must be searched out by 
+standing next to walls and resting (a number of commands do the same thing: 
+'s', '.' (period), delete, or '5' on the numeric keypad; even better you rest 
+or search for a longer duration with either '5' on the digit row or Shift-5 on 
+the numeric keypad). 
+
+The Dungeon gets more dangerous (but more interesting!) as you go down. If you 
+get lost you can access a map of the whole level you are on with the 'X' 
+command, which uses the whole screen. 
+
+ ITEMS 
+
+After walking around for a while, you will no doubt come across some items 
+laying around (you may come across some monsters as well; for help in dealing 
+with them skip to the Monsters section). You can pick up items with the 'g' 
+(get) or ',' commands and drop them again with 'd' (drop), and the 'i' 
+(inventory) command shows you what you're carrying. 
+
+There are several different types of items: 
+
+ - Weapons, represented by the ) sign. Wield them with the 'w' (wield) 
+command. Some weapons are cursed and cannot be un-wielded without the use of 
+magic.
+
+ - Armour ([). Wear it, or take it off, with the 'W' (Wear) command. Heavier 
+ armours give more protection, but may hamper your ability to fight and to 
+ dodge attacks aimed at you. These can also be cursed.
+
+ - Ammunition (which has the ( sign). Throw it with 'f' (fire). Darts are 
+meant to be thrown by hand; other missiles need an appropriate launcher to be 
+wielded (eg arrows are much more effective when shot with a bow).
+
+ - Wands (/), Scrolls (?) and Potions (!) can be very valuable, but have 
+limited uses (scrolls and potions can only be used once each, wands contain 
+only a certain number of charges). Wands are 'Z'apped, scrolls are 'r'ead and 
+potions are 'q'uaffed.
+ Unfortunately, you won't at first know what a wand, scroll or potion does; it 
+will only be described by its physical appearance. But once you have used, for 
+example, a potion of healing, you will in future recognise all potions of 
+healing. 
+
+ - Rings (=) and Amulets (") often contain powerful magic, but it can be 
+difficult to work out exactly what one does. They are put on with 'P' (put on) 
+and can be removed with the same command, or also with 'R'. They can, like 
+weapons, be cursed. 
+
+ - Food (%) is vital to your survival. Eat it with the 'e' (eat) command when 
+hungry. Monsters' corpses, also %, can be eaten if chopped up (the 'c' ommand),
+but not all of them are healthful, and many species of player-character dislike
+eating raw flesh unless very hungry. 
+
+ - Money ($) can be used to buy stuff in shops, and increases your score if 
+you escape. 
+
+There are a few other types of items, but you will discover these as you play. 
+
+One vital command to remember when dealing with items is examing items more
+closely. In order to do so, bring up the inventory ('i') and press the key of
+any item therein. This gives you a short description of any item. Use it on 
+everything you find. The magical Scroll of Identify can also help for 
+identifying magical items of uncertain nature. 
+
+ MONSTERS 
+
+You will also run into monsters (most of which are represented by letters of 
+the alphabet). You can attack a monster by trying to move into the square it 
+is occupying. 
+
+When you are wounded you lose hit points (displayed near the top of the stats 
+list); these return gradually over time through the natural process of 
+healing. If you lose all of your hp you die. 
+
+To survive, you will need to develop a few basic tactics:
+ - Never fight more than one monster if you can help it. Always back into a 
+   corridor so that they must fight you one-on-one. 
+ - If you are badly wounded, you can run away from monsters to buy some time. 
+   Try losing them in corridors, or as a very last resort find a place where 
+   you can run around in circles to heal while the monster chases you. 
+ - Remember to use projectiles before engaging monsters in close combat.
+ - Rest between encounters. The 's', '.', delete or keypad-5 commands make you 
+   rest for one turn, while pressing '5' or shift-and-keypad-5 make you rest 
+   for a longer time (you will stop resting when fully healed). 
+ - Learn when to run away from things you can't handle - this is important! 
+   It is often wise to skip a dangerous level. But don't overdo this.
+
+ DEATH 
+
+Before long, you'll probably end up dead. 
+ 
+Death in Crawl is permanent; you cannot just reload a saved game and start again
+where you left off. The 'S' (save) command exists only to let you leave a game 
+part-way through and come back to it later. Quitting ('Q') lets you commit
+suicide if you can't even be bothered to help your character escape alive. 
+
+Well, that's it for the quick-start guide. This should help you through your 
+first few games, but Crawl is extremely (some would say excessively) complex 
+and cannot be adequately described in so short a document. So when you feel 
+ready to start playing with magic, skills, and religions, browse the manual.
+Happy Crawling! 
diff --git a/crawl-ref/readme.txt b/crawl-ref/readme.txt
index 57f7f80161..fc6313b6b7 100644
--- a/crawl-ref/readme.txt
+++ b/crawl-ref/readme.txt
@@ -1,148 +1,155 @@
-                            Crawl Quick-Start Guide
-                        (Copyright 1999 Linley Henzell)
-
-So, you want to start playing Crawl straight away without bothering with the 
-manual? Read this, the guide to starting Crawl with a minimum of preparation. 
-When you get some more time, you can read crawl_manual.txt in the Docs 
-directory for more detailed information.
-
-I suggest printing it out and following its instructions while playing your 
-first few games (you can also press '?' while playing for a list of commands). 
-
- INTRODUCTION TO CRAWL 
-
-Crawl is a large and very random game of subterranean exploration in a fantasy 
-world of magic and frequent violence. Your quest is to travel into the depths 
-of the Dungeon (which is different each time you play) and retrieve the Orb of 
-Zot. 
-
-Crawl is an RPG of the 'rogue-like' type, one of the descendants of Rogue. Its 
-graphics are simple but highly informative, designed to be understood at a 
-glance, and control is exercised largely through one-keystroke commands. 
-
- STARTING OUT 
-
-After starting the program you will be greeted with a message asking for your 
-name. Don't spend too much time over this, as your first character will *not* 
-last very long (sorry, but it's true). 
-
-Next you are given menus of species and character classes from which to 
-choose. A dwarf, orc, ogre or troll Fighter is a good bet. Elves are quite 
-fragile, humans are pretty average at everything, and the weirder species are 
-mostly too tricky for beginning players. Finally, you may be given a choice of 
-weapons. I suggest an axe (axes are fun). 
-
-Now you are in the game. The game screen has three parts:
- - the Map takes up the upper left part of the screen. In its very centre is 
-   the @ sign which represents You. The coloured parts of the Map are the parts 
-   you can see, while places which you have visited before but cannot currently 
-   see are shown in grey.
- - the Message box is the large part of the screen below the map. It describes 
-   events as they happen and asks you questions from time to time. 
- - the Stats area (to the right of the Map) contains various indicators of 
-   your health and abilities. 
-
- EXPLORING 
-
-Try walking around, using either the numeric keypad (try numlock off and on) or 
-the Rogue (hjklyubn) keys. To move in a given direction until you reach 
-something interesting or see a hostile creature, press shift and the direction. 
-
-If you want to know what a certain character on the screen represents, you can 
-use the 'x' (examine) command to get a short description. You use the 'o', 'c' 
-commands to open or close doors, and the '<' (up) and '>' (down) commands to 
-climb staircases. Sometimes doors are hidden, and must be searched out by 
-standing next to walls and resting (a number of commands do the same thing: 
-'s', '.' (period), delete, or '5' on the numeric keypad). 
-
-The Dungeon gets more dangerous (but more interesting!) as you go down. If you 
-get lost you can access a map of the whole level you are on with the 'X' 
-command, which uses the whole screen. 
-
- ITEMS 
-
-After walking around for a while, you will no doubt come across some items 
-laying around (you may come across some monsters as well; for help in dealing 
-with them skip to the Monsters section). You can pick up items with the 'g' 
-(get) or ',' commands and drop them again with 'd' (drop), and the 'i' 
-(inventory) command shows you what you're carrying. 
-
-There are several different types of items: 
-
- - Weapons, represented by the ) sign. Wield them with the 'w' (wield) 
-command. Some weapons are cursed and cannot be un-wielded without the use of 
-magic.
-
- - Armour ([). Wear it with the 'W' (Wear) command, and remove it with 'T' 
-(Take off). Heavier armours give more protection, but may hamper your ability 
-to fight and to dodge attacks aimed at you. These can also be cursed.
-
- - Ammunition (which has the ( sign). Throw it with 't' (throw). Darts are 
-meant to be thrown by hand; other missiles need an appropriate launcher to be 
-wielded (eg arrows are much more effective when shot with a bow).
-
- - Wands (/), Scrolls (?) and Potions (!) can be very valuable, but have 
-limited uses (scrolls and potions can only be used once each, wands contain 
-only a certain number of charges). Wands are 'z'apped, scrolls are 'r'ead and 
-potions are 'q'uaffed.
- Unfortunately, you won't at first know what a wand, scroll or potion does; it 
-will only be described by its physical appearance. But once you have used, for 
-example, a potion of healing, you will in future recognise all potions of 
-healing. 
-
- - Rings (=) and Amulets (") often contain powerful magic, but it can be 
-difficult to work out exactly what one does. They are put on with 'P' (put on) 
-and removed with 'R' (remove), but can, like weapons, be cursed. 
-
- - Food (%) is vital to your survival. Eat it with the 'e' (eat) command when 
-hungry. Monsters' corpses, also %, can be eaten if chopped up (the 'D' 
-(Dissect) command), but not all of them are healthful, and many species of 
-player-character dislike eating raw flesh unless very hungry. 
-
- - Money ($) can be used to buy stuff in shops, and increases your score if 
-you escape. 
-
-There are a few other types of items, but you will discover these as you play. 
-
-One vital command to remember when dealing with items is 'v' (View), which 
-gives you a short description of any item. Use it on everything you find. The 
-magical Scroll of Identify can also help for identifying magical items of 
-uncertain nature. 
-
- MONSTERS 
-
-You will also run into monsters (most of which are represented by letters of 
-the alphabet). You can attack a monster by trying to move into the square it 
-is occupying. 
-
-When you are wounded you lose hit points (displayed near the top of the stats 
-list); these return gradually over time through the natural process of 
-healing. If you lose all of your hp you die. 
-
-To survive, you will need to develop a few basic tactics:
- - Never fight more than one monster if you can help it. Always back into a 
-   corridor so that they must fight you one-on-one. 
- - If you are badly wounded, you can run away from monsters to buy some time. 
-   Try losing them in corridors, or as a very last resort find a place where 
-   you can run around in circles to heal while the monster chases you. 
- - Remember to use projectiles before engaging monsters in close combat.
- - Rest between encounters. The 's', '.', delete or keypad-5 commands make you 
-   rest for one turn, while pressing '5' or shift-and-keypad-5 make you rest 
-   for a longer time (you will stop resting when fully healed). 
- - Learn when to run away from things you can't handle - this is important! 
-   It is often wise to skip a dangerous level. But don't overdo this.
-
- DEATH 
-
-Before long, you'll probably end up dead. 
- 
-Death in Crawl is permanent; you cannot just reload a saved game and start again
-where you left off. The 'S' (save) command exists only to let you leave a game 
-part-way through and come back to it later. Quitting ('Q') lets you commit
-suicide if you can't even be bothered to help your character escape alive. 
-
-Well, that's it for the quick-start guide. This should help you through your 
-first few games, but Crawl is extremely (some would say excessively) complex 
-and cannot be adequately described in so short a document. So when you feel 
-ready to start playing with magic, skills, and religions, browse the manual.
-Happy Crawling! 
+Dungeon Crawl Stone Soup
+========================
+
+Dungeon Crawl Stone Soup 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.
+
+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 
+you could possibly retrieve the 0.3.4 standards.
+
+Contents:
+1. How to get started? (Information for new players)
+2. The file system of this version.
+3. Contact and reporting bugs.
+4. License and history information.
+5. How you can help!
+
+1. Getting started
+------------------
+If you'd like to dive in immediately, your best bets are to
+* start up a game and choose a tutorial (press T when asked for race), or
+* read quickstart.txt (it is in docs/), or
+* for studious readers, browse the manual (see below for all doc files).
+
+Additionally, you may want to print out the file keys.pdf from the docs/
+folder. Besides a full list of command keys (don't bother with it), it contains 
+two pages of help for new players.
+Note that you can read quickstart.txt and the manual when playing; pressing ? 
+brings up a menu for that.
+
+
+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.)
+
+* 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.
+
+The docs/ folder contains the following helpful texts (all of which can be 
+read in-game by bringing up the help menu with '?'):
+
+* the_manual.txt  The complete manual; describing all aspects in the
+                   detail. Contains appendices on species, classes, etc.
+* options.txt     Describes all options in detail. The structure of
+                   init.txt follows this text.
+* macros.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.
+* ssh_guide.txt   An elaborate introduction on how to get internet play
+                   to work. For Windows only.
+* irc_guide.txt   An elaborate introduction on how to access the IRC
+                   channel ##crawl.
+* keys.pdf        A printable document, listing all commands and it also
+                   contains a very short guide for new players.
+
+
+3. Contact and reporting bugs
+-----------------------------
+The official webpage is
+      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 
+bugs or mention new ideas.
+
+There is a Usenet newsgroup dealing with roguelikes, including Crawl:
+      rec.games.roguelike.misc
+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.
+
+
+4. License and history information
+----------------------------------
+What you have downloaded is a successor to Linley's Dungeon Crawl. Development 
+of the main branch stalled at version 4.0.26, with a final alpha of 4.1 being 
+released by Brent Ross in 2005. Since 2006, the Dungeon Crawl Stone Soup 
+team continues the development.
+
+Dungeon Crawl Stone 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.
+Stone Soup features both ASCII and Tiles display.
+
+Crawl gladly and gratiously uses the following open-source packages:
+* The Lua script language, see /docs/lualicense.txt.
+* The PCRE library for regular expressions, see /docs/pcre-license.txt.
+* The Mersenne Twister for random number generation, /docs/mt19937.txt.
+* The SQLite library as database enging; it is properly public domain.
+* The ReST light markup language for the documentation.
+
+5. 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:
+
+* 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.
+
+* 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 
+dat/entry.des for a first impression). Later, you may want to read 
+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.
+
+* 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 a slightly strange, so you may want to read 
+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.
+
+* Monster descriptions.
+You can look up that current descriptions in-game with ?/ or just read them in 
+dat/descript/monsters.txt. The following conventions should be more or less 
+obeyed: descriptions ought to contain flavour text, ideally pointing out major 
+weaknesses/strenghts. No numbers, please. Citations are okay, but try to stay 
+away from the most generic ones.
+
+* 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.
+
+* 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 is welcome. 
+Please be sure to read docs/coding_conventions.txt first.