More for 4.3.0 release

Doc4.3/Contents.html

@@ -84,11 +84,8 @@ <h3><a href="Windows.html#Windows">3 Getting started on Windows </a></h3>
 <ul>
 <li><a href="Windows.html#Windows_csharp">C#</a>
 <li><a href="Windows.html#Windows_java">Java</a>
-<li><a href="Windows.html#Windows_perl">Perl</a>
 <li><a href="Windows.html#Windows_python">Python</a>
 <li><a href="Windows.html#Windows_tcl">TCL</a>
-<li><a href="Windows.html#Windows_r">R</a>
-<li><a href="Windows.html#Windows_ruby">Ruby</a>
 </ul>
 <li><a href="Windows.html#Windows_other_compilers">Instructions for using the Examples with other compilers</a>
 </ul>
@@ -143,16 +140,17 @@ <h3><a href="SWIG.html#SWIG">5 SWIG Basics</a></h3>
 <li><a href="SWIG.html#SWIG_nn2">Running SWIG</a>
 <ul>
 <li><a href="SWIG.html#SWIG_nn3">Input format</a>
-<li><a href="SWIG.html#SWIG_output">SWIG Output</a>
+<li><a href="SWIG.html#SWIG_output">SWIG output</a>
 <li><a href="SWIG.html#SWIG_nn5">Comments</a>
 <li><a href="SWIG.html#SWIG_nn6">C Preprocessor</a>
-<li><a href="SWIG.html#SWIG_nn7">SWIG Directives</a>
-<li><a href="SWIG.html#SWIG_nn8">Parser Limitations</a>
+<li><a href="SWIG.html#SWIG_nn7">SWIG directives</a>
+<li><a href="SWIG.html#SWIG_nn8">Parser limitations</a>
+<li><a href="SWIG.html#SWIG_parse_tree">Parse tree</a>
 </ul>
-<li><a href="SWIG.html#SWIG_nn9">Wrapping Simple C Declarations</a>
+<li><a href="SWIG.html#SWIG_nn9">Wrapping simple C declarations</a>
 <ul>
-<li><a href="SWIG.html#SWIG_nn10">Basic Type Handling</a>
-<li><a href="SWIG.html#SWIG_nn11">Global Variables</a>
+<li><a href="SWIG.html#SWIG_nn10">Basic type handling</a>
+<li><a href="SWIG.html#SWIG_nn11">Global variables</a>
 <li><a href="SWIG.html#SWIG_nn12">Constants</a>
 <li><a href="SWIG.html#SWIG_nn13">A brief word about const</a>
 <li><a href="SWIG.html#SWIG_nn14">A cautionary tale of char *</a>

Doc4.3/Extending.html

@@ -86,14 +86,17 @@ <H2><a name="Extending_nn2">41.1 Introduction</a></H2>
 
 
 <p>
-This chapter describes SWIG's internal organization and the process by which
-new target languages can be developed.    First, a brief word of warning---SWIG
+This chapter primarily describes SWIG's internal organization and the process by which
+new target languages can be developed.
+It also provides details for debugging and extending existing target languages and functionality.
+</p>
+
+<p>
+First, a brief word of warning---SWIG
 is continually evolving.
 The information in this chapter is mostly up to
 date, but changes are ongoing.   Expect a few inconsistencies.
-</p>
 
-<p>
 Also, this chapter is not meant to be a hand-holding tutorial.  As a starting point,
 you should probably look at one of SWIG's existing modules.
 </p>
@@ -285,10 +288,14 @@ <H3><a name="Extending_nn6">41.4.1 Preprocessing</a></H3>
 
 <p>
 As a debugging aid, the text that SWIG feeds to its C++ parser can be
-obtained by running <tt>swig -E interface.i</tt>.  This output
-probably isn't too useful in general, but it will show how macros have
+obtained by running <tt>swig -E interface.i</tt>.
+This option, like the same option that regular C/C++ compilers support, generates the preprocessed output
+and is useful for looking at how macros have
 been expanded as well as everything else that goes into the low-level
 construction of the wrapper code.
+Also, like a regular C/C++ compiler, the preprocessed output can be generated in one invocation and
+then fed back in with a second invocation.
+This is the approach that the <a href="CCache.html#CCache">CCache</a> tool uses as part of its strategy to speed up repeated builds with the same inputs.
 </p>
 
 <H3><a name="Extending_nn7">41.4.2 Parsing</a></H3>
@@ -465,6 +472,7 @@ <H3><a name="Extending_nn8">41.4.3 Parse Trees</a></H3>
 stage <tt>n</tt> of processing.
 Adding the <tt>-debug-quiet</tt> option is recommended as it removes some noise which is not usually needed,
 that is, the display of many linked list pointers and symbol table pointers.
+See <a href="Extending.html#Extending_debugging_options">Debugging Options</a> for a full list.
 </p>
 
 <div class="shell">
@@ -977,6 +985,57 @@ <H3><a name="Extending_nn13">41.4.8 SWIG and XML</a></H3>
 your mind as a model.
 </p>
 
+<p>
+In addition to the options beginning <tt>-debug-</tt> for dumping out SWIG's parse tree in a simple text format,
+the parse tree can also be dumped as XML.
+There are three options below, where <tt>file</tt> specifies the name of a file for generating the resulting XML into:
+</p>
+
+<ol>
+<li>
+<p>
+<tt>-xmlout &lt;file&gt;</tt>
+</p>
+<p>
+Use this XML option in addition to any target language options.
+The parse tree is dumped after the final stage of processing, that is, after the target language has finished processing.
+It is useful for seeing the parse tree at stage 4 after any target language processing.
+The parse tree dumped is very similar in content to that generated by <tt>-debug-top 4</tt>.
+</p>
+</li>
+
+<li>
+<p>
+<tt>-xml -o &lt;file&gt;</tt>
+</p>
+<p>
+Use this XML option without specifying a target language.
+The parse tree that is dumped is the same as if there was a no target language option.
+It is useful for seeing the parse tree at stage 3, which is the same as stage 4, as there is no target language processing.
+The parse tree dumped is very similar in content to that generated by <tt>-debug-top 3</tt>.
+</p>
+</li>
+
+<li>
+<p>
+<tt>-xml -xmllite -o &lt;file&gt;</tt>
+</p>
+<p>
+Same as above, except the addition of <tt>-xmllite</tt> reduces the output by skipping some type information, that is, the typescope and typetab nodes.
+</p>
+</li>
+</ol>
+
+<p>
+The parse tree generated using <tt>-xmlout</tt> is much bigger than that using <tt>-xml</tt> as the target languages
+process numerous extra SWIG system files and also add to the parse tree quite considerably in stage 4.
+</p>
+
+<p>
+The XML is a dump of SWIG's internal parse tree and as such it is subject to change at any
+time as and when SWIG's implementation changes.
+</p>
+
 <H2><a name="Extending_nn14">41.5 Primitive Data Structures</a></H2>
 
 

Doc4.3/Preface.html

@@ -206,13 +206,16 @@ <H2><a name="Preface_nn9">1.8 Backwards compatibility</a></H2>
 
 <div class="code"><pre>
 #if SWIG_VERSION &gt;= 0x010311
-/* Use some fancy new feature */
+/* Use some fancy new SWIG feature */
 #endif
 </pre></div>
 
 <p>
-Note: The version symbol is not defined in the generated SWIG
-wrapper file. The SWIG preprocessor has defined SWIG_VERSION since SWIG-1.3.11.
+Note: The SWIG preprocessor has defined SWIG_VERSION since SWIG-1.3.11.
+</p>
+
+<p>
+The SWIG_VERSION macro is also generated into the SWIG wrapper file for use by the C preprocessor in the generated code since SWIG-4.1.0.
 </p>
 
 <H2><a name="Preface_release_notes">1.9 Release notes</a></H2>
@@ -438,7 +441,7 @@ <H3><a name="Preface_testing">1.12.4 Testing</a></H3>
 </p>
 
 <p>
-Note: The test-suite currently contains over 600 tests.  If you
+Note: The test-suite currently contains over 800 tests.  If you
 have many different target languages installed and a slow machine, it
 might take more than an hour to run the test-suite.
 </p>

Doc4.3/SWIG.html

@@ -14,16 +14,17 @@ <H1><a name="SWIG">5 SWIG Basics</a></H1>
 <li><a href="#SWIG_nn2">Running SWIG</a>
 <ul>
 <li><a href="#SWIG_nn3">Input format</a>
-<li><a href="#SWIG_output">SWIG Output</a>
+<li><a href="#SWIG_output">SWIG output</a>
 <li><a href="#SWIG_nn5">Comments</a>
 <li><a href="#SWIG_nn6">C Preprocessor</a>
-<li><a href="#SWIG_nn7">SWIG Directives</a>
-<li><a href="#SWIG_nn8">Parser Limitations</a>
+<li><a href="#SWIG_nn7">SWIG directives</a>
+<li><a href="#SWIG_nn8">Parser limitations</a>
+<li><a href="#SWIG_parse_tree">Parse tree</a>
 </ul>
-<li><a href="#SWIG_nn9">Wrapping Simple C Declarations</a>
+<li><a href="#SWIG_nn9">Wrapping simple C declarations</a>
 <ul>
-<li><a href="#SWIG_nn10">Basic Type Handling</a>
-<li><a href="#SWIG_nn11">Global Variables</a>
+<li><a href="#SWIG_nn10">Basic type handling</a>
+<li><a href="#SWIG_nn11">Global variables</a>
 <li><a href="#SWIG_nn12">Constants</a>
 <li><a href="#SWIG_nn13">A brief word about const</a>
 <li><a href="#SWIG_nn14">A cautionary tale of char *</a>
@@ -137,9 +138,12 @@ <H2><a name="SWIG_nn2">5.1 Running SWIG</a></H2>
      -xml            - Generate XML wrappers
 
 Experimental Target Language Options
-     -mzscheme       - Generate MzScheme/Racket wrappers
+     -c              - Generate C wrappers
      -ocaml          - Generate OCaml wrappers
 
+Deprecated Target Language Options
+     -mzscheme       - Generate MzScheme/Racket wrappers
+
 General Options
      -addextern      - Add extra extern declarations
      -c++            - Enable C++ processing
@@ -297,7 +301,7 @@ <H3><a name="SWIG_nn3">5.1.1 Input format</a></H3>
 used in input files to parser generation tools such as yacc or bison.
 </p>
 
-<H3><a name="SWIG_output">5.1.2 SWIG Output</a></H3>
+<H3><a name="SWIG_output">5.1.2 SWIG output</a></H3>
 
 
 <p>
@@ -363,8 +367,9 @@ <H3><a name="SWIG_nn5">5.1.3 Comments</a></H3>
 <p>
 C and C++ style comments may appear anywhere in interface files.  In
 previous versions of SWIG, comments were used to generate
-documentation files. However, this feature is currently under repair
-and will reappear in a later SWIG release.
+documentation files.
+Doxygen comments can now be used to generate target language specific documentation, see the
+<a href="Doxygen.html">Doxygen</a> chapter.
 </p>
 
 <H3><a name="SWIG_nn6">5.1.4 C Preprocessor</a></H3>
@@ -391,7 +396,7 @@ <H3><a name="SWIG_nn6">5.1.4 C Preprocessor</a></H3>
 extensions are described in the "<a href="Preprocessor.html#Preprocessor">Preprocessor</a>" chapter.
 </p>
 
-<H3><a name="SWIG_nn7">5.1.5 SWIG Directives</a></H3>
+<H3><a name="SWIG_nn7">5.1.5 SWIG directives</a></H3>
 
 
 <p>
@@ -422,7 +427,7 @@ <H3><a name="SWIG_nn7">5.1.5 SWIG Directives</a></H3>
 it is parsing an input file.
 </p>
 
-<H3><a name="SWIG_nn8">5.1.6 Parser Limitations</a></H3>
+<H3><a name="SWIG_nn8">5.1.6 Parser limitations</a></H3>
 
 
 <p>
@@ -520,7 +525,16 @@ <H3><a name="SWIG_nn8">5.1.6 Parser Limitations</a></H3>
 described on p. 234 of K&amp;R).
 </p>
 
-<H2><a name="SWIG_nn9">5.2 Wrapping Simple C Declarations</a></H2>
+<H3><a name="SWIG_parse_tree">5.1.7 Parse tree</a></H3>
+
+
+<p>
+SWIG can dump its parse tree in either a simple text or XML format.
+This can be useful for advanced development or debugging purposes.
+Details are covered in the developer documentation <a href="Extending.html#Extending">Extending SWIG</a> chapter.
+</p>
+
+<H2><a name="SWIG_nn9">5.2 Wrapping simple C declarations</a></H2>
 
 
 <p>
@@ -583,7 +597,7 @@ <H2><a name="SWIG_nn9">5.2 Wrapping Simple C Declarations</a></H2>
 next few sections describe various aspects of this mapping.
 </p>
 
-<H3><a name="SWIG_nn10">5.2.1 Basic Type Handling</a></H3>
+<H3><a name="SWIG_nn10">5.2.1 Basic type handling</a></H3>
 
 
 <p>
@@ -708,7 +722,7 @@ <H3><a name="SWIG_nn10">5.2.1 Basic Type Handling</a></H3>
 You may need to write some special conversion functions.
 </p>
 
-<H3><a name="SWIG_nn11">5.2.2 Global Variables</a></H3>
+<H3><a name="SWIG_nn11">5.2.2 Global variables</a></H3>
 
 
 <p>
@@ -1395,7 +1409,7 @@ <H3><a name="SWIG_nn23">5.4.2 Return by value</a></H3>
 Vector *wrap_cross_product(Vector *v1, Vector *v2) {
   Vector x = *v1;
   Vector y = *v2;
-  Vector *result = new Vector(cross_product(x, y)); // Uses default copy constructor
+  Vector *result = new Vector(cross_product(x, y)); // Uses default copy or move constructor
   return result;
 }
 </pre></div>

Doc4.3/Sections.html

@@ -8,7 +8,7 @@
 <H1><a name="Sections">SWIG-4.3 Documentation</a></H1>
 
 <p>
-Last update : SWIG-4.3.0 (in progress)
+Last update : SWIG-4.3.0 (20 Oct 2024)
 </p>
 
 <H2><a name="Sections_Sections">Sections</a></H2>