Apply the relevant parts of r10086 to 0.5, add the patch guide and new

man page, and update the change log.


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

11 files changed, 252 insertions, 1097 deletions

diff --git a/crawl-ref/docs/changes.stone_soup b/crawl-ref/docs/changes.stone_soup
index 64f2dbcac2..ff7f75be46 100644
--- a/crawl-ref/docs/changes.stone_soup
+++ b/crawl-ref/docs/changes.stone_soup
@@ -4,11 +4,14 @@ Stone Soup 0.5.1 (2009????)
 Disclaimer: These are merely the highlights, not an exhaustive list of changes.
 
 * Speed-up for the Tiles version.
-* Fix crashes related to giant spores.
-* Fix erroneous "blocked line of fire" warnings.
-* Fix missing items in Tiles inventory.
+* Fixed crashes related to giant spores.
+* Fixed summoning decks giving permanent summons at low power.
+* Fixed erroneous "blocked line of fire" warnings.
+* Fixed missing items in Tiles inventory menus.
+* Fixed Xom's repel stairs effect moving shops.
 * Really allow uniques to retain their spells when polymorphed.
-* Tiles: Allow selection of player dolls.
+* Artificers start with 1 MP.
+* Tiles: Re-allow selection of player dolls.
 * Add missing tiles options to the options guide (docs/, '?&' command).
 
 Stone Soup 0.5.0 (20090612)
diff --git a/crawl-ref/docs/crawl.6 b/crawl-ref/docs/crawl.6
index 2010bf4456..846a2e5e8c 100644
--- a/crawl-ref/docs/crawl.6
+++ b/crawl-ref/docs/crawl.6
@@ -1,1056 +1,18 @@
-.TH crawl 6 "02 April 2001"
-.IX crawl
+.TH CRAWL 6
 .SH NAME
 crawl - play the roguelike game of crawl
 .SH SYNOPSIS
 .BR crawl
-[-name <string>]
-[-race <letter>]
-[-class <letter>]
-[-plain]
-[-dir <path>]
-[-rc <file>]
-[-scores [N]]
-[-scorefile <file>]
+[options]
+.PP
+Use the "-help" option to get a list of command line options and their descriptions.
 .SH DESCRIPTION
 Crawl is a fun game in the grand tradition of games like Rogue, Hack, and
 Moria. Your objective is to travel deep into a subterranean cave complex and
 retrieve the Orb of Zot, which is guarded by many horrible and hideous
 creatures.
 .PP
-This file contains detailed instructions for playing Crawl. If you are
-completely new to this kind of game, it may be worth your while to read at
-least part (although it will probably confuse you somewhat), otherwise you
-should probably just dive into the game and use the '?' command to give a list
-of keys to use.
-.PP
-.SH OPTIONS
-.TP
-\fB-name\fR <string>
-set character name
-.TP
-\fB-race\fR <letter>
-preselect race
-.TP
-\fB-class\fR <letter>
-preselect class
-.TP
-\fB-plain\fR
-don't use IBM extended characters (needed when playing in a xterm)
-.TP
-\fB-dir\fR <path>
-crawl directory
-.TP
-\fB-macro\fR <path>
-directory for crawl macro file
-.TP
-\fB-rc\fR <file>
-init file name
-.TP
-\fB-scores\fR [N]
-show highscore list [first N entries]
-.TP
-\fB-scorefile\fR <file>
-scorefile name. If used without -scores, converts the scorefile to Crawl's
-native format and writes it to stdout (useful to convert logfiles from previous
-releases). If the filename is -, reads the scorefile on stdin.
-.PP
-.SH THE GAME
-.IP "CHARACTER SPECIES"
-.PP
-You have a number of different character races to choose from. This affects
-several characteristics including:
-Your choice of classes;
-Your initial attributes (strength etc);
-Occasional extra points added to some abilities;
-The amount of hit points and magic you get as you increase in level;
-Your initial equipment;
-Your rate of level advancement;
-Your rate of skill advancement.
-.PP
-.I Humans
-are the most versatile race. Humans advance quickly in levels and
-have equal abilities in all skills. Humans can also be of any class.
-.PP
-.I Elves
-have good intelligence and dexterity, but suffer a bit in strength.
-They have slightly less hp and slightly more magic than humans, and advance in
-experience a bit more slowly as well. They are especially good at fighting
-with short and long swords, although not so good at other weapons, and are
-adept at bows and darts. Their quickness makes them good at dodging, and they
-possess natural elven stealth as well. Their nature also gives them
-proficiency with magic, especially enchantments, but they are poor at using
-necromancy.
-.PP
-There are also a number of related types of elves:
-.PP
-.I High elves
-are a powerful elven race who advance in levels very slowly -
-requiring half again as much experience as do humans. They are similar to
-common elves in most respects, but their strengths and weaknesses tend to be
-greater.
-.PP
-.I Grey elves
-also advance slowly, but more quickly than high elves. They are
-generally poor at fighting - although they are still good at short and long
-swords and bows - but are excellent at all forms of magic except for
-necromancy.
-.PP
-.I Deep elves
-are poor at fighting but excellent at bows, crossbows, darts, and
-especially magic. They are the only elven subtype who are skilled at using
-necromancy and earth magic, and are particularly good at enchantment magic.
-They advance in levels at the same rate as grey elves. Deep elves are not
-physically robust, but have great reserves of magical energy.
-.PP
-.I Sludge elves
-are a bit like common elves, but are not quite as good at most
-things while being better at necromancy and some elemental magics. They
-advance in level slightly faster, though.
-.PP
-Elven armour is unusually light, and does not affect the dodging or stealth of
-its wearer to the extent that other armours do. Elven cloaks and boots are
-particularly useful to those who wish to be stealthy, and elven bows are
-particularly effective in conjunction with elven arrows. Elves are especially
-dangerous when using elven weapons.
-.PP
-All elves are good at using air elemental magic, and are okay at fire and ice
-magic. They are also poor at earth magic with the exceptions of deep and
-sludge elves, who can use earth magic well.
-.PP
-.I Hill dwarves
-are extremely robust but are poor at using magic. They are
-excellent at hand combat, especially favouring axes, and are good at using
-armour and shields, but are poor at missile combat or at using polearms (which
-are usually too big for them to wield comfortably). The only forms of magic
-which they can use with any aptitude are earth, fire and conjurations, but
-they are worse than humans at the conjurations skill. They advance in levels
-at a similar rate to common elves.
-.PP
-.I Mountain dwarves
-are almost as robust as hill dwarves and have similar
-aptitudes, but are slightly better at the things that hill dwarves don't do
-very well, and slightly worse at the things that hill dwarves are good at.
-They advance in levels at a rate between that of elves and humans.
-.PP
-Dwarven weapons and armours are very durable, and do not rust or corrode
-easily. Dwarves are especially effective when using dwarven weaponry.
-.PP
-.I Halflings
-are very small and, with deep elves and kobolds, are the least
-robust of any character race. Although fair to poor at most fighting skills,
-they can use short blades well and are good at all forms of missile combat.
-They are also very stealthy and good at dodging and stabbing, but are poor at
-most types of magic (except enchantments and translocations). They advance in
-levels as rapidly as humans. Halflings cannot wield large weapons.
-.PP
-.I Hill orcs
-are orcs from the upper world who, jealous of the riches which
-their cousins, the cave orcs, possess below the ground, descend in search of
-plunder and adventure. They are as robust as the hill dwarves, but have very
-low reserves of magical energy. Their forte is fighting, and they are skilled
-at using most hand weapons (with the exception of short blades, at which they
-are only fair, and missile weapons, at which they are not particularly good).
-They are poor at using most types of magic with the exception of conjurations
-and necromancy. They advance as quickly as humans.
-.PP
-Orcish bows/crossbows are particularly effective in combination with orcish
-arrows/bolts. Orcs are especially good at using orcish weapons.
-.PP
-Orcs are poor at using air elemental magic, but okay at other kinds (and good
-at earth magic).
-.PP
-.I Kobolds
-are small, ugly creatures with few redeeming features. They have
-poor abilities and have similar aptitudes to halflings, without the excellent
-agility. However, they are slightly better than halflings at using some types
-of magic, particularly summonings and necromancy. They often live as
-scavengers, surviving on carrion, but are carnivorous and can only eat meat.
-They advance in levels as quickly as humans.
-.PP
-.I Mummies
-are undead creatures who travel into the depths in search of
-revenge, redemption, or just because they want to. Being undead, they are
-immune to poisons and negative energy, have little warmth left to be affected
-by cold, and are not susceptible to reductions in their physical or mental
-abilities. However, their dessicated bodies are highly flammable. They also do
-not need to eat or drink, and in any case are unable to.
-.PP
-Mummies progress very slowly in level (as slow as High Elves) and in all
-skills except fighting, spellcasting and necromancy. As they increase in level
-they become increasingly in touch with the powers of death, but cannot use
-some types of necromancy which only affect living creatures (if they are
-unable to use a spell, they will usually be unable to memorise it). The side
-effects of necromantic magic tend to be relatively harmless to mummies.
-.PP
-.I Naga
-are a race of hybrids; humanoid from the waist up, with a large
-snake tail instead of legs. They are reasonably good at most things and
-advance in experience levels at a decent rate. They are naturally immune to
-poisons, can see invisible creatures, and have tough skin, but their tails are
-relatively slow and cannot move them around as quickly as can other creatures'
-legs (this only affects their movement rate; all other actions are at normal
-speed). Their body shape also prevents them from gaining full protection from
-most armour. Every now and then, a naga can spit poison; the range, accuracy
-and damage of this poison increases with the naga's experience level.
-.PP
-.I Gnomes
-are an underground-dwelling race of creatures, related to the dwarves
-but even more closely in touch with the earth. They are quite small, and share
-many of their characteristics with halflings (except for the great agility),
-although they advance slightly more slowly in experience levels. They are okay
-at most skills, but excellent at earth elemental magic and very poor at air
-magic. Occasionally they can use their empathy with the earth to sense their
-surroundings; this ability increases in power as they gain experience levels.
-.PP
-.I Ogres
-are huge, chunky creatures related to orcs. They have great physical
-strength, but are bad at almost everything except fighting. Because of their
-large size they can only wear loose robes, cloaks and animal skins. They learn
-quite slowly. Although ogres can eat almost anything, their size means that
-they need to.
-.PP
-.I Trolls
-are like ogres, but even nastier. They can rip creatures apart with
-their claws, and regenerate very quickly from even the most terrible wounds.
-They learn very slowly indeed - even more slowly than high elves - and need a
-great amount of food to survive.
-.PP
-.I Ogre-mages
-are a separate race of ogres who are unique among the beefier
-races in their ability to use magic, especially enchantments. Although
-slighter than their common ogre relatives they nevertheless have great
-strength and can survive a lot of punishment. They advance in level as slowly
-as high elves.
-.PP
-.I Draconians
-are a race of human-dragon hybrids; humanoid in form and
-approximately human-sized, with wings, tails and scaly skins. Draconians start
-out in an immature form with brown scales, but as they grow in power they take
-on a variety of colours. Some types of draconians have breath weapons. Because
-of their decidedly non-human shapes, draconians cannot wear most armours.
-Draconians advance very slowly in level, but are reasonably good at most
-skills (except missile weapons and armour).
-.PP
-.I Centaurs
-are another race of hybrid creatures: horses with a human
-torso. Centaurs can move very quickly on their four legs, and are excellent
-with bows and other missile weapons; they are also reasonable at the Fighting
-skill while being slow learners at specific weapon skills. They advance quite
-slowly in experience level and are rather sub-average at using magic. Due to
-their large bulk, they need a little extra food to survive.
-.PP
-.I Demigods
-are mortals (humans, orcs or elves, for example) with some divine
-ancestry, however distant; they can be created by a number of processes
-including magical experiments and the time-honoured practice of interplanar
-miscegenation. Demigods look more or less like members of their mortal part's
-race, but have excellent abilities (strength, int, dex) and are extremely
-robust; they also have great supplies of magical energy. On the downside they
-advance very slowly in experience, gain skills slightly less quickly than
-humans, and cannot worship the various Gods and Powers available to the other
-races.
-.PP
-.I Spriggans
-are small magical creatures distantly related to elves. They are
-poor fighters with anything other than a dagger or a shortsword, have little
-physical resilience, and are terrible at destructive magic - conjurations,
-summonings, necromancy and elemental spells. On the other hand, they are
-excellent at other forms of magic and are very good at moving silently and
-quickly. So great is their speed that a spriggan can keep pace with a centaur.
-.PP
-.I Minotaurs
-are yet another hybrid - a human body with a bovine head.
-Minotaurs are extremely good at all forms of physical combat, but are awful at
-using any type of magic. They can wear all armour except for headgear.
-.PP
-.I Demonspawn
-are horrible half-mortal, half-infernal creatures - the flip side
-of the Demigods. Demonspawn can be created in any number of ways - magical
-experiments, breeding, unholy pacts, etc. Although many demonspawn may be
-indistinguishable from those of pure mortal stock, they often grow horns,
-scales or other unusual features. Powerful members of this class of beings
-also develop a range of unholy abilities, which are listed as mutations (and
-can sometimes be activated with the 'a' command).
-.PP
-Demonspawn advance very slowly in experience and learn most skills at about
-the same rate as do Demigods. However, they are a little better at fighting
-and much better at conjurations, summonings, necromancy and invocations.
-.PP
-.I Ghouls
-are horrible undead creatures, slowly rotting away. Although ghouls
-can sleep in their graves for years on end, when they rise to walk among the
-living they must eat flesh to survive. Raw flesh is preferred, especially
-rotting or tainted meat, and ghouls gain strength from consuming it.
-.PP
-As undead, Ghouls are naturally immune to poison, cold and negative energy.
-They aren't very good at doing most things, although they make decent fighters
-and can use ice and earth magic without too many difficulties.
-.PP
-.I Kenku
-are an ancient and feared race of bird-people with a legendary
-propensity for violence. They are experts at all forms of fighting, including
-the magical arts of combat (conjurations, summonings and, to a lesser extent,
-necromancy). However, their light avian bodies cannot sustain a great deal of
-injury.
-.PP
-Basically humanoid with bird-like heads and clawed feet, the kenku can
-wear all types of armour except helmets and boots. Despite their lack of
-wings, powerful kenku can fly and very powerful members of this race can stay
-in the air permanently. They are good at air and fire elemental magic, but
-poor at ice and earth magic. Kenku do not appreciate any form of servitude,
-and so are poor at using invocations.
-.PP
-Some species have special abilities which can be accessed by the 'a' abilities
-menu. Some also have physical characteristics which allow them to make extra
-attacks using the Unarmed Combat skill.
-.PP
-.IP "CHARACTER CLASSES"
-.PP
-In your quest, you play as one of a number of different types of characters.
-Although each has its own strengths and weaknesses, some are definitely easier
-than others, at least to begin with. The best classes for a beginner are
-probably Gladiators, fighters and Berserkers; if you really want to play a
-magician, try a Conjurer. Each class starts out with a different set of skills
-and items, but from there you can shape them as you will.
-.PP
-.I Fighters
-start with a decent weapon, a suit of armour and a shield. They have
-a good general grounding in the arts of fighting.
-.PP
-.I Priests
-serve either Zin, the ancient and revered God of Law, or the rather
-less pleasant Death-God Yredelemnul. Although priests enter the dungeon with a
-mace (as well as a priestly robe and a few healing potions), this is purely
-the result of an archaic tradition the reason for which has been lost in the
-mists of time; Priests are not in any way restricted in their choice of weapon
-skills.
-.PP
-The
-.I Thief
-is one of the trickiest classes to play. Thieves start out with a
-large variety of useful skills, and need to use all of them to survive.
-Thieves start with a short sword, some throwing darts, and light armour.
-.PP
-The magician is the best at using magic. Magicians start with a dagger,
-a robe, and a book of spells which should see them through the first several
-levels. There are various kinds of magicians:
-.PP
-The
-.I Wizard
-is a magician who does not specialise in any area of magic.
-Wizards start with a variety of magical skills and the magic dart spell in
-memory.
-.PP
-The
-.I Conjurer
-specialises in the violent and destructive magic of conjuration
-spells. Like the Wizard, the Conjurer starts with the magic dart spell.
-.PP
-The
-.I Enchanter
-specialises in the more subtle area of enchantment magic.
-Although not as directly powerful as conjurations, high-level enchantments
-offer a wide range of very handy effects. As there are no useful enchantment
-spells of the first level, the Enchanter begins with a random attack spell and
-has a magic wand to help survive until he or she can start learning to use the
-craft properly, and is equipped with lightly enchanted weapons and armour.
-.PP
-The
-.I Summoner
-specialises in calling creatures from this and other worlds to
-give assistance. Although they can at first summon only very wimpy creatures,
-the more advanced summoning spells allow summoners to call on such powers as
-elementals and demons.
-.PP
-The
-.I Necromancer
-is a magician who specialises in the less pleasant side of
-magic. Necromantic spells are a varied bunch, but many involve some degree of
-risk or harm to the caster.
-.PP
-.I Elementalists
-are magicians who specialise in one of the four types of
-elemental magic.
-.PP
-.I Venom mages
-specialise in poison magic, which is extremely useful in the
-shallower levels of the dungeon where few creatures are immune to it. Poison
-magic is especially effective when used against insects.
-.PP
-.I Transmuters
-specialise in transmigrations, and can cause strange changes in
-themselves and others.
-.PP
-.I Warpers
-specialise in translocations, and are experts in travelling long
-distances and positioning themselves precisely.
-.PP
-The
-.I Paladin
-is a servant of the Shining One, and has many of the abilities of
-the Fighter and the Priest. He or she enters the dungeon with a sword, a
-shield, a robe, and a healing potion.
-.PP
-The
-.I Gladiator
-is well trained in the art of fighting but is not so good at
-other things. In fact, Gladiators are pretty terrible at anything except
-bashing monsters with heavy things. They start with a nasty weapon, a small
-shield, and armour.
-.PP
-The
-.I Berserker
-is a hardy warrior who fights well with many weapons.
-Berserkers worship Trog the Wrathful, from whom they get the power to go
-berserk (as well as a number of other powers should they prove worthy)
-but who forbids the use of spell magic. They enter the dungeon with an
-axe, some spears, and a set of leather armour.
-.PP
-The
-.I Ranger
-is a fighter who specialises in missile weapons. A Ranger starts
-with a bow and some arrows, as well as a hunting knife and a set of leathers.
-.PP
-An
-.I Assassin
-is a thief who is especially good at killing. Assassins are like
-thieves in most respects, but begin more skilled at hand combat.
-.PP
-The
-.I Crusader
-is a decent fighter who also has some aptitude in the magical
-arts. Crusaders start out with a book of martial spells.
-.PP
-The
-.I Death Knight
-is a fighter who aligns him or herself with the powers of
-death. There are two types of Death Knights: those who worship and draw their
-abilities from the Demon-God Yredelemnul, and those who study the fearsome
-arts of necromancy.
-.PP
-The
-.I Chaos knight
-is a fighter who chooses to serve one of the fearsome and
-unpredictable Gods of Chaos. He or she has two choices: Xom or Makhleb. Xom is
-a very unpredictable (and possibly psychotic) creature who rewards or punishes
-according to whim. Makhleb the Destroyer is a more purposeful God, who
-appreciates destruction and offers a variety of very violent powers to the
-faithful.
-.PP
-The
-.I Healer
-is a priest of Elyvilon. Healers begin with minor healing powers,
-but can gain far greater abilities in the long run.
-.PP
-The
-.I Reaver
-is a warrior who has some aptitude with the magic of destruction.
-.PP
-The
-.I stalker
-is an assassin who has some aptitude in the use of poison magic.
-.PP
-The
-.I Monk
-is a type of fighter specialising in unarmed combat. Monks start
-with very little equipment, but can survive without the weighty weapons and
-spellbooks needed by other classes.
-.PP
-.IP EXPERIENCE
-.PP
-When you kill monsters, you gain experience points (xp) (you also receive one
-half experience for monsters killed by friendly creatures). When you get
-enough xp, you gain an experience level, making your character more powerful.
-As they gain levels, characters gain more hit points, magic points, and spell
-levels.
-.PP
-.IP SKILLS
-.PP
-Your character has a number of skills which affect his or her ability to
-perform certain tasks. You can see your character's skills by pressing the 'm'
-key; the higher the skill level of a skill, the better you are at it. Every
-time your character gains experience points, those points become available to
-increase skills. You convert experience points into skill levels by practising
-the skill in question (eg fight with a certain type of weapon, cast a certain
-type of spell, or walk around wearing light armour to practise stealth). The
-amount of unassigned experience points is shown on the skills screen, and the
-number in blue next to each skill counts down from 9 to 0 as you get closer to
-increasing that skill.
-.PP
-You can elect not to practise a particular skill by selecting it in the skill
-screen (making it turn dark grey). This means that you will be less likely to
-increase that skill when you practise it (and will also not spend as many
-experience points on it).
-.PP
-The race you have chosen for your character has a significant effect on
-your rate of advancement in each skill. Some races are very good at some
-skills and poor at others. If your character's race is good at a skill, they
-will require less experience and take less time to advance in it; being bad
-at a skill has the opposite result.
-.PP
-There are a few different types of skills:
-.PP
-Fighting skills
-.PP
-.I Fighting
-is the basic skill used in hand-to-hand combat, and applies
-no matter which weapon your character is wielding (if any). It is also
-the skill which determines the number of hit points your character gets
-as they increase in level (note that this is calculated so that you don't
-get a long run advantage by starting out with a high fighting skill).
-.PP
-In addition, there are a number of weapon skills which affect your ability to
-fight with specific weapons. If you are already good at a weapon, say a long
-sword, and you practise for a while with similar weapon such as a short sword,
-your practise will be speeded up (and will require less experience) until both
-skills are equal.
-.IP "Similar types of weapons include:"
-- All sword skills
-.br
-- Maces & flails and Axes
-.br
-- Polearms and Axes
-.br
-- Staves and Polearms
-.PP
-Being good at a specific weapon improves the speed with which you can use it
-by about 10% every two skill levels. Although lighter weapons are easier to
-use initially, as they strike quickly and accurately, heavier weapons increase
-in damage potential very quickly as you improve your skill with them.
-.PP
-.I Unarmed Combat
-is a special fighting skill. It allows your character to make
-a powerful attack when unarmed and also to make special secondary attacks
-(and increases the power of those attacks for characters who get them anyway).
-You can practise Unarmed Combat by attacking empty-handed, and it is also
-exercised when you make a secondary attack (a kick, punch etc). Unarmed combat
-is particularly difficult to use in combination with heavy armour, and
-characters wearing a shield or wielding a two-handed weapon other than a staff
-lose the powerful punch attack.
-.PP
-Throwing skills
-.PP
-.I Throwing
-is the basic skill used when throwing things, and there are
-a number of individual weapon skills for missile weapons as well.
-.PP
-Magic skills
-.PP
-.I Spellcasting
-is the basic skill for magic use, and affects your
-reserves of magical energy in the same way that Fighting affects your
-hit points. Every time you increase your spellcasting skill you gain
-some magic points and spell levels. Spellcasting is a very difficult
-skill to learn, and requires a large amount of practice and experience.
-.PP
-Only those characters with at least one magic skill at level one or above can
-learn magical spells. If your character has no magic skills, he or she can
-learn the basic principles of the hermetic arts by reading and reciting the
-spells inscribed on magical scrolls (this stops being useful once you reach
-level one in Spellcasting).
-.PP
-There are also individual skills for each different type of magic; the higher
-the skill, the more powerful the spell. Multidisciplinary spells use an
-average of the two or three skills.
-.PP
-Elemental magic is a special case here. When you practise an elemental magic
-skill (fire, ice, air or earth magic) you will improve much less quickly than
-normal if you already have one or more elemental magic skills higher than the
-one you are practising. This is especially true if those skills are 'opposed'
-to the one you're practising: fire and ice are mutually opposed, as are earth
-and air. Say you have level 2 fire magic, level 4 ice magic, and level 1 air
-magic. Practising ice magic won't be a problem. Practising air magic will be a
-bit slow, as you have other elemental skills at higher levels. Practising fire
-magic will be very slow, as you have a higher level in ice magic. Right?
-.PP
-Miscellaneous
-.PP
-This includes a variety of skills:
-.PP
-.IR Armour :
-Having a high armour skill means that you are used to wearing heavy
-armour, so you gain more AC from it and lose less evasion while wearing it.
-.PP
-.IR Dodging :
-When you are wearing light armour, a high dodging skill increases
-your evasion score.
-.PP
-.IR Stealth :
-Helps you avoid being noticed. Try not to wear heavy armour (or be
-encumbered) if you want to be stealthy.
-.PP
-.IR Stabbing :
-Lets you make a very powerful first strike against a
-sleeping/resting monster who hasn't noticed you yet. This is most effective
-with a dagger, slightly less effective with a short sword, and less useful
-(although by no means of negligible effect) with any other weapon.
-.PP
-.IR Shields :
-affects the amount of protection you gain by using a shield.
-.PP
-.IR "Traps & doors" :
-affects your ability to notice hidden traps and doors and to
-disarm traps when you find them. With this skill at a high level you will
-often find hidden things without actively looking for them.
-.PP
-.IR Invocations :
-an easy-to-learn skill which affects your ability to call on
-your God for aid. Those skilled at invoking have reduced fail rates and
-produce more powerful effects. The Invocations skill affects your supply of
-magic in a similar way to the Spellcasting skill and to a greater extent, but
-the two are not cumulative - whichever gives the greater increase is used.
-Some Gods (such as Trog) do not require followers to learn this skill.
-.PP
-If your character does not have a particular skill, they can gain it by
-practising as above.
-.PP
-.IP ABILITIES
-.PP
-Your character is further defined by his or her abilities, which initially
-vary according to class and species.
-.PP
-.I Strength
-affects the amount of damage you do in combat, as well as how much
-stuff you can carry.
-.PP
-.I Intelligence
-affects how well you can cast spells as well as your ability to
-use some magical items.
-.PP
-.I Dexterity
-affects your accuracy in combat, your general effectiveness with
-missile weapons, and your ability to dodge attacks aimed at you. Although
-your dexterity does not affect your evasion score (Ev) directly, any
-calculation involving your Ev score also takes account of your dexterity.
-.PP
-.IR AC :
-This stands for Armour Class. When you something injures you, your AC
-reduces the amount of damage you suffer. The number next to your AC is a
-measure of how good your shield (if any) is at blocking attacks.
-.PP
-.IR EV :
-This is your evasion score. It helps you to avoid being hit by unpleasant
-things.
-.PP
-.IR Gold :
-This is how much money you're carrying. Money adds to your final score,
-and can be used to purchase items in shops.
-.PP
-.I Magic Resistance
-affects your ability to resist the effects of enchantments
-and similar magic directed at you. Although your magic resistance increases
-with your level to an extent determined by your character's race, the
-creatures you will meet deeper in the dungeon are better at casting spells
-and are more likely to be able to affect you. MR is an internal variable, so
-you can't see what yours is.
-.PP
-Sometimes characters will be able to use special abilities, for example the
-Naga's ability to spit poison or the magical power to turn invisible granted
-by a ring. These are accessed through the 'a' command.
-.PP
-.IP RELIGION
-.PP
-There are a number of Gods, Demons and other assorted Powers who will accept
-your character's worship, and sometimes give out favours in exchange. You can
-use the '^' command to check the requirements of whoever it is that you
-worship, and if you find religion to be an inconvenience you can always
-renounce your faith (use the 'a' command - but some Gods resent being
-scorned!).
-.PP
-The 'p' command lets you pray to your God. Anything you do while praying, you
-do in your God's name - this is how you dedicate your kills or corpse-
-sacrifices ('D' command) to your God, for example. Praying also gives you a
-sense of what your God thinks of you, and can be used to sacrifice things at
-altars.
-.PP
-To use any powers which your God deems you fit for, access the abilities menu
-with the 'a' command; God-given abilities are listed as invocations.
-.PP
-Some classes start out religious; others have to pray at an altar to dedicate
-themselves to a life of servitude. There are altars scattered all over the
-dungeon, and your character has heard rumours of a special temple somewhere
-near the surface.
-.PP
-.IP MUTATIONS
-.PP
-Although it would doubtless be a nice thing if you could remain genetically
-pure, there are too many toxic wastes and mutagenic radiations in the Dungeon
-for that to be possible. If your character is so affected by these that he or
-she undergoes physiological change, you can use the 'A' command to see how
-much of a freak they've become and the 'a' command to activate any mutations
-which can be controlled.
-.PP
-You can also become mutated by overusing certain powerful enchantments,
-particularly Haste (not the kind you get from being berserk) and Invisibility,
-as your system absorbs too much magical energy - but you would have to spend
-almost all of your time hasted or invisible to be affected. However, some
-powerful items radiate dangerous levels of magical energy. More often than
-not, the mutations caused by magical radiations express harmfully.
-.PP
-Any demonic powers your character may have are listed in red; these are
-permanent and can never be removed. If one of your powers has been augmented
-by a mutation, it is displayed in a lighter red colour.
-.PP
-.IP "EXPLORING THE DUNGEON"
-.PP
-You can make your character walk around with the numeric keypad (turn numlock
-off) or the "Rogue" keys (hjklbnyu). If this is too slow, you can make your
-character walk repeatedly by typing shift and a direction. They will walk in
-that direction until any of a number of things happen: a hostile monster is
-visible on the screen, a message is sent to the message window for any reason,
-you type a key, or you are about to step on anything other than normal floor
-or an undiscovered trap and it is not your first move of the long walk. Note
-that this is functionally equivalent to just pressing the direction key
-several times.
-.PP
-If you press shift and '5' on the numeric keypad (or just the number '5' on
-the keyboard) you rest for 100 turns or until your hit points or magic return
-to full, whichever is sooner. You can rest for just one turn by pressing '.',
-delete, 's', or '5' on the keypad. Whenever you are resting, you are assumed
-to be observing your surroundings, so you have a chance of detecting any traps
-or secret doors adjacent to you.
-.PP
-The section of the viewing window which is coloured (with the '@' representing
-you at the centre) is what you can see around you. The dark grey around it is
-the parts of the level which you have visited, but cannot currently see. The
-\&'x' command lets you move the cursor around to get a description of the
-various dungeon features, and typing '?' when the cursor is over a monster
-brings up a short description of that monster (these are all rather sketchy;
-I'll write better descriptions when I have time). You can get a map of the
-whole level (which shows where you've already been) by typing the 'X' key.
-This map specially colour-codes stairs and known traps, even if something is
-on top of them.
-.PP
-You can make your way between levels by using staircases, which appear as '>'
-(down) and '<' (up), by pressing the '>' or '<' keys. If you ascend an up
-staircase on level one, you will leave the dungeon forever; if you are
-carrying the magical Orb of Zot, you win the game by doing this.
-.PP
-Occasionally you will find an archway; these lead to special places like
-shops, magical labyrinths, and Hell. Depending on which type of archway it is,
-you can enter it by typing '<' or '>'.
-.PP
-Doors can be opened with the 'o' command and closed with the 'c' command.
-Pressing control plus a direction also opens doors. If there is no closed door
-in the indicated space, you will attempt to attack any monster which may be
-standing there (this is the only way to attack a friendly creature hand-to-
-hand). If there is no creature there, you will attempt to disarm any trap in
-the target square. If there is apparently nothing there you will still attack
-it, just in case there's something invisible lurking around.
-.PP
-A variety of dangerous and irritating traps are hidden around the dungeon.
-Traps look like normal floor until discovered (usually by activating them). A
-discovered trap can be disarmed with the control-direction commands, although
-not all traps can be affected in this way.
-.PP
-When you are in a shop, you are given a list of the shopkeeper's stock from
-which to choose, and a list of instructions. You can leave the shop and even
-the level and come back later if you want. Unfortunately the shopkeepers all
-have an enterprise bargaining agreement with the dungeon teamsters union which
-prevents them using non-union labour to obtain stock, so you can't sell
-anything in a shop (but what shopkeeper would trust a scummy adventurer like
-you, anyway?).
-.PP
-You goal is to locate the Orb of Zot, which is held somewhere deep beneath the
-world's surface. The Orb is an ancient and incredibly powerful artefact, and
-the legends promise great things for anyone brave enough to extract it from
-the fearsome Dungeon. Some believe it will grant immortality or even godhood
-to the one who carries it into the sunlight; many undead creatures seek it in
-the hope that it will restore them to life. Good luck!
-.PP
-.PP
-A full list of the commands available to you can be accessed by typing '?'
-(question mark). If you don't like them, they can be changed by the use of:
-.PP
-.IP "MACROS/KEYMAPS"
-.PP
-You can change the keys used to perform specific functions by editing the
-macro.txt file (or creating a new one). The K: line indicates a key, and the
-A: line assigns another key to that key's function.
-.PP
-You can also redefine keys in-game with the ` key, and save them with the ~
-key.
-.PP
-(Thanks to Juho Snellman for this patch)
-.PP
-.IP ITEMS
-.PP
-In the dungeons of Crawl there are many different kinds of normal and magical
-artefacts to be found and used. Some of them are useful, some are nasty, and
-some give you great power, but at a price. Some items are unique; these have
-interesting properties which can make your life rather bizarre for a while.
-They all fall into several classes of items, each of which is used in a
-different way. Here is a general list of what you might find in the course of
-your adventures:
-.PP
-.IP WEAPONS
-.PP
-These are rather important. You will find a variety of weapons in the dungeon,
-ranging from small and quick daggers to huge, cumbersome battleaxes and pole-
-arms. Each type of weapon does a differing amount of damage, has a different
-chance of hitting its target, and takes a different amount of time to swing.
-You should choose your weapons carefully; trying to hit a bat with a
-greatsword is about as clever as bashing a dragon with a club. For this reason
-it is wise to have a good mixture of weapon skills. Skills affect damage,
-accuracy and speed.
-.PP
-Weapons can be enchanted; when they are identified, they have values which
-tell you how much more effective they are than an unenchanted version. The
-first number is the enchantment to-hit, which affects the weapon's accuracy,
-and the second is its damage enchantment; weapons which are not enchanted are
-simply '+0'. Some weapons also have special magical effects which make them
-very effective in certain situations. Some types of hand weapon (especially
-daggers, spears and hand axes) are quite effective when thrown. You can wield
-weapons with the 'w' command, which is a very quick action. If for some reason
-you want to go bare-handed, type 'w' followed by a hyphen ('-'). Note that
-weapons are not the only class of item which you can wield.
-.PP
-The ' key is a shortcut which automatically wields item a. If item a is being
-wielded, it causes you to wield item b instead, if possible. Try assigning the
-letter a to your primary weapon, and b to your bow or something else you need
-to wield only sometimes. Note that this is just a typing shortcut and is not
-functionally different to wielding these items normally.
-.PP
-.IP AMMUNITION
-.PP
-If you would rather pick off monsters from a safe distance, you will need
-ammunition for your sling or bow. Darts are effective when simply thrown;
-other kinds of ammunition require you to wield an appropriate device to
-inflict worthwhile damage. Ammunition has only one "plus" value, which affects
-both accuracy and damage. If you have ammunition suitable for what you are
-wielding, the 'f' command will choose the first lot in your inventory, or you
-can use the 't' command to throw anything. If you are using the right kind of
-hand weapon, you will "shoot" the ammunition, otherwise you "throw" it.
-.PP
-When throwing something, you are asked for a direction. You can either enter
-one of the directions on your keypad, or type '*' and move the cursor over
-your target if they are not in a direct line with you. When the cursor is on
-them, press '.' (period) or delete to target them (you can also target an
-empty space if you want). If you press '>' instead of  '.', the missile will
-stop at that space even if it misses, and if the target space is water, it may
-hit anything which might be lurking beneath the surface (which would otherwise
-be missed completely). If you type '.' (or del) instead of a direction or '*',
-or if you target yourself as described above, you throw whatever it is at
-yourself (this can be useful when zapping some wands; see later). Also, if you
-type 'p' instead of a direction or '*', you will target your previous target
-(if still possible).
-.PP
-.IP ARMOUR
-.PP
-This is also rather important. When worn, most armour improves your Armour
-Class, which decreases the amount of damage you take when something injures
-you. Unfortunately the heavier types of armour also hamper your movement,
-making it easier for monsters to hit you (ie reducing your evasion score) and
-making it harder for you to hit monsters. These effect can be mitigated by a
-high Armour skill. Wearing heavy armour also increases your chances of
-miscasting spells, an effect which is not reduced by your Armour skill.
-.PP
-A Shield normally affects neither your AC or your evasion, but it lets you
-block some of the attacks aimed at you and absorbs some of the damage you
-would otherwise receive from things like dragon breath and lightning bolts.
-Wearing a shield (especially a large shield) makes you less effective in hand
-combat.
-.PP
-Some magical armours have special powers. These powers are sometimes
-automatic, affecting you whenever you wear the armour, and sometimes must be
-activated with the 'a' command.
-.PP
-You can wear armour with the 'W' command, and take it off with the 'T'
-command.
-.PP
-.IP FOOD
-.PP
-This is extremely important. You can find many different kinds of food in the
-dungeon. If you don't eat when you get hungry, you will eventually die of
-starvation. Fighting, carrying heavy loads, casting spells, and using some
-magical items will make you hungry. When you are starving you fight less
-effectively as well. You can eat food with the 'e' command.
-.PP
-.IP "MAGICAL SCROLLS"
-.PP
-Scrolls have many different magical spells enscribed on them, some good and
-some bad. One of the most useful scrolls is the scroll of identify, which will
-tell you the function of any item you have in your inventory; save these up
-for the more powerful and inscrutable magic items, like rings. You can read
-scrolls (and by doing so invoke their magic) with the 'r' command.
-.PP
-.IP "MAGICAL POTIONS"
-.PP
-While scrolls tend to affect your equipment or your environment, most potions
-affect your character in some way. The most common type is the simple healing
-potion, which restores some hit points, but there are many other varieties of
-potions to be found. Try to avoid drinking poisonous potions! Potions can be
-quaffed (drunk) with the 'q' command.
-.PP
-.IP WANDS
-.PP
-Sometimes you will be lucky enough to find a stick which contains stored
-magical energies. Wands each have a certain amount of charges, and a wand will
-cease to function when its charges run out. You must identify a wand to find
-out how many uses it has left. Wands are aimed in the same way as missile
-weapons, and you can invoke the power of a wand by 'z'apping it.
-.PP
-.IP RINGS
-.PP
-Magical rings are among the most useful of the items you will find in the
-dungeon, but can also be some of the most hazardous. They transfer various
-magical abilities onto their wearer, but powerful rings like rings of
-regeneration or invisibility make you hunger very quickly when activated. You
-can put on rings with the 'P' command, and remove them by typing 'R'. You can
-wear up to two rings simultaneously, one on each hand; which hand you put a
-ring on is immaterial to its function. Some rings function automatically,
-while others require activation (the 'a' command).
-.PP
-Amulets are similar to rings, but have a different range of effects (which
-tend to be more subtle). Amulets are worn around the neck, and you can wear
-only one at a time.
-.PP
-.IP STAVES
-.PP
-There are a number of types of magical staves. Some enhance your general
-spellcasting ability, while some greatly increase the power of a certain class
-of spells (and possibly reduce your effectiveness with others). Some are
-spell staves, and hold spells which you can cast without having to memorise
-them first, and also without consuming food. You must wield a staff like a
-weapon in order to gain from its power, and magical staves are as effective as
-+0 quarterstaves in combat. Spell staves can be Invoked with the 'I' command
-while you are wielding them.
-.PP
-.IP BOOKS
-.PP
-Books contain magical spells which your character may be able to learn. You
-can read a book with the 'r' command, which lets you access a description of
-each spell, or memorise spells from it with the 'M' command. Some books have
-other special effects, and some powerful spellbooks have been known to punish
-the attentions of incompetent magicians.
-.PP
-.IP CARRION
-.PP
-If you manage to kill a monster delicately enough to avoid scattering bits of
-it around the room, it may leave a corpse behind for you to play with. Despite
-the fact that corpses are represented by the same '%' sign as food, you can't
-eat them without first cutting them into pieces with the 'D' command, and
-being extremely hungry helps as well. Even then, you should choose your
-homemade food with great care.
-.PP
-.IP MISCELLANEOUS
-.PP
-These are items which don't fall into any other category. You can use many of
-them by wielding and 'I'nvoking them. You can also use some other special
-items (such as some weapons) by invoking them in this way.
-.PP
-You pick items up with the ',' (comma) command and drop them with the 'd'rop
-command. When you are given a prompt like "drop which item?" or "pick up
-<x>?", if you type a number before either the letter of the item, or 'y' or
-\&'n' for yes or no, you will drop or get that quantity of the item.
-.PP
-Typing 'i' gives you an inventory of what you are carrying. When you
-are given a prompt like "Throw [or wield, wear, etc] which item?", you can
-type the letter of the item, or you can type '?' or '*' to get an inventory
-list. '?' lists all appropriate items, while '*' lists all items, appropriate
-or not. When the inventory screen is showing "-more-", to show you that there
-is another page of items, you can type the letter of the item you want instead
-of space or enter.
-.PP
-You can use the adjust command (the '=' key) to change the letters to which
-your possessions are assigned. This command can be used to change spell
-letters as well.
-.PP
-Some items can be stickycursed, in which case they weld themselves to your
-body when you use them. Such items usually carry some kind of disadvantage: a
-weapon or armour may be damaged or negatively enchanted, while rings can have
-all manner of unpleasant effects on you. If you are lucky, you might find
-magic which can rid you of cursed items.
-.PP
-Items like scrolls, potions and some other types each have a characteristic,
-like a label or a colour, which will let you tell them apart on the basis of
-their function. However, these characteristics change between each game, so
-while in one game every potion of healing may be yellow, in another game they
-might all be purple and bubbly. Once you have discovered the function of such
-an item, you will remember it for the rest of the current game. You can access
-your item discoveries with the '\' key.
-.PP
-A very useful command is the 'V' key, which gives you a description of what an
-item does. This is particularly useful when comparing different types of
-weapons, but don't expect too much information from examining unidentified
-items.
-.PP
-.IP SPELLCASTING
-.PP
-Magical spells are a very important part of surviving in the dungeon. Every
-character class can make use of magical spells, although those who enter the
-dungeon without magical skills must practise by reading scrolls before they
-can attempt spellcasting.
-.PP
-Spells are stored in books, which you will occasionally find in the dungeon.
-Each spell has a Level, which denotes the amount of skill required to use it
-as well as indicating how powerful it may be. You can only memorise a certain
-number of levels of spells; type 'M' to find out how many. When you gain
-experience levels, you can memorise more, and you will need to save up for
-several levels to memorise the more powerful spells. When you cast a spell,
-you temporarily expend some of your magical energy as well as becoming
-hungrier (although more powerful spellcasters hunger less quickly from using
-magic).
-.PP
-High level spells are difficult to cast, and you may miscast them every once
-in a while (resulting in a waste of magic and possibly dangerous side-
-effects). Your chance of failing to cast a spell properly depends on your your
-skills, your intelligence, the level of the spell and whether you are wearing
-heavy armour. Failing to cast a spell exercises your spell skills, but not by
-as much as casting it successfully.
-.PP
-Many of the more powerful spells carry disadvantages or risks; you should read
-the spell description (obtained by reading the spellbook in which you found
-the spell) before casting anything.
-.PP
-Some spells are directional, and require you to enter a direction in the same
-way as you would when shooting a missile or zapping a wand. Some spells
-require the proper materials to be present before they will work; for example,
-to animate a skeleton with the necromantic spell, you must stand on a space
-where a skeleton is on the top of the stack of items.
-.PP
-Be careful of magic-using enemies! Some of them can use magic just as well as
-you, if not better, and often use it intelligently.
-.PP
-.IP MONSTERS
-.PP
-In the caverns of Crawl, you will find a great variety of creatures, many of
-whom would very much like to eat you. To stop them doing this, you will need
-to fight. To attack a monster, stand next to it and move in its direction;
-this makes you attack it with your wielded weapon. Of course, some monsters
-are just too nasty to beat, and you will find that discretion is often the
-better part of valour.
-.PP
-Some monsters can be friendly; friendly monsters will follow you around and
-fight on your behalf (you gain 1/2 the normal experience points for any kills
-they make). You can command your allies using the '!' key, which lets you
-either shout to attract them or tell them who to attack.
-.PP
-.SH ENVIRONMENT VARIABLES
-.IP CRAWL_NAME
-Default name for your character.
-.IP CRAWL_DIR
-The directory where your macros and character dumps are stored.
-.IP CRAWL_RC
-A pointer to the file containing your default settings.
-.PP
-.SH FILES
-.IP "/usr/lib/games/crawl/bone*"
-The bones files.
-.IP "/usr/lib/games/crawl/score"
-The high score list.
-.IP "$CRAWL_DIR/macro.txt"
-The macro resource file.
-.IP "$CRAWL_DIR/morgue.txt"
-A character dump of your last death.
-.IP "$CRAWL_RC, $CRAWL_DIR/init.txt, $HOME/.crawlrc"
-Default settings.
-
-.SH BUGS
-Lots.
-.PP
-Avoid the labyrinth... you may not be able to get out.
-
+To access Crawl's help menu, press '?'. To get the list of all commands,
+press '?' again.
 .SH AUTHORS
 Copyright 1997, 1998, 1999 Linley Henzell
diff --git a/crawl-ref/docs/options_guide.txt b/crawl-ref/docs/options_guide.txt
index 332f6595d5..fde2d1b59e 100644
--- a/crawl-ref/docs/options_guide.txt
+++ b/crawl-ref/docs/options_guide.txt
@@ -630,32 +630,26 @@ By default, only two of the item brands are active (and set to reverse):
    heap_brand, feature_item_brand
 They can be deactivated by setting them to "none".
 
-friend_brand = none
-        Brand friends in some way. This is very helpful for summoners.
-        E.g.
-             friend_brand = hi:green
-        shows friends with a green background. If the friend is itself
-        green, it'll show up as black on green.
-
-neutral_brand = none
+friend_brand = hi:green
+        Brand friends in some way. This is very helpful for summoners. The
+        default setting shows friends with a green background. If the friend is
+        itself green, it'll show up as black on green.
+
+neutral_brand = hi:lightgrey
         Brand neutral monsters in some way. Useful both to get out of
         a neutral monster's path, and to avoid accidentally killing it.
-        E.g.
-             neutral_brand = hi:darkgrey
-        shows neutrals with a dark grey background. Since there are
-        no darkgrey monster glyphs anymore, this works fine.
+        The default setting shows neutrals with a dark grey background. Since
+        there are no darkgrey monster glyphs anymore, this works fine.
 
-stab_brand = none
+stab_brand = hi:blue
         Some deities object to you stabbing monsters. Certain jobs
         specialise in stabbing monsters. Still other characters are
         happy if they spot a monster before the monster spots them. In
         all these cases, it helps to identify monsters that are unaware
         of the character (and hence susceptible to being stabbed) without
-        using the 'x' command. All the normal 'brand' options apply. For
-        example
-             stab_brand = hi:blue
+        using the 'x' command. All the normal 'brand' options apply.
 
-may_stab_brand = none
+may_stab_brand = hi:yellow
         Stabbing may be possible even if the monster is not asleep (if
         it's confused or distracted, for instance). This option brands
         monsters that you *might* be able to stab.
@@ -669,7 +663,7 @@ feature_item_brand = reverse
         are hidden by the feature symbol and the feature symbol is
         branded.
 
-trap_item_brand = none
+trap_item_brand = reverse
         Brands traps that would otherwise be hidden by items. If you
         use this brand, the items on the square are hidden by the trap
         symbol (^) and the trap symbol is branded.
diff --git a/crawl-ref/docs/patch_guide.txt b/crawl-ref/docs/patch_guide.txt
new file mode 100644
index 0000000000..34679dff84
--- /dev/null
+++ b/crawl-ref/docs/patch_guide.txt
@@ -0,0 +1,134 @@
+How to Write a Patch
+====================
+
+The following is a rough guide on how to write patches to the code. It is
+meant to make writing patches easier to inexperienced programmers, but
+following these steps does not guarantee that any patch will actually be
+accepted - that depends entirely on content.
+
+Also, we're talking about Stonesoup here, but the principle could be applied to
+any other program as well. :)
+
+Required tools
+--------------
+At the very least you'll need the source code, and some helpful programs like
+diff and grep. The latter come preinstalled with Unix, whereas Windows users
+will have to download and install them. This may be a bit of work, but is
+totally worth it if you're programming a lot. You can get them at e.g.
+    http://gnuwin32.sourceforge.net/packages/diffutils.htm
+    http://gnuwin32.sourceforge.net/packages/grep.htm
+
+Main steps
+----------
+0.) If you're not interested in coding or have no intention of compiling the
+    game, you can still submit patches for the documentation, descriptions
+    or vaults. In that case, simply ignore the steps relating to compilation
+    and coding. You don't even need the source code for that, instead you can
+    simply use the binary distributation that also contains the relevant
+    text files.
+
+1.) Get the source code, either from the most recent release
+    (http://sourceforge.net/projects/crawl-ref/files/) or use SVN to get the
+    current trunk:
+    svn co https://crawl-ref.svn.sourceforge.net/svnroot/crawl-ref/trunk/crawl-ref trunk
+
+2.) Compile the code. To do this you might have to install a compiler and/or
+    additional libraries. See INSTALL.txt for details. If you have any
+    questions, you can ask for help on crawl-ref-discuss@lists.sourceforge.net.
+
+3.) Once you've got everything set up, you should copy the folder containing
+    the files you're going to change, i.e. docs/, dat/descript/ or the entire
+    source/ folder, as appropriate. This is done so you can later easily create
+    the patch against the original version.
+
+4.) Now you can start tweaking the code. Depending on your coding background
+    you may want to experiment with smaller changes first. If you intend to
+    submit the patch to the dev team, please skim coding_conventions.txt.
+    Following these guidelines will save us some time later when integrating
+    the patch.
+
+5.) Compile again to test your changes.
+
+6.) Once everything works as it should, you can use diff or git to create a
+    patch out of the differences between the two folders, e.g.
+    diff -ur trunk-orig trunk-new > mypatch.diff
+
+    You may want to apply the patch against the unmodified folder to test
+    whether everything worked correctly.
+
+7.) Upload the patch on the patch tracker of Sourceforge at
+    http://sourceforge.net/tracker/?group_id=143991&atid=757515.
+
+    Here it is immensely helpful if you give a summary of what the patch is
+    about. If you created it in response to a bug report or feature request,
+    mention the id, and you might also want to post a reply in said item
+    pointing out your new patch. Please also mention the revision/version you
+    used for patching, e.g. 0.5 or r10078, and anything you think may still
+    need to be improved or modified.
+
+    Thank you! :D
+
+
+Tips
+----
+Tip 1:  The code is rougly divided into files according to functionality that
+        is reflected in the file names, so monstuff.cc, mon-util.cc and
+        mstuff2.cc all handle code relating to monsters, while spl-data.h,
+        spl-cast.cc and spells2.cc deal with spells. Note that related code can
+        still be found in other files, too, but these are a good starting point.
+
+Tip 2:  Start out with the simple, generic stuff where you only have to copy
+        and minimally tweak existing code, and only once that works move on to
+        the more complicated implementations.
+
+Tip 3:  Use grep to find all occurences of a similar instance of the same type
+        as the one you're implementing, e.g.
+            grep GOD_ELYVILON *.cc  when adding a new god, or
+            grep SCR_FOG *.cc  when adding a new scroll.
+
+        That way you'll be able to repurpose a lot of code for your new
+        implementation, and it also helps cut down on coding errors.
+
+
+Example
+-------
+I want to add a spell that creates some kind of clouds. The first similar spell
+I can think of is Mephitic Cloud. I know that this spell is defined as
+SPELL_MEPHITIC_CLOUD (and if I didn't know I could find out by grepping for
+"Mephitic Cloud"), so I type (within the source folder)
+    grep SPELL_MEPHITIC_CLOUD *.h   and
+    grep SPELL_MEPHITIC_CLOUD *.cc
+
+... which tells me that code regarding this spell turns up in enum.h (its
+declaration), mon-spll.h (monsters "casting" the spell), spl-data.h (the
+definition), and ghost.cc (monster spell), it_use3.cc (some kind of misc.
+item, maybe), mstuff2.cc (helpfully with a comment mentioning swamp
+drakes), spl-book.cc (spellbooks that contain this spell), and spl-cast.cc
+(actually casting the spell).
+
+That gives me some ideas on where to start looking at code to duplicate
+for my new spell. I'd start out with the basics, the declaration and
+definition, copying all values from Mephitic Cloud and only changing the
+SPELL_xxxx tag. Then I add the new spell to the list in spl-cast.cc, at which
+point I'll also notice that Mephitic Cloud uses a function called
+stinking_cloud() and that various other cloud spells (helpfully sorted by
+effect type) use functions like cast_big_c() and others. Using grep I can
+quickly find out that both functions are declared in spells1.h, meaning their
+definitions can be found in spells1.cc.
+
+stinking_cloud() contains a definition of a beam that defines damage and
+such. The various properties are not self-explanatory but they're also not
+totally obscure, so you should be able to find out a lot about them by just
+fiddling with the values. In particular, beam.flavour is set to something
+called BEAM_POTION_STINKING_CLOUD which looks interesting enough to check
+out, so I grep the source (*.h and *.cc) for all occurences and have a look
+at all files this turns up. And so on.
+
+Evaluating and prioritising the findings takes some experience with the source
+code but even if you have no idea what the files are likely to contain using
+grep still greatly reduces the number of files you have to look at. To find
+the code you're interested in search the files for the same keyword you used
+for grepping.
+
+Good luck with your patch! If you have any questions, don't hesitate to ask.
+Thank you for your support!
diff --git a/crawl-ref/source/acr.cc b/crawl-ref/source/acr.cc
index 02ba4c55d7..398d694231 100644
--- a/crawl-ref/source/acr.cc
+++ b/crawl-ref/source/acr.cc
@@ -294,6 +294,7 @@ int main( int argc, char *argv[] )
 static void _show_commandline_options_help()
 {
     puts("Command line options:");
+    puts("  -help            prints this list of options");
     puts("  -name <string>   character name");
     puts("  -race <arg>      preselect race (by letter, abbreviation, or name)");
     puts("  -class <arg>     preselect class (by letter, abbreviation, or name)");
@@ -307,7 +308,7 @@ static void _show_commandline_options_help()
     puts("Command line options override init file options, which override");
     puts("environment options (CRAWL_NAME, CRAWL_DIR, CRAWL_RC).");
     puts("");
-    puts("Highscore list options: (Can now be redirected to more, etc)");
+    puts("Highscore list options: (Can be redirected to more, etc)");
     puts("  -scores [N]            highscore list");
     puts("  -tscores [N]           terse highscore list");
     puts("  -vscores [N]           verbose highscore list");
diff --git a/crawl-ref/source/dat/database/FAQ.txt b/crawl-ref/source/dat/database/FAQ.txt
index 4df69f4124..35ecbc65ab 100644
--- a/crawl-ref/source/dat/database/FAQ.txt
+++ b/crawl-ref/source/dat/database/FAQ.txt
@@ -345,6 +345,9 @@ your suggestions under Feature Requests and wait for people to become
 enthusiastic and give feedback before you submit a patch. If you want,
 you can also write a patch that implements an existing FR or fixes a bug.
 
+If you'd like to write a patch but don't know how to go about it,
+patch_guide.txt in the docs/ folder is the file for you.
+
 We really appreciate your help!
 %%%%
 Q:help
@@ -411,6 +414,36 @@ the change log in docs/changes.stone_soup.
 ##############################################
 # Questions about the Tiles version
 ##############################################
+Q:tiles lag
+
+The tiles version is awfully slow on Windows! What can I do to improve that?
+%%%%
+A:tiles lag
+
+First, we're really sorry about that! Stonesoup 0.5 was tested on several
+systems and the gigantic lag on some Windows systems was completely unexpected.
+
+Crawl 0.5 renders graphics using OpenGL and SDL. For most video cards, this
+should be faster than the 0.4 version. However, the default driver that ships
+with Windows is extremely slow. If you are having performance problems, be sure
+to update your video card driver as a first step.
+
+We're working on a solution for this problem, but in the meantime you can try
+to see whether tweaking some options will improve performance. See
+docs/tiles_help.txt for details. If things are still too laggy after all of
+that, you'll have to either continue playing 0.4.5 until the problem has been
+solved, or you could try the non-graphical console version.
+
+We'd like to apologize for the grief that this has caused some players, but we
+hope that it's understandable that making this change in 0.5 has allowed a lot
+of graphical improvements: Uniques get on-screen names. All monsters get health
+bars. Graphical menus. Full screen mode. Eee PC support.
+None of those things would have been possible in previous tiles versions. On
+top of that, if you have an adequate driver 0.5 can often be faster than 0.4,
+because the GPU can easily do the work that used to take the CPU a lot of time.
+
+At any rate, it'll be fixed.  Just be patient.  :)
+%%%%
 Q:tiles online
 
 Can I play Tiles online?
@@ -457,3 +490,18 @@ A:tiles options
 A: Yes. Play around with the options in settings/tiles_options.txt until
 you are satisfied.
 %%%%
+Q:tiles doll
+
+Why can I no longer change the look of my character?
+%%%%
+A:tiles doll
+
+That feature got broken when we transitioned to openGL and needs to be
+reimplemented. It will come back, but we can't say, when.
+
+In the meantime we've implemented a really basic menu (still '-') that lets
+you choose between the default look according to job, equipment mode and one
+of a number of predefined dolls.
+
+Sorry about that!
+%%%%
diff --git a/crawl-ref/source/decks.cc b/crawl-ref/source/decks.cc
index 1659903d9b..825ce9601f 100644
--- a/crawl-ref/source/decks.cc
+++ b/crawl-ref/source/decks.cc
@@ -2687,7 +2687,7 @@ static void _summon_demon_card(int power, deck_rarity_type rarity)
     // This hack appears later in this file as well.
     if (create_monster(
             mgen_data(summon_any_demon(dct), BEH_FRIENDLY,
-                      std::min(power / 50, 6), 0,
+                      std::min(power/50 + 1, 6), 0,
                       you.pos(), MHITYOU),
             false) == -1)
     {
@@ -2835,7 +2835,7 @@ static void _summon_flying(int power, deck_rarity_type rarity)
         create_monster(
             mgen_data(result,
                       friendly ? BEH_FRIENDLY : BEH_HOSTILE,
-                      std::min(power / 50, 6), 0,
+                      std::min(power/50 + 1, 6), 0,
                       you.pos(), MHITYOU));
     }
 }
@@ -2850,7 +2850,7 @@ static void _summon_skeleton(int power, deck_rarity_type rarity)
 
     if (create_monster(mgen_data(skeltypes[power_level],
                                  friendly ? BEH_FRIENDLY : BEH_HOSTILE,
-                                 std::min(power / 50, 6), 0,
+                                 std::min(power/50 + 1, 6), 0,
                                  you.pos(), MHITYOU),
                        false) == -1)
     {
@@ -2872,7 +2872,7 @@ static void _summon_ugly(int power, deck_rarity_type rarity)
 
     if (create_monster(mgen_data(ugly,
                                  friendly ? BEH_FRIENDLY : BEH_HOSTILE,
-                                 std::min(power / 50, 6), 0,
+                                 std::min(power/50 + 1, 6), 0,
                                  you.pos(), MHITYOU),
                        false) == -1)
     {
diff --git a/crawl-ref/source/initfile.cc b/crawl-ref/source/initfile.cc
index b5696e5daa..8c04d4c972 100644
--- a/crawl-ref/source/initfile.cc
+++ b/crawl-ref/source/initfile.cc
@@ -655,6 +655,9 @@ void game_options::reset_options()
 #if !defined(SHORT_FILE_NAMES) && !defined(SAVE_DIR_PATH)
     morgue_dir = "morgue/";
 #endif
+
+    macro_dir = "settings/";
+
     additional_macro_files.clear();
 
     player_name.clear();
@@ -877,15 +880,15 @@ void game_options::reset_options()
     sc_entries             = 0;
     sc_format              = -1;
 
-    friend_brand       = CHATTR_NORMAL;
-    neutral_brand      = CHATTR_NORMAL;
-    stab_brand         = CHATTR_NORMAL;
-    may_stab_brand     = CHATTR_NORMAL;
+    friend_brand       = CHATTR_HILITE | (GREEN << 8);
+    neutral_brand      = CHATTR_HILITE | (LIGHTGREY << 8);
+    stab_brand         = CHATTR_HILITE | (BLUE << 8);
+    may_stab_brand     = CHATTR_HILITE | (YELLOW << 8);
     heap_brand         = CHATTR_REVERSE;
     feature_item_brand = CHATTR_REVERSE;
-    trap_item_brand    = CHATTR_NORMAL;
+    trap_item_brand    = CHATTR_REVERSE;
 
-    no_dark_brand    = true;
+    no_dark_brand      = true;
 
 #ifdef WIZARD
     wiz_mode         = WIZ_NO;
@@ -3406,6 +3409,7 @@ enum commandline_option_type {
     CLO_MACRO,
     CLO_MAPSTAT,
     CLO_ARENA,
+    CLO_HELP,
 
     CLO_NOPS
 };
@@ -3413,7 +3417,7 @@ enum commandline_option_type {
 static const char *cmd_ops[] = {
     "scores", "name", "species", "job", "plain", "dir", "rc",
     "rcdir", "tscores", "vscores", "scorefile", "morgue", "macro",
-    "mapstat", "arena"
+    "mapstat", "arena", "help"
 };
 
 const int num_cmd_ops = CLO_NOPS;
@@ -3464,7 +3468,7 @@ bool parse_args( int argc, char **argv, bool rc_only )
             return (false);
         }
 
-        // look for match (now we also except --scores)
+        // Look for match (we accept both -option and --option).
         if (arg[1] == '-')
             arg = &arg[2];
         else
@@ -3472,10 +3476,12 @@ bool parse_args( int argc, char **argv, bool rc_only )
 
         int o;
         for (o = 0; o < num_cmd_ops; o++)
-        {
-             if (stricmp(cmd_ops[o], arg) == 0)
-                 break;
-        }
+            if (stricmp(cmd_ops[o], arg) == 0)
+                break;
+
+        // Print the list of commandline options for "--help".
+        if (o == CLO_HELP)
+            return (false);
 
         if (o == num_cmd_ops)
         {
@@ -3484,22 +3490,22 @@ bool parse_args( int argc, char **argv, bool rc_only )
             return (false);
         }
 
-        // disallow options specified more than once.
+        // Disallow options specified more than once.
         if (arg_seen[o] == true)
             return (false);
 
-        // set arg to 'seen'
+        // Set arg to 'seen'.
         arg_seen[o] = true;
 
-        // partially parse next argument
+        // Partially parse next argument.
         bool next_is_param = false;
-        if (next_arg != NULL)
+        if (next_arg != NULL
+            && (next_arg[0] != '-' || strlen(next_arg) == 1))
         {
-            if (next_arg[0] != '-' || strlen(next_arg) == 1)
-                next_is_param = true;
+            next_is_param = true;
         }
 
-        //.take action according to the cmd chosen
+        // Take action according to the cmd chosen.
         switch (o)
         {
         case CLO_SCORES:
@@ -3616,7 +3622,7 @@ bool parse_args( int argc, char **argv, bool rc_only )
             break;
 
         case CLO_RCDIR:
-            // Always parse
+            // Always parse.
             if (!next_is_param)
                 return (false);
 
@@ -3625,7 +3631,7 @@ bool parse_args( int argc, char **argv, bool rc_only )
             break;
 
         case CLO_DIR:
-            // ALWAYS PARSE
+            // Always parse.
             if (!next_is_param)
                 return (false);
 
@@ -3634,16 +3640,20 @@ bool parse_args( int argc, char **argv, bool rc_only )
             break;
 
         case CLO_RC:
-            // ALWAYS PARSE
+            // Always parse.
             if (!next_is_param)
                 return (false);
 
             SysEnv.crawl_rc = next_arg;
             nextUsed = true;
             break;
-        } // end switch -- which option?
 
-        // update position
+        case CLO_HELP:
+            // Shouldn't happen.
+            return (false);
+        }
+
+        // Update position.
         current++;
         if (nextUsed)
             current++;
diff --git a/crawl-ref/source/monstuff.cc b/crawl-ref/source/monstuff.cc
index f27863db70..765cf04b97 100644
--- a/crawl-ref/source/monstuff.cc
+++ b/crawl-ref/source/monstuff.cc
@@ -1443,9 +1443,11 @@ int monster_die(monsters *monster, killer_type killer,
             {
                 bool notice = false;
 
-                monsters *killer_mon = &menv[killer_index];
+                monsters *killer_mon = NULL;
                 if (!anon)
                 {
+                    killer_mon = &menv[killer_index];
+
                     // If the killer is already dead treat it like an
                     // anonymous monster.
                     if (killer_mon->type == -1)
diff --git a/crawl-ref/source/newgame.cc b/crawl-ref/source/newgame.cc
index 81e6ef8a1f..9422d3008f 100644
--- a/crawl-ref/source/newgame.cc
+++ b/crawl-ref/source/newgame.cc
@@ -2854,7 +2854,7 @@ static void _jobs_stat_init(job_type which_job)
 
     case JOB_WANDERER:          s =  2; i =  2; d =  2; hp = 11; mp = 1; break;
 
-    case JOB_ARTIFICER:         s =  2; i =  3; d =  4; hp = 13; mp = 0; break;
+    case JOB_ARTIFICER:         s =  2; i =  3; d =  4; hp = 13; mp = 1; break;
     default:                    s =  0; i =  0; d =  0; hp = 10; mp = 0; break;
     }
 
diff --git a/crawl-ref/source/player.cc b/crawl-ref/source/player.cc
index 8152b5d9f2..8e52ec611d 100644
--- a/crawl-ref/source/player.cc
+++ b/crawl-ref/source/player.cc
@@ -327,6 +327,7 @@ bool move_player_to_grid( const coord_def& p, bool stepped, bool allow_shift,
     command_type stair_dir = grid_stair_direction(new_grid);
 
     if (stepped && stair_dir != CMD_NO_CMD
+        && new_grid != DNGN_ENTER_SHOP
         && you.duration[DUR_REPEL_STAIRS_MOVE])
     {
         int pct;