Added documentation to rpsystem

evennia/contrib/rpsystem.py

@@ -1,36 +1,51 @@
 """
-RP base system for Evennia
+Roleplaying base system for Evennia
 
 Contribution - Griatch, 2015
 
+This module contains the ContribRPObject, ContribRPRoom and
+ContribRPCharacter typeclasses.  If you inherit your
+objects/rooms/character from these (or make them the defaults) from
+these you will get the following features:
 
-This RP base system introduces the following features to a game,
-common to many RP-centric games:
+    - Objects/Rooms will get the ability to have poses and will report
+    the poses of items inside them (the latter most useful for Rooms).
+    - Characters will get poses and also sdescs (short descriptions)
+    that will be used instead of their keys. They will gain commands
+    for managing recognition (custom sdesc-replacement), masking
+    themselves as well as an advanced free-form emote command.
 
-    emote system using director stance emoting (names/sdescs instead of
-        replacing with you etc)
-    sdesc obscuration of real character names for use in emotes
-        and in any referencing
-    recog system to assign your own nicknames to characters, can then
-        be used for referencing
-    pose system to set room-persistent poses, visible in room
-        descriptions and when looking at the person
+To use, simply import the typclasses you want from this module and use
+them to create your objects, or set them to default.
 
-Emote system: This uses a customizable replacement noun (/me, @ etc)
-    to represent you in the emote. You can use /sdesc, /nick, /key or
-    /alias to reference objects in the room.
-Sdesc system:
-    This relies on an Attribute `sdesc` being set on the Character and
-    makes use of a custom Character.get_display_name hook. If sdesc
-    is not set, the character's `key` is used instead. This is particularly
-    used in the emoting system.
-Recog system:
-    The user may recog a user and assign any personal nick to them. This
-    will be shown in descriptions and used to reference them. This is
-    making use of the nick functionality of Evennia.
-Pose system:
-    This is a simple Attribute that modifies the way the character is
-    listed when in a room as sdesc + pose.
+In more detail, This RP base system introduces the following features
+to a game, common to many RP-centric games:
+
+    - emote system using director stance emoting (names/sdescs).
+        This uses a customizable replacement noun (/me, @ etc) to
+        represent you in the emote. You can use /sdesc, /nick, /key or
+        /alias to reference objects in the room. You can use any
+        number of sdesc sub-parts to differentiate a local sdesc, or
+        use /1-sdesc etc to differentiate them. The emote also
+        identifies nested says.
+    - sdesc obscuration of real character names for use in emotes
+        and in any referencing such as object.search().  This relies
+        on an SdescHandler `sdesc` being set on the Character and
+        makes use of a custom Character.get_display_name hook. If
+        sdesc is not set, the character's `key` is used instead. This
+        is particularly used in the emoting system.
+    - recog system to assign your own nicknames to characters, can then
+        be used for referencing. The user may recog a user and assign
+        any personal nick to them. This will be shown in descriptions
+        and used to reference them. This is making use of the nick
+        functionality of Evennia.
+    - masks to hide your identity (using a simple lock).
+    - pose system to set room-persistent poses, visible in room
+        descriptions and when looking at the person/object.  This is a
+        simple Attribute that modifies how the characters is viewed when
+        in a room as sdesc + pose.
+    - in-emote says, including seamless integration with language
+        obscuration routine (such as contrib/rplanguage.py)
 
 Examples:
 
@@ -38,7 +53,7 @@ Examples:
 Tavern
 The tavern is full of nice people
 
-You see *a tall man* standing by the bar.
+*A tall man* is standing by the bar.
 
 Above is an example of a player with an sdesc "a tall man". It is also
 an example of a static *pose*: The "standing by the bar" has been set
@@ -52,6 +67,7 @@ I see:
 Tall man (assuming his name is Tom) sees:
     The godlike figure looks at Tom and says "Hello".
 
+
 """
 
 import re