1 files changed, 111 insertions, 22 deletions
diff --git a/Doc/Manual/Modules.html b/Doc/Manual/Modules.html
index 8971324fb..1b628f802 100644
--- a/Doc/Manual/Modules.html
+++ b/Doc/Manual/Modules.html
@@ -10,6 +10,7 @@
 <!-- INDEX -->
 <div class="sectiontoc">
 <ul>
+<li><a href="#Modules_introduction">Modules Introduction</a>
 <li><a href="#Modules_nn1">Basics</a>
 <li><a href="#Modules_nn2">The SWIG runtime code</a>
 <li><a href="#external_run_time">External access to the runtime</a>
@@ -22,11 +23,49 @@
 
 
 
+<H2><a name="Modules_introduction"></a>15.1 Modules Introduction</H2>
+
+
+<p>
+Each invocation of SWIG requires a module name to be specified.
+The module name is used to name the resulting target language extension module. 
+Exactly what this means and and what the name is used for
+depends on the target language, for example the name can define
+a target language namespace or merely be a useful name for naming files or helper classes.
+Essentially, a module comprises target language wrappers for a chosen collection of global variables/functions, structs/classes and other C/C++ types.
+</p>
+
+<p>
+The module name can be supplied in one of two ways. 
+The first is to specify it with the special <tt>%module</tt>
+directive. This directive must appear at the beginning of the interface file.
+The general form of this directive is:
+</p>
+
+<div class="code"><pre>
+<tt>%module(option1="value1",option2="value2",...) modulename</tt>
+</pre></div>
+
+<p>
+where the modulename is mandatory and the options add one or more optional additional features.
+Typically no options are specified, for example:
+</p>
+
+<div class="code"><pre>
+<tt>%module mymodule</tt>
+</pre></div>
+
+<p>
+The second way to specify the module name is with the <tt>-module</tt> command line option, for example <tt>-module mymodule</tt>.
+If the module name is supplied on the command line, it overrides the name specified by the
+<tt>%module</tt> directive.
+</p>
+
 <p>
 When first working with SWIG, users commonly start by creating a
 single module.  That is, you might define a single SWIG interface that
 wraps some set of C/C++ code.  You then compile all of the generated
-wrapper code into a module and use it.   For large applications, however,
+wrapper code together and use it.   For large applications, however,
 this approach is problematic---the size of the generated wrapper code
 can be rather large.  Moreover, it is probably easier to manage the
 target language interface when it is broken up into smaller pieces.
@@ -34,10 +73,11 @@ target language interface when it is broken up into smaller pieces.
 
 <p>
 This chapter describes the problem of using SWIG in programs
-where you want to create a collection of modules.
+where you want to create a collection of modules. 
+Each module in the collection is created via separate invocations of SWIG.
 </p>
 
-<H2><a name="Modules_nn1"></a>15.1 Basics</H2>
+<H2><a name="Modules_nn1"></a>15.2 Basics</H2>
 
 
 <p>
@@ -50,43 +90,92 @@ scripting language runtime as you would do for the single module case.
 
 <p>
 A bit more complex is the case in which modules need to share information.
-For example, when one module extends the class of the another by deriving from
+For example, when one module extends the class of another by deriving from
 it:
 </p>
 
 <div class="code"><pre>
-%module base
-
-%inline %{
+// File: base.h
 class base {
 public:
-       int foo(void);
+  int foo();
 };
+</pre></div>
+&nbsp;
+
+<div class="code"><pre>
+// File: base_module.i
+%module base_module
+
+%{
+#include "base.h"
 %}
+%include "base.h"
 </pre></div>
 &nbsp;
+
 <div class="code"><pre>
-%module derived
+// File: derived_module.i
+%module derived_module
 
-%import "base.i"
+%import "base_module.i"
 
 %inline %{
 class derived : public base {
 public:
-       int bar(void);
+  int bar();
 };
 %}
 </pre></div>
 
-<p>To create the wrapper properly, module <tt>derived</tt> needs to know the
-<tt>base</tt> class and that it's interface is covered in another module. The
-line <tt>%import "base.i"</tt> lets SWIG know exactly that. The common mistake here is
-to <tt>%import</tt> the <tt>.h</tt> file instead of the <tt>.i</tt>, which sadly won't do the trick. Another issue
-to take care of is that multiple dependent wrappers should not be linked/loaded
+<p>To create the wrapper properly, module <tt>derived_module</tt> needs to know about the
+<tt>base</tt> class and that its interface is covered in another module. The
+line <tt>%import "base_module.i"</tt> lets SWIG know exactly that. Oftentimes
+the <tt>.h</tt> file is passed to <tt>%import</tt> instead of the <tt>.i</tt>, 
+which unfortunately doesn't work for all language modules. For example, Python requires the
+name of module that the base class exists in so that the proxy classes can fully inherit the
+base class's methods. Typically you will get a warning when the module name is missing, eg:
+</p>
+
+<div class="shell"> <pre>
+derived_module.i:8: Warning(401): Base class 'base' ignored - unknown module name for base. Either import 
+the appropriate module interface file or specify the name of the module in the %import directive.
+</pre></div>
+
+<p>
+It is sometimes desirable to import the header file rather than the interface file and overcome
+the above warning. 
+For example in the case of the imported interface being quite large, it may be desirable to
+simplify matters and just import a small header file of dependent types.
+This can be done by specifying the optional <tt>module</tt> attribute in the <tt>%import</tt> directive.
+The <tt>derived_module.i</tt> file shown above could be replaced with the following:
+
+<div class="code"><pre>
+// File: derived_module.i
+%module derived_module
+
+%import(module="base_module") "base.h"
+
+%inline %{
+class derived : public base {
+public:
+  int bar();
+};
+</pre></div>
+
+<p>
+Note that "base_module" is the module name and is the same as that specified in <tt>%module</tt>
+in <tt>base_module.i</tt> as well as the <tt>%import</tt> in <tt>derived_module.i</tt>.
+</p>
+
+<p>
+Another issue
+to beware of is that multiple dependent wrappers should not be linked/loaded
 in parallel from multiple threads as SWIG provides no locking - for more on that
-issue, read on.</p>
+issue, read on.
+</p>
 
-<H2><a name="Modules_nn2"></a>15.2 The SWIG runtime code</H2>
+<H2><a name="Modules_nn2"></a>15.3 The SWIG runtime code</H2>
 
 
 <p>
@@ -152,7 +241,7 @@ can peacefully coexist. So the type structures are separated by the
 is empty. Only modules compiled with the same pair will share type information.
 </p>
 
-<H2><a name="external_run_time"></a>15.3 External access to the runtime</H2>
+<H2><a name="external_run_time"></a>15.4 External access to the runtime</H2>
 
 
 <p>As described in <a href="Typemaps.html#runtime_type_checker">The run-time type checker</a>,
@@ -189,7 +278,7 @@ SWIG_TYPE_TABLE to be the same as the module whose types you are trying to
 access.
 </p>
 
-<H2><a name="Modules_nn4"></a>15.4 A word of caution about static libraries</H2>
+<H2><a name="Modules_nn4"></a>15.5 A word of caution about static libraries</H2>
 
 
 <p>
@@ -200,7 +289,7 @@ into it. This is very often <b>NOT</b> what you want and it can lead to unexpect
 behavior. When working with dynamically loadable modules, you should try to work exclusively with shared libraries.
 </p>
 
-<H2><a name="Modules_nn5"></a>15.5 References</H2>
+<H2><a name="Modules_nn5"></a>15.6 References</H2>
 
 
 <p>
@@ -208,7 +297,7 @@ Due to the complexity of working with shared libraries and multiple modules, it
 an outside reference.  John Levine's "Linkers and Loaders" is highly recommended.
 </p>
 
-<H2><a name="Modules_nn6"></a>15.6 Reducing the wrapper file size</H2>
+<H2><a name="Modules_nn6"></a>15.7 Reducing the wrapper file size</H2>
 
 
 <p>