Updated rst-docs to match online wiki

docs/sphinx/source/wiki/GettingStarted.rst

@@ -49,7 +49,7 @@ Evennia:
 -  The default database system SQLite3 only comes as part of Python2.5
    and later.
 -  Windows users are recommended to use ActivePython
-   (http://www.activestate.com/activepython)
+   (http://www.activestate.com/activepython/downloads)
 
 **Twisted** (http://twistedmatrix.com)
 
@@ -106,19 +106,22 @@ all you need:
 
 If some or all dependencies are not readily available (for example,
 running some flavors of !RedHat/CentOS or an older Debian version) you
-can still retrieve them easily by using Python's
+can still retrieve them easily by installing and using Python's
 `easyinstall <http://packages.python.org/distribute/easy%3Ci%3Einstall.html>`_
 or the alternative
 `pip <http://www.pip-installer.org/en/latest/index.html>`_:
-``easy_install django twisted pil mercurial``
+
+::
+
+    easy_install django twisted pil mercurial
 
 ::
 
     pip install django twisted pil mercurial
 
 **Windows** users may choose to install
-`ActivePython <http://www.activestate.com/activepython>`_ instead of the
+`ActivePython <http://www.activestate.com/activepython/downloads>`_
-usual Python. If ActivePython is installed, you can use
+instead of the usual Python. If ActivePython is installed, you can use
 `pypm <http://docs.activestate.com/activepython/2.6/pypm.html>`_ in the
 same manner as ``easy_install``/``pip`` above. This *greatly* simplifies
 getting started on Windows:
@@ -127,8 +130,10 @@ getting started on Windows:
 
     pypm install Django Twisted PIL Mercurial
 
-}} Another simple alternative (for all platforms) is to set up a
+Another simple alternative (for all platforms) is to set up a *virtual
-*virtual Python environment* and install to that. This is covered
+Python environment* and install to that - in that case you can even
+experiment with different library versions without affecting your main
+system configuration. This is covered
 `here <GettingStarted#Optional:%3Ci%3EA%3C/i%3Eseparate%3Ci%3Einstallation%3C/i%3Eenvironment%3Ci%3Ewith%3C/i%3Evirtualenv.html>`_.
 
 Windows users not using ActivePython or virtual environments will have
@@ -257,6 +262,10 @@ To stop Evennia, do:
 
     python evennia.py stop
 
+See `Running
+Evennia <https://code.google.com/p/evennia/wiki/StartStopReload.html>`_
+for more advanced options on controlling Evennia's processes.
+
 Step 4: Connecting to the server
 --------------------------------
 
@@ -287,9 +296,10 @@ play. You can install South from
 available through the normal package distributions, easy\_install, pip,
 or pypm (see above notes).
 
-Whenever you see a commit or mailing list message instructing you to run
+After your first run of ``migrate.py syncdb`` and whenever you see a
-migrations to update your DB schema, simply do the following from within
+commit or mailing list message telling you that "the Database Schema has
-the ``evennia/game`` directory:
+changed", simply do the following from within the ``evennia/game``
+directory:
 
 ::
 
@@ -325,17 +335,22 @@ virtual environment in here.
     # for Windows:
     <path_to_this_place>\bin\activate.bat
 
-In here you can play around and install python packages of any version
+Next we get all the requirements with *pip*, which is included with
-without affecting your normal system installation at all. Next we get
+virtualenv:
-all the requirements with *pip*, which comes with virtualenv. This is
-the cool bit.
 
 ::
 
-    pip install django twisted pil
+    pip install django twisted pil mercurial
+
+(The difference from the normal install described earlier is that these
+installed packages are *only* localized to the virtual environment, they
+do not affect the normal versions of programs you run in the rest of
+your system. So you could for example experiment with bleeding-edge,
+unstable libraries or go back to older versions without having to worry
+about messing up other things. It's also very easy to uninstall the
+whole thing in one go - just delete your ``mudenv`` folder.)
 
 You can now refer to **Step 1** above and continue on from there to
-install Evennia into *mudenv* (you need to get ``subversion`` manually
+install Evennia into *mudenv*. In the future, just go into the folder
-still, it's not a python program). In the future, just go into the
+and activate it to make this separate virtual environment available to
-folder and activate it to make this separate virtual environment
+Evennia.
-available to Evennia.

docs/sphinx/source/wiki/HelpSystem.rst

@@ -8,7 +8,7 @@ players and staff alike to learn how to use the game's commands as well
 as other information pertinent to the game. The help system has many
 different aspects, from the normal editing of help entries from inside
 the game, to auto-generated help entries during code development using
-the *auto-help* system.
+the *auto-help system*.
 
 Viewing the help database
 -------------------------
@@ -31,18 +31,19 @@ Command Auto-help system
 
 One important use of the help system is to teach the use of in-game
 commands. Evennia offers a dynamically updated help system for all your
-commands, new and old, known simply as the *auto-help* system. Only
+commands, new and old, known simply as the *auto-help system*. Only
-commands that you can actually use are picked up by the auto-help
+commands that you and your character can actually currently use are
-system. That means an admin will see a considerably larger mass of help
+picked up by the auto-help system. That means an admin will see a
-topics when using the ``help`` command than a normal player.
+considerably larger amount of help topics than a normal player when
+using the ``help`` command.
 
 The auto-help system uses the ``__doc__`` strings of your command
 definitions and formats this to a nice-looking help entry. This makes
 for a very easy way to keep the help updated - just document your
-commands well - updating the help system is just a ``@reload`` away.
+commands well abd updating the help file is just a ``@reload`` away.
-There is no need to manually create help database entries for commands;
+There is no need to manually create and maintain help database entries
-as long as you keep the docstrings updated your help will be dynamically
+for commands; as long as you keep the docstrings updated your help will
-updated for you as well.
+be dynamically updated for you as well.
 
 Example (from a module with command definitions):
 
@@ -59,37 +60,38 @@ Example (from a module with command definitions):
        help_category = "Building"
         ...
 
-So the text at the very top of the command class definition is the
+The text at the very top of the command class definition is the class'
-class' ``__doc__``-string and what will be shown to users looking for
+``__doc__``-string and will be shown to users looking for help. Try to
-help. Try to use a consistent formatting between your help strings (for
+use a consistent format - all default commands are using the structure
-example, all default commands have ``__doc__``-strings formatted in the
+shown above. You should also supply the ``help_category`` class property
-way seen above). You should also supply the ``help_category`` class
+if you can; this helps to group help entries together for easier finding
-property if you can; this helps to group help entries together for
+(if you don't supply a help\_category, "General" will be assumed).
-easier finding (if you don't supply a help\_category, "General" will be
-assumed).
 
 Other help entries (entries stored in database)
 -----------------------------------------------
 
-The *Other help* section you see when using the ``help`` command shows
+Not all help entries concern commands. You will also probably need help
-all help entries that has been manually added to the database by staff.
+entries describing how your particular game is played - its rules, world
-Instead of being generated from the code by Evennia, these are stored in
+descriptions and other types of information not covered by the auto-help
-the database using a model called *!HelpEntry*. HelpEntry topics are
+system. Such entries are manually added to the database by staff and
-intended for world-game-info, tutorials and other types of useful
+will appear under a heading "Other help" whenever you have any. Instead
-information not directly tied to a command and covered by auto-help.
+of being generated from the code by Evennia, these entries are stored in
+the database as a ``HelpEntry``.
 
 A help entry consists of four parts:
 
 -  The *topic*. This is the name of the help entry. This is what players
    search for when they are looking for help. The topic can contain
-   spaces.
+   spaces and also partual matches will be found.
 -  The *help category*. Examples are *Administration*, *Building*,
    *Comms* or *General*. This is an overall grouping of similar help
    topics, used by the engine to give a better overview.
--  The *text* - the help text itself, of any length. This can also
+-  The *text* - the help text itself, of any length.
-   include *markup*, see below.
+-  locks - a `lock definition <Locks.html>`_. This can be used to limit
--  locks - a `lock definition <Locks.html>`_. Help commands check for
+   access to this help entry, maybe because it's staff-only or otherwise
-   access\_types ``examine`` and ``edit``.
+   meant to be restricted. Help commands check for ``access_type``s
+   ``view`` and ``edit``. An example of a lock string would be
+   ``view:perm(Builders)``.
 
 You can create new help entries in code by using
 ``src.utils.create.create_help_entry()``:
@@ -116,11 +118,13 @@ You can change this using a different form of the ``@sethelp`` command:
 
     > @sethelp/add emote, Roleplaying = Emoting is important because ...
 
-If the category *Roleplaying* did not exist it is created and will
+If the category *Roleplaying* did not already exist, it is created and
-appear in the help index. You can, finally, define a lock for the help
+will appear in the help index.
-entry by following the category with a `lock definition <Locks.html>`_:
+
+You can, finally, define a lock for the help entry by following the
+category with a `lock definition <Locks.html>`_:
 
 ::
 
-    > @sethelp/add emote, Roleplaying, view:all() = The emote command ...
+    > @sethelp/add emote, Roleplaying, view:all() = Emoting is important because ...
 

docs/sphinx/source/wiki/PortalAndServer.rst

@@ -7,9 +7,9 @@ described `here <StartStopReload.html>`_.
 
 https://2498159658166209538-a-1802744773732722657-s-sites.googlegroups.com/site/evenniaserver/file-cabinet/evennia*server*portal.png
 
-As seen above, the Server and Portal are glued together via an AMP
+The Server and Portal are glued together via an AMP (Asynchronous
-(Asynchronous Messaging Protocol) connection. This allows the two
+Messaging Protocol) connection. This allows the two programs to
-programs to communicate.
+communicate.
 
 Portal and Server Sessions
 --------------------------
@@ -24,15 +24,16 @@ Session* is created on the Portal side. This session object looks
 different depending on which protocol is used to connect, but all still
 have a minimum set of attributes that are generic to all sessions.
 
-These common properties are piped through AMP to the Server, who is now
+These common properties are piped from the Portal, through AMP, to the
-informed a new connection has been established. On the Server side, a
+*Server*, which is now informed a new connection has been established.
-*Server Session* object is created to represent this. There is only one
+On the Server side, a *Server Session* object is created to represent
-type of Server Session. It looks the same regardless of how the Player
+this. There is only one type of Server Session. It looks the same
-connects, it leaves such details up to the Portal.
+regardless of how the Player connects.
 
 From now on, there is a one-to-one match between the Server Session on
-one side and the Portal Session on the other. Data arriving to the
+one side of the AMP connection and the Portal Session on the other. Data
-Portal Session is sent on to its mirror Server session and vice versa.
+arriving to the Portal Session is sent on to its mirror Server session
+and vice versa.
 
 During certain situations, the portal- and server-side sessions are
 "synced" with each other:
@@ -43,12 +44,12 @@ During certain situations, the portal- and server-side sessions are
 -  The Player quits from inside the game, killing the Server Session.
    The Server then syncs with the Portal to make sure to close the
    Portal connection cleanly.
--  The Server is rebooted/reset/shutdown - The Server Sessions are then
+-  The Server is rebooted/reset/shutdown - The Server Sessions are
    copied over ("saved") to the Portal side. When the Server comes back
    up, this data is returned by the Portal so the two are again in sync.
    This way a Player's login status and other connection-critical things
-   can survive a server reboot (assuming the Portal is also not stopped,
+   can survive a server reboot (assuming the Portal is not stopped at
-   obviously).
+   the same time, obviously).
 
 Sessionhandlers
 ---------------

docs/sphinx/source/wiki/SessionProtocols.rst

@@ -1,8 +1,8 @@
 Portal Sessions and Protocols
 =============================
 
-*Note: This is considered an advanced topic and not relevant to most
+*Note: This is considered an advanced topic and is mostly of interest to
-users.*
+users planning to implement their own custom client protocol.*
 
 A *Portal Session* is the basic data object representing an external
 connection to the Evennia `Portal <PortalAndServer.html>`_ -- usually a
@@ -40,17 +40,21 @@ A straight-forward protocol (like Telnet) is assumed to at least have
 the following components (although the actual method names might vary):
 
 -  ``connectionMade`` - called when a new connection is made. This must
-   call ``self.init_session()`` with three arguments: an identifier for
+   call ``self.init_session()`` with three arguments: an *identifier*
-   the protocol type (e.g. the string 'telnet'), the IP address
+   for the protocol type (e.g. the string 'telnet' or 'ssh'), the *IP
-   connecting, and a reference to the sessionhandler.
+   address* of the client connecting, and a reference to the
+   *sessionhandler*. The sessionhandler is by convention made available
+   by storing it on the protocol's *Factory* in
+   ``src/server/portal.py``, see that file for examples. Doing it this
+   way avoids many possible recursive import issues.
 -  ``connectionLost`` - called when connection is dropped for whatever
-   reason. This must call 'self.sessionhandler.disconnect(self)' so the
+   reason. This must call ``self.sessionhandler.disconnect(self)`` so
-   handler can make sure the disconnect is reported to the rest of the
+   the handler can make sure the disconnect is reported to the rest of
-   system.
+   the system.
 -  ``getData`` - data arriving from the player to Evennia. This should
    apply whatever custom formatting this protocol needs, then relay the
    data to ``self.sessionhandler.data_in(self, msg, data)``.
--  sendLine - data from server to Player. This is called by hook
+-  ``sendLine`` - data from Server to Player. This is called by hook
    ``data_out()`` below.
 
 See an example of this in
@@ -58,8 +62,8 @@ See an example of this in
 
 These might not be as clear-cut in all protocols, but the principle is
 there. These four basic components - however they are accessed - links
-to the *Session*, which is the actual common interface between the
+to the *Portal Session*, which is the actual common interface between
-different low-level protocols and Evennia.
+the different low-level protocols and Evennia.
 
 Portal Sessions
 ---------------
@@ -85,13 +89,15 @@ be named exactly like this):
 -  ``disconnect()`` - called when manually disconnecting. Must call the
    protocol-specific disconnect method (e.g. ``connectionLost`` above)
 -  ``data_out(string="", data=None)`` - data from Evennia to player.
-   ``string`` is normally a raw text string with formatting. ``data``
+   This method should handle any protocol-specific processing before
-   can be a collection of any extra information the server want to give
+   relaying data on to a send-method like ``self.sendLine()`` mentioned
-   to the protocol; it's completely up to the Protocol to handle this
+   above. ``string`` is normally a raw text string with formatting.
-   (e.g. telnet completely ignores the ``data`` variable). From inside
+   ``data`` can be a collection of any extra information the server want
-   Evennia, this if often called with the alias ``msg`` instead. This
+   to give to the protocol- it's completely up to the Protocol to handle
-   method should call the protocol-specific send method, such as
+   this. To take an example, telnet assumes ``data`` to be either
-   ``self.sendLine()``, directly.
+   ``None`` or a dictionary with flags for how the text should be
+   parsed. From inside Evennia, ``data_out`` is often called with the
+   alias ``msg`` instead.
 
 Assorted notes
 --------------
@@ -100,4 +106,6 @@ To take two examples, Evennia supports the *telnet* protocol as well as
 *webclient*, a custom ajax protocol. You'll find that whereas telnet is
 a textbook example of a Twisted protocol as seen above, the ajax client
 protocol looks quite different due to how it interacts with the
-webserver through long-polling (comet) style requests.
+webserver through long-polling (comet) style requests. All the necessary
+parts mentioned above are still there, but implemented in very different
+ways.