added comments to doc to clarify "module as file" metaphor

doc/advanced/module.txt

@@ -5,25 +5,28 @@
 Module Interface
 ================
 
-Functions in theano can share containers, when the `value` argument to `In` is a Container
-instance.  This feature makes it possible for multiple functions to use (and update) the same
-inputs.
-Module is a class in Theano that exists to facilitate the compilation of
-multiple Functions that work on (and update) overlapping sets of input
-Variables.
-
-Modules provide a more intuitive syntax that makes this feature easier to use.  
-They draw on the metaphor of a python import--a module has functions and variables, and
-can contain other modules.  All functions have access to all variables, and whenever any
-function modifies a file-level variable, then that change is visible to all other functions.
+A Theano Module is like Theano's version of a file.
+When you instantiate a ``Module()``, you are creating a blank file.
+Into this file you can put both symbolic and non-symbolic objects.
+Non-symbolic objects are like constants (technically literals) in the file.
+Symbolic objects are like variables and functions.
+The functions in a Module are called Methods.
+The variables in a Module (and submodules) are global.
+Module Methods have access to all these global variables.
+
+To use a Module, you need to compile it.
+This is done by calling `Module.make()`.
+The result of compiling a Module is a ModuleInstance, this is the compiled
+version of your Theano file.
+In the ModuleInstance, your symbolic variables have become containers (containing None),
+and your Methods have become callable functions.
+You should initialize the symbolic variables by calling
+``ModuleInstance.initialize()`` (although make() will call it for you, 
+on the top-level ModuleInstance.)
+
+You can compile a Module several times, to create multiple ModuleInstances.
+Each of these will have its own copy of all program literals.
 
-In the Module system, the analog of the file is the `Module`, the analog of the function is the
-`Method`, and the analog of the variable is the `Member`.  Module, Member, and Method all work
-at the symbolic level.  Once a graph of Modules, Members, and Methods is ready for use, it must
-be compiled with a call to `make` which will return an isomorphic structure in which Modules
-have become `ModuleInstances`, Members have become `Container`s, and Methods have become
-`Function`s.
-This structure contains numbers and functions, and is ready for computation.
 
 
 Module Graph
@@ -129,3 +132,15 @@ into Components by :api:`compile.module.wrap`.  If a Module contains something
 that is not convertible into a Component, then it is not possible to compile
 that Module with ``make``.
 
+
+Old Text
+--------
+
+In the Module system, the analog of the file is the `Module`, the analog of the function is the
+`Method`, and the analog of the variable is the `Member`.  Module, Member, and Method all work
+at the symbolic level.  Once a graph of Modules, Members, and Methods is ready for use, it must
+be compiled with a call to `make` which will return an isomorphic structure in which Modules
+have become `ModuleInstances`, Members have become `Container`s, and Methods have become
+`Function`s.
+This structure contains numbers and functions, and is ready for computation.
+

doc/basic_tutorial/module.txt

@@ -5,9 +5,11 @@ Using Module
 
 Now that we're familiar with the basics, we introduce Theano's more
 advanced interface, Module. This interface allows you to define Theano
-"objects" which can have many state variables and many methods sharing
-these states. The Module system simplifies the way to define complex
+"files" which can have variables and methods sharing
+those variables. The Module system simplifies the way to define complex
 systems such as a neural network.
+It also lets you load and save these complex systems using Python's pickle
+mechanism.
 
 
 Remake of the "state" example
@@ -44,12 +46,15 @@ This deserves to be broken up a bit...
 >>> m = Module()
 
 Here we instantiate an empty Module.
+If you can imagine that Theano is a way of generating code (expression
+graphs),
+then a ``Module()`` is like a fresh blank file.
 
 
 >>> m.state = T.dscalar()
 >>> m.inc = T.dscalar('inc')
 
-Then we declare Variables for use with our Module.
+Then we declare Variables for use in our Module.
 Since we assign these input Variables as attributes of the Module,
 they will be *member Variables* of the Module.
 Member Variables are special in a few ways, which we will see shortly.
@@ -57,7 +62,8 @@ Member Variables are special in a few ways, which we will see shortly.
 .. note::
 
    There is no need to name the Variable explicitly here. ``m.state`` will
-   be given the name ``'state'`` automatically.
+   be given the name ``'state'`` automatically, because it is being assigned
+   to the attribute named ``'state'``.
 
 
 .. note::