add new %begin directive for inserting code at top of wrapper file

git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk@11133 626c5289-ae23-0410-ae9c-e8d60b6d4f22

Doc/Manual/Allegrocl.html

@@ -411,7 +411,7 @@ using the SWIG <tt>%insert(section) %{ ...code... %}</tt> directive:
 <pre>
 %module example
 
-%insert("runtime") %{
+%{
 #include "header.h"
 %}
 
@@ -432,7 +432,7 @@ generated lisp interface file
 </ul>
 <p>
 Note that the block <tt>%{ ... %}</tt> is effectively a shortcut for
-<tt>%insert("runtime") %{ ... %}</tt>.
+<tt>%insert("header") %{ ... %}</tt>.
 </p>
 
 

Doc/Manual/Extending.html

@@ -232,10 +232,11 @@ of <tt>swig.swg</tt> looks like this:
 ...
 /* Code insertion directives such as %wrapper %{ ... %} */
 
-#define %init        %insert("init")
-#define %wrapper     %insert("wrapper")
-#define %header      %insert("header")
+#define %begin       %insert("begin")
 #define %runtime     %insert("runtime")
+#define %header      %insert("header")
+#define %wrapper     %insert("wrapper")
+#define %init        %insert("init")
 
 /* Access control directives */
 

Doc/Manual/Lisp.html

@@ -583,7 +583,7 @@ using the SWIG <tt>%insert(section) %{ ...code... %}</tt> directive:
 <pre>
 %module example
 
-%insert("runtime") %{
+%{
 #include "header.h"
 %}
 
@@ -604,7 +604,7 @@ generated lisp interface file:
 </ul>
 <p>
 Note that the block <tt>%{ ... %}</tt> is effectively a shortcut for
-<tt>%insert("runtime") %{ ... %}</tt>.
+<tt>%insert("header") %{ ... %}</tt>.
 </p>
 
 

Doc/Manual/SWIG.html

@@ -2737,11 +2737,16 @@ the module upon loading.
 
 <p>
 Code is inserted into the appropriate code section by using one
-of the following code insertion directives:
+of the code insertion directives listed below. The order of the sections in
+the wrapper file is as shown:
 </p>
 
 <div class="code">
 <pre>
+%begin %{
+   ... code in begin section ...
+%}
+
 %runtime %{
    ... code in runtime section ...
 %}
@@ -2762,10 +2767,12 @@ of the following code insertion directives:
 
 <p>
 The bare <tt>%{ ... %}</tt> directive is a shortcut that is the same as
-<tt>%header %{ ... %}</tt>.
+<tt>%header %{ ... %}</tt>. 
 </p>
 
 <p>
+The <tt>%begin</tt> section is empty by default
+and is provided as a way for users to insert code at the top of the wrapper file.
 Everything in a code insertion block is copied verbatim into the output file and is 
 not parsed by SWIG.   Most SWIG input files have at least one such block to include header
 files and support C code.  Additional code blocks may be placed anywhere in a