docs: updating rest documentationdocs: updating rest documentation..

docs/sphinx/source/wiki/Attributes.rst

@@ -193,6 +193,68 @@ Example of non-supported save:
     bad.dbobj = myobj
     obj.db.test8 = bad # this will likely lead to a traceback
 
+Storing nested data directly on the variable
+--------------------------------------------
+
+Evennia needs to do a lot of work behind the scenes in order to save and
+retrieve data from the database. Most of the time, things work just like
+normal Python, but there is one further exception except the one about
+storing database objects above. It is related to updating already
+existing attributes in-place. Normally this works just as it should. For
+example, you can do
+
+::
+
+    # saving data
+    obj.db.mydict["key"] = "test1"
+    obj.db.mylist[34] = "test2"
+    obj.db.mylist.append("test3")
+    # retrieving data
+    obj.db.mydict["key"] # returns "test1"
+    obj.db.mylist[34] # returns "test2
+    obj.db.mylist[-1] # returns "test3"
+
+and it will work fine, thanks to a lot of magic happening behind the
+scenes. What will *not* work however is editing *nested*
+lists/dictionaries in-place. This is due to the way Python referencing
+works. Consider the following:
+
+::
+
+    obj.db.mydict = 1:2:3
+
+This is a perfectly valid nested dictionary and Evennia will store it
+just fine.
+
+::
+
+    obj.db.mydict[1][2] # correctly returns 3
+
+However:
+
+::
+
+    obj.db.mydict[1][2] = "test" # fails!
+
+will not work - trying to edit the nested structure will fail silently
+and nothing will have changed. No, this is not consistent with normal
+Python operation, it's where the database magic fails. All is not lost
+however. In order to change a nested structure, you simply need to use a
+temporary variable:
+
+::
+
+    # retrieve old db data into temporary variable
+    mydict = obj.db.mydict
+    # update temporary variable
+    mydict[1][2] = "test"
+    # save back to database
+    obj.db.mydict = mydict
+    # test
+    obj.db.mydict[1][2] # now correctly returns "test"
+
+mydict was updated and recreated in the database.
+
 Notes
 -----
 

docs/sphinx/source/wiki/DefaultCommandHelp.rst

@@ -20,7 +20,7 @@ Admin
 -----
 
 `Link to Python
-module <https://code.google.com/p/evennia/source/browse/trunk/src/commands/default/admin.py.html>`_
+module <https://code.google.com/p/evennia/source/browse/src/commands/default/admin.py.html>`_
 
 @boot
 ~~~~~
@@ -200,7 +200,7 @@ Building
 --------
 
 `Link to Python
-module <https://code.google.com/p/evennia/source/browse/trunk/src/commands/default/building.py.html>`_
+module <https://code.google.com/p/evennia/source/browse/src/commands/default/building.py.html>`_
 
 @alias
 ~~~~~~
@@ -652,14 +652,13 @@ module <https://code.google.com/p/evennia/source/browse/trunk/src/commands/defau
           @script[/switch] <obj> [= <script.path or scriptkey>]
         
         Switches:
-          start - start a previously added script
+          start - start all non-running scripts on object, or a given script only
-          stop - stop a previously added script    Attaches the given script to the object and starts it. Script path
+          stop - stop all scripts on objects, or a given script only    If no script path/key is given, lists all scripts active on the given
-        can be given from the base location for scripts as given in
+        object. 
-        settings.  If stopping/starting an already existing script, the
+        Script path can be given from the base location for scripts as given in
-        script's key can be given instead (if giving a path, *all* scripts
+        settings. If adding a new script, it will be started automatically (no /start
-        with this path on <obj> will be affected). If no script name is given,
+        switch is needed). Using the /start or /stop switches on an object without 
-        all scripts on the object is affected (or displayed if no start/stop
+        specifying a script key/path will start/stop ALL scripts on the object.
-        switch is set).
 
 @set
 ~~~~
@@ -804,7 +803,7 @@ Comms
 -----
 
 `Link to Python
-module <https://code.google.com/p/evennia/source/browse/trunk/src/commands/default/comms.py.html>`_
+module <https://code.google.com/p/evennia/source/browse/src/commands/default/comms.py.html>`_
 
 @cboot
 ~~~~~~
@@ -1115,7 +1114,7 @@ General
 -------
 
 `Link to Python
-module <https://code.google.com/p/evennia/source/browse/trunk/src/commands/default/general.py.html>`_
+module <https://code.google.com/p/evennia/source/browse/src/commands/default/general.py.html>`_
 
 @encoding
 ~~~~~~~~~
@@ -1459,7 +1458,7 @@ System
 ------
 
 `Link to Python
-module <https://code.google.com/p/evennia/source/browse/trunk/src/commands/default/system.py.html>`_
+module <https://code.google.com/p/evennia/source/browse/src/commands/default/system.py.html>`_
 
 @objects
 ~~~~~~~~
@@ -1508,20 +1507,19 @@ module <https://code.google.com/p/evennia/source/browse/trunk/src/commands/defau
 ::
 
     Execute a snippet of python code     Usage:
-          @py <cmd>    In this limited python environment, there are a 
+          @py <cmd>    Separate multiple commands by ';'.  A few variables are made
-        few variables made available to give access to 
+        available for convenience in order to offer access to the system
-        the system.     available_vars: 'self','me'  : caller
+        (you can import more at execution time).    Available variables in @py environment: 
-                        'here'  : caller.location
+          self, me                   : caller
-                        'obj'   : dummy obj instance
+          here                       : caller.location
-                        'script': dummy script instance
+          obj                        : dummy obj instance
-                        'config': dummy conf instance
+          script                     : dummy script instance
-                        'ObjectDB' : ObjectDB class
+          config                     : dummy conf instance                    
-                        'ScriptDB' : ScriptDB class
+          ObjectDB                   : ObjectDB class
-                        'ServerConfig' ServerConfig class
+          ScriptDB                   : ScriptDB class
-        only two
+          ServerConfig               : ServerConfig class
-        variables are defined: 'self'/'me' which refers to one's
+          inherits_from(obj, parent) : check object inheritance    rNote: In the wrong hands this command is a severe security risk.
-        own object, and 'here' which refers to self's current
+        It should only be accessible by trusted server admins/superusers.n
-        location.
 
 @reload
 ~~~~~~~
@@ -1670,7 +1668,7 @@ Unloggedin
 ----------
 
 `Link to Python
-module <https://code.google.com/p/evennia/source/browse/trunk/src/commands/default/unloggedin.py.html>`_
+module <https://code.google.com/p/evennia/source/browse/src/commands/default/unloggedin.py.html>`_
 
 connect
 ~~~~~~~