Clean up the change log a bit, and modify the monster speech

documentation.


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

1 files changed, 116 insertions, 105 deletions

diff --git a/crawl-ref/docs/monster_speech.txt b/crawl-ref/docs/monster_speech.txt
index 7ec8d92151..f8236166be 100644
--- a/crawl-ref/docs/monster_speech.txt
+++ b/crawl-ref/docs/monster_speech.txt
@@ -2,15 +2,15 @@ Overview
 ========
 
 As of Dungeon Crawl Stone Soup 0.3 the previously hard-coded monster
-speech has been outsourced by Matthew Cline. This makes changing 
-existing messages, or adding new ones really easy. This file will
-hopefully help you in this endeavour.
+speech has been outsourced. This makes changing existing messages,
+or adding new ones really easy. This file will hopefully help you in
+this endeavour.
 
 The outsourced messages are used to create two databases out of which
-Crawl randomly draws the necessary speech text. 
+Crawl randomly draws the necessary speech text.
 
-* shout.db (handling speech when monsters first notice you), and 
-* speak.db (for all other cases). 
+* shout.db (handling speech when monsters first notice you), and
+* speak.db (for all other cases).
 
 Because of the amount of definitions necessary, they have been divided
 over a number of different files.
@@ -18,25 +18,25 @@ over a number of different files.
 The shout database is constructed from the following two files:
 
 * shout.txt     handles message output for monsters noticing you
-* insult.txt    handles insults thrown at you by imps and demons 
+* insult.txt    handles insults thrown at you by imps and demons
 
 The speak database contains messages defined in these files:
 
 * monspeak.txt  handles messages for monsters communicating with you
 * wpnnoise.txt  handles randart weapons with the noises property
-* godspeak.txt  handles randomized speech by the gods, as well as 
+* godspeak.txt  handles randomized speech by the gods, as well as
                 speech used for some divine abilities
 * insult.txt    Same file as above.
 
-The messages defined in insult.txt form a part of both databases. 
-Apart from that, keywords and statements defined for one database 
-cannot be automatically accessed from the other. Rather, they have to 
+The messages defined in insult.txt form a part of both databases.
+Apart from that, keywords and statements defined for one database
+cannot be automatically accessed from the other. Rather, they have to
 be defined a second time.
 
 Whenever Dungeon Crawl is started, the game checks whether any of the
 databases needs to be updated. If one of the underlying files has been
-changed since the last check, the database is automatically rerolled. 
-That means that if you'd like to change one of the descriptions or add 
+changed since the last check, the database is automatically rerolled.
+That means that if you'd like to change one of the descriptions or add
 some new monster speech all you have to do is modify the file, save,
 and restart the game to test your changes.
 
@@ -54,12 +54,12 @@ Contents:
 A.  Monster speech probabilities
 ================================
 
-Not all monsters are equally likely to speak. Rather there are 
+Not all monsters are equally likely to speak. Rather there are
 different chances involved, depending on several attributes, and most
 of the time the database lookup stage isn't even reached.
 
-First, the player will only ever hear monsters speak if they are in 
-line of sight, and monsters will only ever speak if they are not 
+First, the player will only ever hear monsters speak if they are in
+line of sight, and monsters will only ever speak if they are not
 asleep, not submerged in water, air or lava, and not wandering around 
 aimlessly (unless neutral).
 
@@ -78,10 +78,10 @@ if the monster in question was generated as a member of a group.
 Chances are again doubled if this non-humanoid monster is fleeing, and
 doubled again if confused.
 
-Neutral monsters only speak half as often, and for charmed monsters 
-the probability is divided by 3. The same applies to silenced 
-monsters, i.e. monsters that are not naturally silent will only get to 
-even attempt to speak in one out of three tries where the above 
+Neutral monsters only speak half as often, and for charmed monsters
+the probability is divided by 3. The same applies to silenced
+monsters, i.e. monsters that are not naturally silent will only get to
+even attempt to speak in one out of three tries where the above
 chances hold.
 
 Note that the definition of which monsters are capable of speech is
@@ -129,8 +129,8 @@ are comment lines.
   friendly '5'
 
 The first non-comment, non-blank line is interpreted as the key of an
-entry. Many keys are hardcoded, but there's place for user defined 
-ones as well. More on that later, though. 
+entry. Many keys are hardcoded, but there's place for user defined
+ones as well. More on that later, though.
 In this case, the key is "friendly '5'".
 
 '5' refers to the monster glyph, so the speech will not be entirely
@@ -183,7 +183,7 @@ attributes as prefixes.
 speech from "hostile" or "neutral". All prefixes are optional and
 tested in the following order:
 
-  default <attitude> fleeing silenced confused [related] <player god> 
+  default <attitude> fleeing silenced confused [related] <player god>
 
 where <attitude> can be any of friendly, neutral or hostile. Note that
 the game generally treats neutral monsters like hostiles since they
@@ -191,7 +191,7 @@ still pose a danger to players.
 
 The prefix "related" is added if the player and the monster share the
 same genus, e.g. if you're playing a Sludge Elf, and the monster in
-question is a deep elf blademaster, you both are Elves and the monster
+question is a deep elf blademaster, you both are elves and the monster
 speech may reflect that. It's currently only used for friendly
 humanoids who will now sometimes mention that you're family, if you
 are. Stupid monsters, i.e. animals, will judge your relatedness status
@@ -206,9 +206,9 @@ orc species and the character worships Beogh, the prefix "beogh" gets
 added to the list, though not for charmed orcs who will simply use the
 generic friendly statements instead of the orcish followers' cheers.
 If you worship one of the good gods instead (Zin, The Shining One, or
-Elyvilon) the prefix "good god" is used. Conversely, worshippers of 
+Elyvilon) the prefix "good god" is used. Conversely, worshippers of
 one of the evil gods (Yredelemnul, Makhleb, Kikubaaqudgha, Lugonu, or
-Beogh) will use the prefix "evil god". 
+Beogh) will use the prefix "evil god".
 
 This allows fine-grained handling of monsters depending on your
 character's religion status, e.g. orcs will use special speech for
@@ -217,7 +217,7 @@ shout messages of encouragement to followers of the good gods, while
 demons will attempt to slander the good gods.
 
 Once the entire set of prefixes has been determined, we only need
-to add the monster name and start the database search. 
+to add the monster name and start the database search.
 
 First we search for the complete prefix string in combination with the
 monster name. Then we try omitting some very specific prefixes that
@@ -236,16 +236,16 @@ general.
 
 In practice this means that database keys starting with "default" are
 the fallback solution if the exact look-up has failed. As such, the
-messages should be generic enough to allow for all the possibly 
-skipped prefixes, or else those cases should be caught earlier, e.g. 
-if you have "default friendly humanoid", you should also define 
-"default friendly fleeing humanoid" and "default friendly confused 
-humanoid" (and possibly both combined) even if only with "__NONE" 
-(stay silent), as the general friendly messages may look odd for a 
+messages should be generic enough to allow for all the possibly
+skipped prefixes, or else those cases should be caught earlier, e.g.
+if you have "default friendly humanoid", you should also define
+"default friendly fleeing humanoid" and "default friendly confused
+humanoid" (and possibly both combined) even if only with "__NONE"
+(stay silent), as the general friendly messages may look odd for a
 monster such afflicted.
 
 Only keys that match a search string perfectly (ignoring case) will
-be used. Once all prefixes have been exhausted and still no match has 
+be used. Once all prefixes have been exhausted and still no match has
 been found, the database lookup will try for a more general monster
 description. There are several possible ways this is attempted, in the
 following order:
@@ -263,19 +263,19 @@ following order:
    latter is entirely hardcoded, though.
    Examples: "default winged insect", "default confused humanoid"
 
-If you are playing with tiles, you may not know the monster glyphs, 
-but internally the monsters are still treated the same, and even under 
-tiles, the glyph keys used for step 3 are entirely valid. In case you 
-need to know the monster glyphs for your speech definitions you'll 
-find a list of monster glyphs at the end of this file. Also, for many 
-monsters you can find out their glyph in-game by searching the 
-database ('?/') and entering a vague enough monster name. For example, 
+If you are playing with tiles, you may not know the monster glyphs,
+but internally the monsters are still treated the same, and even under
+tiles, the glyph keys used for step 3 are entirely valid. In case you
+need to know the monster glyphs for your speech definitions you'll
+find a list of monster glyphs at the end of this file. Also, for many
+monsters you can find out their glyph in-game by searching the
+database ('?/') and entering a vague enough monster name. For example,
 entering "drac" will tell you that all draconians use the symbol 'd'.
 
 Note that changing monster glyphs using the mon_glyph option may also
 affect speech of this kind.
 
-For the last round (shape comparison, e.g. winged humanoid)
+For the last round (shape comparison, e.g. "winged humanoid")
 occasionally an additional intelligence estimate ("stupid", "smart")
 is prefixed to the search string, depending on the monster type, e.g. 
 a "stupid humanoid" may still be smarter than a "smart arachnid".
@@ -299,7 +299,7 @@ Examples
 Example 1: 
   The monster we want to make "speak" is a "confused killer bee".
 
-  However, such an entry cannot be found in the database, so the game  
+  However, such an entry cannot be found in the database, so the game
   tries first for "default confused killer bee", then "default killer
   bee", neither of which yields any results.
   The monster genus is also plain "killer bee", so that doesn't help
@@ -318,11 +318,11 @@ Example 2:
   wizard".
 
   This obviously made up example also has no direct equivalent in the
-  database, so first we try to remove the less important prefixes, in 
+  database, so first we try to remove the less important prefixes, in
   this case "related" and "beogh". Unfortunately, none of "friendly
   fleeing related orc wizard", "friendly fleeing beogh orc wizard", or
   "friendly fleeing orc wizard" has any corresponding entry in the
-  database, so that we now check for "default" in combination with, 
+  database, so that we now check for "default" in combination with,
   one after another, all combinations of three or less prefixes.
 
   Three prefixes: "default friendly fleeing related orc wizard",
@@ -338,24 +338,24 @@ Example 2:
   One prefix: "default friendly orc wizard", "default fleeing orc
   wizard", "default related orc wizard", "default beogh orc wizard".
 
-  No prefix: "default orc wizard". 
+  No prefix: "default orc wizard".
 
   Sadly, none of these is successful. The genus of orc wizards is
-  "orc", so we retry the above using "orc" instead of "orc wizard". 
+  "orc", so we retry the above using "orc" instead of "orc wizard".
   The same is repeated for "friendly fleeing beogh 'o'", and we still
   haven't found anything.
 
   This is starting to get ridiculous, so it's time for desperate
-  measures: 
+  measures:
 
-  With the help of some rather complicated functions the game works 
+  With the help of some rather complicated functions the game works
   out that orcs can be described as humanoids of average intelligence.
   Thus, in a final attempt of making this orc wizard speak, we search
-  the database for "friendly fleeing related beogh humanoid", 
-  something that, not surprisingly (since Beogh and humanoid don't go 
-  well together), doesn't exist. Annoyingly enough, neither do the 
-  variants "friendly fleeing related humanoid", "friendly fleeing 
-  beogh humanoid" or even "friendly fleeing humanoid". 
+  the database for "friendly fleeing related beogh humanoid",
+  something that, not surprisingly (since Beogh and humanoid don't go
+  well together), doesn't exist. Annoyingly enough, neither do the
+  variants "friendly fleeing related humanoid", "friendly fleeing
+  beogh humanoid" or even "friendly fleeing humanoid".
 
   Still, we haven't yet tried the prefix combinations: "default
   friendly fleeing related humanoid" is still unsuccessful, as
@@ -381,15 +381,22 @@ VISUAL:@The_monster@ tries to hide somewhere.
 
 Weapon speech
 -------------
-
 For obvious reasons, weapon noises get by without any such prefixes,
 and the only hardcoded keywords are "noisy weapon" for weapons with
 the noises property, and "singing sword" for (who'd have guessed?) the
 Singing Sword.
 
+Special monster speech
+----------------------
+Rarely, monster speech will also rely on hard-coded keys, such as
+Boris' "return_speech". If such a hard-coded key is changed or removed,
+the speech in question will simply not be printed. This may look odd in
+the game, but will have no other effect. Sometimes, default messages
+will be output instead.
+
 God speech
 ----------
-The keys used to search for god speech are entirely hard-coded, though 
+The keys used to search for god speech are entirely hard-coded, though
 some local synonyms have been defined as well. Hopefully, the comments
 will explain what the different speech messages are used for.
 
@@ -421,8 +428,8 @@ Values can contain variable references, which look like text
 surrounded by @@. These variables may be defined by entries in
 shout.txt for the shouting database, or monspeak.txt or one of the
 other files for the speech database, in which case they are replaced
-with a random value from the entry; or they may have hardcoded
-expansions defined by the game.
+with a random value from the entry in question; or they may have
+hardcoded expansions defined by the game.
 
 Note that variable replacement is recursive, so be careful to avoid
 infinite loops. Though the game will abort after a number of
@@ -442,16 +449,16 @@ The following variables are hardcoded:
 @a_something@   : similar
 @the_something@ : similar
 @player_name@   : Player name.
-@player_species@: Player base species, with Draconian rather than the 
+@player_species@: Player base species, with Draconian rather than the
                   actual subtype.
 @player_genus@  : Player genus, i.e. "Elf" rather than the exact type,
                   or "Ogre" instead of "Ogre-Mage".
 @player_genus_plural@ : pluralised genus form.
 @player_god@    : Player's god name, or "you" if non-religious.
 @Player_god@    : Player's god name, or "You" if non-religious.
-@god_is@        : replaced with "<god name> is" or "you are", if 
+@god_is@        : replaced with "<god name> is" or "you are", if
                   non-religious.
-@God_is@        : replaced with "<god name> is" or "You are", if 
+@God_is@        : replaced with "<god name> is" or "You are", if
                   non-religious.
 @surface@       : Whatever the monster is standing on.
 @feature@       : The monster's square's feature description.
@@ -485,10 +492,10 @@ replacements don't hold. Instead you can use @The_weapon@,
 @the_weapon@, @Your_weapon@, @your_weapon@ and @weapon@ which will get
 replaced by "The (weapon name)", "the (weapon name)", "Your (weapon
 name)", "your (weapon name)", and the plain weapon name,
-respectively. 
+respectively.
 
-Note that the Singing Sword, being unique, cannot be referred to by 
-the possessive variants, so they will be replaced with the appropriate 
+Note that the Singing Sword, being unique, cannot be referred to by
+the possessive variants, so they will be replaced with the appropriate
 definite article ones.
 
 Examples of pre-defined variables in the database include
@@ -544,16 +551,16 @@ and enforce output even when silenced.
   VISUAL SPELL   : MSGCH_MONSTER_SPELL
   VISUAL WARN    : MSGCH_WARN
 
-Note, though, that these only will take effect if a VISUAL message 
-just happens to be chosen. As stated above, the database search 
-doesn't really care whether a monster is supposed to be silent, so it 
-may pick any noisy monster speech, but the message output will care 
-and refuse to print such nonsense, so that in this case the monster 
-will actually stay silent after all. 
+Note, though, that these only will take effect if a VISUAL message
+just happens to be chosen. As stated above, the database search
+doesn't really care whether a monster is supposed to be silent, so it
+may pick any noisy monster speech, but the message output will care
+and refuse to print such nonsense, so that in this case the monster
+will actually stay silent after all.
 
-All in all, chances of silent "speech" are lower (as is intended) but
-only VISUAL messages even have a chance to be printed under these 
-circumstances.
+To summarize, chances of silent "speech" are overall lower (as is
+intended) but only VISUAL messages even have a chance to be printed
+under these circumstances.
 
 As explained earlier, "silenced" is one of the prefixes that are
 regarded as "less important" and can be ignored in the exact string
@@ -578,7 +585,7 @@ Killer Klown
 
 ...
 
-  none of which, if chosen, would actually be printed, but luckily the 
+  none of which, if chosen, would actually be printed, but luckily the
   "Killer Klown" entry also contains VISUAL statements like the
   following:
 
@@ -593,7 +600,7 @@ VISUAL:@The_monster@ does a flip.
   If one of these is chosen, we get a non-verbal "speech" statement of
   this silenced monster.
 
-  However, what happens if the other 50% take effect and we will *not* 
+  However, what happens if the other 50% take effect and we will *not*
   ignore the "silenced" prefix? In this case, we'll simply continue
   like in the earlier examples above, get no results for either of
   "default silenced Killer Klown" or "default Killer Klown", and try
@@ -621,11 +628,15 @@ VISUAL:@The_monster@ gestures.
 
 For shouts the default channel is also MSGCH_TALK, which is
 automatically changed to MSGCH_TALK_VISUAL for monsters that can't
-speak (animals, usually), and manually set to MSGCH_SOUND for all 
+speak (animals, usually), and manually set to MSGCH_SOUND for all
 those variants of "You hear a shout!"
 
+Monster spells and enchantments will only interrupt resting/running
+if done by a non-friendly creature, and, as stated above, messages
+passed through the TALK or SOUND channels never will.
+
 For weapon noises only a subset of the above is relevant, as anything
-including VISUAL and the channel keys SPELL and ENCHANT are considered
+including VISUAL and the channel keys SPELL and ENCHANT is considered
 invalid and will trigger a default message instead. Again, the default
 channel is MSGCH_TALK.
 
@@ -653,10 +664,10 @@ E.  Testing your changes
 ========================
 
 Get a version of Stone Soup that contains WIZARD mode. You can check
-whether this is the case by pressing '&' during the game. If you are
-told that this is an "unknown command" (likely, since WIZARD builds
-are generally not distributed), you will have to compile the game for
-yourself.
+whether this is the case by reading the in-game version information
+('?v'). If Wizard mode is not listed among the included features
+(likely, since WIZARD builds are generally not distributed), you will
+have to compile the game for yourself.
 
 To build Crawl yourself, download the source code from the Crawl
 homepage [1] and read the "INSTALL" file in the main directory for
@@ -664,11 +675,11 @@ instructions. Should you still have any questions after reading the
 documentation and checking the archives of the Crawl newsgroup [2],
 ask away!
 
-If you have WIZARD mode compiled in, you can simply answer "yes" to
-the safety question resulting from pressing '&', and then test to your
-heart's content. Pressing '&' followed by a number of other keys will
-execute wizard mode commands that are all listed in the wizard help
-menu (press '&?').
+If you have WIZARD mode compiled in, you can access special wizard
+commands by pressing '&'. First answer "yes" to the safety question
+and then you can test to your heart's content. Pressing '&' followed
+by a number of other keys will execute wizard mode commands that are
+all listed in the wizard help menu (press '&?').
 
 In particular, you can create a monster with '&M', and enforce
 behaviour on a monster by examining it (with 'x', as usual). In wizard
@@ -676,8 +687,8 @@ mode, examining monsters offers several new sub-commands such as 'F'
 (make monster friendly/neutral/hostile) and 's' (make monster shout).
 These last two are of particular interest to monster speech designers.
 
-Also, the Singing Sword and all other hardcoded artefacts can be 
-created with '&|'. The Elemental Staff and the spear of Voo-Doo are 
+Also, the Singing Sword and all other hardcoded artefacts can be
+created with '&|'. The Elemental Staff and the spear of Voo-Doo are
 examples of noisy weapons.
 
 You can also temporarily increase the likelihood of a given message by
@@ -685,19 +696,19 @@ adding a high weight value before it, e.g. w:5000, or equally
 temporarily push it into another channel (e.g. MSGCH_WARN) to make it
 more noticeable.
 
-If you successfully got Crawl compiled, you can easily enable more 
-detailed debug information. All you need to do is add 
+If you successfully got Crawl compiled, you can easily enable more
+detailed debug information. All you need to do is add
 
   #define DEBUG_MONSPEAK
 
 somewhere in AppHdr.h, for example at the beginning of the section
 entitled "Debugging Defines", and then compile the game anew, first
-using "make clean", then "make wizard". 
-If you play with DEBUG_MONSPEAK compiled in, whenever the game is 
-searching the monspeak database you'll get extensive information on 
-all keys and prefixes tried. Once you're done testing don't forget to 
+using "make clean", then "make wizard".
+If you play with DEBUG_MONSPEAK compiled in, whenever the game is
+searching the monspeak database you'll get extensive information on
+all keys and prefixes tried. Once you're done testing don't forget to
 remove (or comment out) the DEBUG_MONSPEAK setting as trying to
-actually play that way would sure be annoying. 
+actually play that way would sure be annoying.
 
 
 F.  Publishing your changes
@@ -713,9 +724,9 @@ request on sourceforge.net [1] or in the newsgroup [2].
    http://sourceforge.net/projects/crawl-ref
 
 .. [2] rec.games.roguelike.misc
-   Since this newsgroup is being shared with a number of other 
-   roguelike games, it is generally considered polite to flag 
-   subjects of posts pertaining only to Crawl with "-crawl-" or 
+   Since this newsgroup is being shared with a number of other
+   roguelike games, it is generally considered polite to flag
+   subjects of posts pertaining only to Crawl with "-crawl-" or
    a similar marker.
 
 
@@ -735,14 +746,14 @@ h   all hounds (jackal, hound, wolf, warg, war dog, hell hound)
         and hogs (hog, hell-hog)
 j   snails: elephant slug, giant slug, giant snail
 k   winged insects: killer bee, bumblebee
-l   lizards (giant newt/gecko/iguana/lizard, gila monster, komodo 
-             dragon), and drakes (swamp drake, firedrake, death drake, 
-                                  lindwurm)
+l   lizards (giant newt/gecko/iguana/lizard, gila monster, komodo
+             dragon),
+        and drakes (swamp drake, firedrake, death drake, lindwurm)
 n   ghouls: necrophage, ghoul, rotting hulk
 o   all orcs
 p   all ghosts, phantom, and insubstantial wisp
 r   all rodents (rats of all colours, and quokka)
-s   arachnides (giant mite, giant centipede, scorpion, wolf spider, 
+s   arachnides (giant mite, giant centipede, scorpion, wolf spider,
                 redback)
 t   minotaur
 u   (very) ugly thing
@@ -764,7 +775,7 @@ F   all frogs
 G   all eyes, giant spore, and giant orange brain
 H   hippogriff, manticore, griffon, and sphinx
 I   ice beast
-J   all jellies, oozes, and slime creature, pulsating lump, 
+J   all jellies, oozes, and slime creature, pulsating lump,
     giant amoeba, jellyfish, and acid blob
 K   all kobolds
 L   all liches
@@ -787,10 +798,10 @@ Numbers:
 --------
 1   all Fiends, Executioner, Blue/Green Death, Balrug, Cacodemon
 2   sun demon, reaper, soul eater, ice devil, and Lorocyproca
-3   hellion, tormentor, blue/iron devil, neqoxec, orange/shadow demon, 
+3   hellion, tormentor, blue/iron devil, neqoxec, orange/shadow demon,
     hellwing, ynoxinul, and demonic crawler
 4   red/rotting/hairy devil, beast, and smoke demon
-5   all imps, and other minor demons (quasit, lemure, ufetubus, manes, 
+5   all imps, and other minor demons (quasit, lemure, ufetubus, manes,
                                       midge)
 8   all golems, and living statues
 9   all gargoyles