Update examples to talk about a version of Perl which we actually still

support.
Use $ for the shell prompt character, since that matches what most users
will see.
Compile code for shared use with -fPIC, since that's required for most
architectures, and a good idea even on x86.
Fix Sun C++ example to use CC not g++ for invoking the compiler.
Drop space before colon in prose. 


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

1 files changed, 71 insertions, 73 deletions

diff --git a/Doc/Manual/Perl5.html b/Doc/Manual/Perl5.html
index da2344759..0a4b61bd5 100644
--- a/Doc/Manual/Perl5.html
+++ b/Doc/Manual/Perl5.html
@@ -113,7 +113,7 @@ options are found near the end of the chapter.
 
 <p>
 To build a Perl5 module, run SWIG using the <tt>-perl</tt> option as
-follows :
+follows:
 </p>
 
 <div class="code"><pre>
@@ -137,7 +137,7 @@ To build the module, you will need to compile the file
 
 
 <p>
-In order to compile, SWIG extensions need the following Perl5 header files :</p>
+In order to compile, SWIG extensions need the following Perl5 header files:</p>
 
 <div class="code"><pre>
 #include "Extern.h"
@@ -149,19 +149,19 @@ In order to compile, SWIG extensions need the following Perl5 header files :</p>
 These are typically located in a directory like this</p>
 
 <div class="code"><pre>
-/usr/lib/perl5/5.00503/i386-linux/CORE
+/usr/lib/perl/5.14/CORE
 </pre></div>
 
 <p>
 The SWIG configuration script automatically tries to locate this directory so
 that it can compile examples.  However, if you need to find out where the directory is
-loaded, an easy way to find out is to run Perl itself.
+located, an easy way to find out is to ask Perl itself:
 </p>
 
 <div class="code">
 <pre>
-% perl -e 'use Config; print $Config{archlib};'
-/usr/lib/perl5/5.00503/i386-linux
+$ perl -e 'use Config; print "$Config{archlib}\n";'
+/usr/lib/perl/5.14
 </pre>
 </div>
 
@@ -176,9 +176,9 @@ using commands like this (shown for Linux):
 
 <div class="code"><pre>
 $ swig -perl example.i
-% gcc example.c
-% gcc -c example_wrap.c -I/usr/lib/perl5/5.00503/i386-linux/CORE -Dbool=char
-% gcc -shared example.o example_wrap.o -o example.so
+$ gcc -fPIC example.c
+$ gcc -fPIC -c example_wrap.c -I/usr/lib/perl/5.14/CORE -Dbool=char
+$ gcc -shared example.o example_wrap.o -o example.so
 </pre></div>
 
 <p>
@@ -204,7 +204,7 @@ the target should be named `<tt>example.so</tt>',
 <p>
 It is also possible to use Perl to build dynamically loadable modules
 for you using the MakeMaker utility.  To do this, write a Perl
-script such as the following :</p>
+script such as the following:</p>
 
 <div class="targetlang"><pre>
 # File : Makefile.PL
@@ -218,12 +218,12 @@ WriteMakefile(
 </pre></div>
 
 <p>
-Now, to build a module, simply follow these steps :</p>
+Now, to build a module, simply follow these steps:</p>
 
 <div class="code"><pre>
-% perl Makefile.PL
-% make
-% make install
+$ perl Makefile.PL
+$ make
+$ make install
 </pre></div>
 
 <p>
@@ -239,10 +239,10 @@ and Randal Schwartz.</p>
 If you machine does not support dynamic loading or if you've tried to
 use it without success, you can build a new version of the Perl
 interpreter with your SWIG extensions added to it. To build a static
-extension, you first need to invoke SWIG as follows :</p>
+extension, you first need to invoke SWIG as follows:</p>
 
 <div class="code"><pre>
-% swig -perl -static example.i
+$ swig -perl -static example.i
 </pre></div>
 
 <p>
@@ -253,7 +253,7 @@ By default SWIG includes code for dynamic loading, but the
 Next, you will need to supply a <tt>main()</tt> function that
 initializes your extension and starts the Perl interpreter. While,
 this may sound daunting, SWIG can do this for you automatically as
-follows :</p>
+follows:</p>
 
 <div class="targetlang"><pre>
 %module example
@@ -268,10 +268,10 @@ extern int fact(int);
 </pre></div>
 
 <p>
-The same thing can be accomplished by running SWIG as follows :</p>
+The same thing can be accomplished by running SWIG as follows:</p>
 
 <div class="code"><pre>
-% swig -perl -static -lperlmain.i example.i
+$ swig -perl -static -lperlmain.i example.i
 </pre></div>
 
 <p>
@@ -290,7 +290,7 @@ for a dynamic module, but change the link line to something like this:
 </p>
 
 <div class="code"><pre>
-% gcc example.o example_wrap.o -L/usr/lib/perl5/5.00503/i386-linux/CORE \
+$ gcc example.o example_wrap.o -L/usr/lib/perl/5.14/CORE \
 	-lperl -lsocket -lnsl -lm -o myperl
 </pre></div>
 
@@ -323,9 +323,7 @@ A common error received by first-time users is the following:
 <div class="targetlang">
 <pre>
 use example;
-Can't locate example.pm in @INC (@INC contains: /usr/lib/perl5/5.00503/i386-lin
-ux /usr/lib/perl5/5.00503 /usr/lib/perl5/site_perl/5.005/i386-linux /usr/lib/pe
-rl5/site_perl/5.005 .) at - line 1.
+Can't locate example.pm in @INC (@INC contains: /etc/perl /usr/local/lib/perl/5.14.2 /usr/local/share/perl/5.14.2 /usr/lib/perl5 /usr/share/perl5 /usr/lib/perl/5.14 /usr/share/perl/5.14 /usr/local/lib/site_perl .) at - line 1.
 BEGIN failed--compilation aborted at - line 1.
 </pre>
 </div>
@@ -363,7 +361,7 @@ Another common error is the following:
 <pre>
 use example;
 Can't load './example.so' for module example: ./example.so: 
-undefined symbol: Foo at /usr/lib/perl5/5.00503/i386-linux/DynaLoader.pm line 169.
+undefined symbol: Foo at /usr/lib/perl/5.14/i386-linux/DynaLoader.pm line 169.
 
  at - line 1
 BEGIN failed--compilation aborted at - line 1.
@@ -409,7 +407,7 @@ error when you try to use your module:
 <pre>
 use example;
 Can't load './example.so' for module example: libfoo.so: cannot open shared object file: 
-No such file or directory at /usr/lib/perl5/5.00503/i386-linux/DynaLoader.pm line 169.
+No such file or directory at /usr/lib/perl/5.14/i386-linux/DynaLoader.pm line 169.
 
  at - line 1
 BEGIN failed--compilation aborted at - line 1.
@@ -472,10 +470,10 @@ compiler.  For example:
 </p>
 
 <div class="code"><pre>
-% swig -c++ -perl example.i
-% g++ -c example.cxx
-% g++ -c example_wrap.cxx -I/usr/lib/perl5/5.00503/i386-linux/CORE
-% <b>g++ -shared example.o example_wrap.o -o example.so</b>
+$ swig -c++ -perl example.i
+$ g++ -fPIC -c example.cxx
+$ g++ -fPIC -c example_wrap.cxx -I/usr/lib/perl/5.14/i386-linux/CORE
+$ <b>g++ -shared example.o example_wrap.o -o example.so</b>
 </pre></div>
 
 <p>
@@ -485,10 +483,10 @@ Solaris, you often need to add an extra library <tt>-lCrun</tt> like this:
 </p>
 
 <div class="code"><pre>
-% swig -c++ -perl example.i
-% g++ -c example.cxx
-% g++ -c example_wrap.cxx -I/usr/lib/perl5/5.00503/i386-linux/CORE
-% g++ -shared example.o example_wrap.o -o example.so <b>-lCrun</b>
+$ swig -c++ -perl example.i
+$ CC -c example.cxx
+$ CC -c example_wrap.cxx -I/usr/lib/perl/5.14/i386-linux/CORE
+$ CC -shared example.o example_wrap.o -o example.so <b>-lCrun</b>
 </pre></div>
 
 <p>
@@ -503,7 +501,7 @@ it needs to be.  So you should compile the wrapper like:
 </p>
 
 <div class="code"><pre>
-% g++ -c example_wrap.cxx -I/usr/lib/perl/5.8.0/CORE -D_GNU_SOURCE
+$ g++ -fPIC -c example_wrap.cxx -I/usr/lib/perl/5.8.0/CORE -D_GNU_SOURCE
 </pre></div>
 
 <p>
@@ -511,7 +509,7 @@ it needs to be.  So you should compile the wrapper like:
 </p>
 
 <div class="code"><pre>
-% perl -e 'use Config; print $Config{ccflags};'
+$ perl -e 'use Config; print "$Config{ccflags}\n";'
 </pre></div>
 
 <p>
@@ -519,8 +517,8 @@ So you could also compile the wrapper like
 </p>
 
 <div class="code"><pre>
-% g++ -c example_wrap.cxx -I/usr/lib/perl/5.8.0/CORE \
-`perl -e 'use Config; print $Config{ccflags}'`
+$ g++ -fPIC -c example_wrap.cxx -I/usr/lib/perl/5.8.0/CORE \
+`perl -MConfig -e 'print $Config{ccflags}'`
 </pre></div>
 
 <p>
@@ -568,8 +566,8 @@ can behave strangely when working with multiple modules.
 
 <p>
 It should be noted that you may get a lot of error messages
-about the `<tt>bool</tt>' datatype when compiling a C++ Perl module. If
-you experience this problem, you can try the following :</p>
+about the '<tt>bool</tt>' datatype when compiling a C++ Perl module. If
+you experience this problem, you can try the following:</p>
 
 <ul>
 <li>Use <tt>-DHAS_BOOL</tt> when compiling the SWIG wrapper code
@@ -643,7 +641,7 @@ although the procedure may be similar with other compilers.
 <p>
 If you are developing your application within Microsoft developer
 studio, SWIG can be invoked as a custom build option.  The process
-roughly requires these steps :</p>
+roughly requires these steps:</p>
 
 <ul>
 <li>Open up a new workspace and use the AppWizard to select a DLL
@@ -651,7 +649,7 @@ project.
 
 <li>Add both the SWIG interface file (the .i file), any supporting C
 files, and the name of the wrapper file that will be created by SWIG
-(ie. <tt>example_wrap.c</tt>).  Note : If using C++, choose a
+(ie. <tt>example_wrap.c</tt>).  Note: If using C++, choose a
 different suffix for the wrapper file such as
 <tt>example_wrap.cxx</tt>. Don't worry if the wrapper file doesn't
 exist yet--Developer studio will keep a reference to it around.
@@ -689,7 +687,7 @@ Now, assuming you made it this far, SWIG will be automatically invoked when
 you build your project.  Any changes made to the interface file will
 result in SWIG being automatically invoked to produce a new version of
 the wrapper file.  To run your new Perl extension, simply run Perl and
-use the use command as normal. For example :
+use the use command as normal. For example:
 </p>
 
 <div class="targetlang"><pre>
@@ -758,7 +756,7 @@ double Spam;
 </pre></div>
 
 <p>
-is accessed as follows :</p>
+is accessed as follows:</p>
 
 <div class="targetlang"><pre>
 use example;
@@ -858,7 +856,7 @@ print example::FOO,"\n";
 SWIG represents pointers as blessed references.  A blessed reference
 is the same as a Perl reference except that it has additional
 information attached to it indicating what kind of reference it
-is. That is, if you have a C declaration like this :</p>
+is. That is, if you have a C declaration like this:</p>
 
 <div class="code"><pre>
 Matrix *new_Matrix(int n, int m);
@@ -880,7 +878,7 @@ generated.</p>
 
 <p>
 To check to see if a value is the NULL pointer, use the
-<tt>defined()</tt> command :</p>
+<tt>defined()</tt> command:</p>
 
 <div class="targetlang"><pre>
 if (defined($ptr)) {
@@ -904,7 +902,7 @@ In general, <tt>$a</tt> and <tt>$b</tt> will be different--since they
 are different references.  Thus, it is a mistake to check the equality
 of <tt>$a</tt> and <tt>$b</tt> to check the equality of two C
 pointers.  The correct method to check equality of C pointers is to
-dereference them as follows :
+dereference them as follows:
 </p>
 
 <div class="targetlang"><pre>
@@ -1099,7 +1097,7 @@ void Bar_f_set(Bar *b, Foo *val) {
 
 <p>
 C++ classes are wrapped by building a set of low level accessor functions. 
-Consider the following class :
+Consider the following class:
 </p>
 
 <div class="code"><pre>
@@ -1117,7 +1115,7 @@ static void print(List *l);
 </pre></div>
 
 <p>
-When wrapped by SWIG, the following functions are created :
+When wrapped by SWIG, the following functions are created:
 </p>
 
 <div class="code"><pre>
@@ -1272,11 +1270,11 @@ The following C++ operators are currently supported by the Perl module:
 <p>
 When you create a SWIG extension, everything gets placed into
 a single Perl module. The name of the module is determined by the
-<tt>%module</tt> directive. To use the module, do the following :
+<tt>%module</tt> directive. To use the module, do the following:
 </p>
 
 <div class="targetlang"><pre>
-% perl5
+$ perl5
 use example;                      # load the example module
 print example::fact(4),"\n"       # Call a function in it
 24
@@ -1342,17 +1340,17 @@ nested namespace simply provide the fully qualified name in your
 <!--
 <p>
 This can be changed by giving SWIG the -package
-option :
+option:
 </p>
 
 <div class="code"><pre>
-% swig -perl -package Foo example.i
+$ swig -perl -package Foo example.i
 </pre></div>
 
 <p>
 In this case, you still create a module called `<tt>example</tt>' exactly as before, but
 all of the functions in that module will be installed into the package
-`<tt>Foo</tt>.' For example :
+`<tt>Foo</tt>.' For example:
 </p>
 
 <div class="targetlang"><pre>
@@ -1588,7 +1586,7 @@ The SWIG <tt>%exception</tt> directive can be used to create a
 user-definable exception handler for converting exceptions in your
 C/C++ program into Perl exceptions.  The chapter on customization features
 contains more details, but suppose you have a C++ class like the
-following :
+following:
 </p>
 
 <div class="code"><pre>
@@ -1796,7 +1794,7 @@ The <tt>$input</tt> variable is the input object (usually a <tt>SV *</tt>).
 </p>
 
 <p>
-When this example is used in Perl5, it will operate as follows :
+When this example is used in Perl5, it will operate as follows:
 </p>
 
 <div class="targetlang"><pre>
@@ -1805,7 +1803,7 @@ $n = example::fact(6);
 print "$n\n";
 ...
 
-Output :
+Output:
 Received an integer : 6
 720
 </pre></div>
@@ -2200,7 +2198,7 @@ char **get_args() {
 
 <p>
 When this module is compiled, the wrapped C functions can be used in a
-Perl script as follows :
+Perl script as follows:
 </p>
 
 <div class="targetlang"><pre>
@@ -2227,7 +2225,7 @@ number of output values.
 <p>
 The total number of return values should not exceed the number of
 input values unless you explicitly extend the argument stack.  This
-can be done using the <tt>EXTEND()</tt> macro as in :
+can be done using the <tt>EXTEND()</tt> macro as in:
 </p>
 
 <div class="code"><pre>
@@ -2286,7 +2284,7 @@ int multout(double a, double b, double *OUTPUT, double *OUTPUT);
 <p>
 When this function is called, the output arguments are appended to the stack used
 to return results.  This shows up an array in Perl.
-For example :
+For example:
 </p>
 
 <div class="targetlang"><pre>
@@ -2299,7 +2297,7 @@ print "multout(7,13) = @r\n";
 
 
 <p>
-Consider the following data structure :
+Consider the following data structure:
 </p>
 
 <div class="code"><pre>
@@ -2364,7 +2362,7 @@ to copy the converted array into a C data structure.
 <p>
 A frequent confusion on the SWIG mailing list is errors caused by the
 mixing of Perl references and C pointers.  For example, suppose you
-have a C function that modifies its arguments like this :
+have a C function that modifies its arguments like this:
 </p>
 
 <div class="code"><pre>
@@ -2374,7 +2372,7 @@ void add(double a, double b, double *c) {
 </pre></div>
 
 <p>
-A common misinterpretation of this function is the following Perl script :
+A common misinterpretation of this function is the following Perl script:
 </p>
 
 <div class="targetlang"><pre>
@@ -2411,7 +2409,7 @@ To make this work with a reference, you can use a typemap such as this:
 </pre></div>
 
 <p>
-Now, if you place this before the add function, you can do this :
+Now, if you place this before the add function, you can do this:
 </p>
 
 <div class="targetlang"><pre>
@@ -2544,7 +2542,7 @@ high level wrappers.  The wrappers, in turn, interact with the low-level procedu
 
 
 <p>
-Suppose you have the following SWIG interface file :
+Suppose you have the following SWIG interface file:
 </p>
 
 <div class="code"><pre>
@@ -2672,7 +2670,7 @@ $v-&gt;DESTROY();
 <p>
 In order for proxy classes to work properly, it is necessary for Perl
 to manage some mechanism of object ownership.  Here's the crux of the
-problem---suppose you had a function like this :
+problem---suppose you had a function like this:
 </p>
 
 <div class="code"><pre>
@@ -2685,7 +2683,7 @@ Vector *Vector_get(Vector *v, int index) {
 This function takes a Vector pointer and returns a pointer to another
 Vector.  Such a function might be used to manage arrays or lists of
 vectors (in C).  Now contrast this function with the constructor for a
-Vector object :
+Vector object:
 </p>
 
 <div class="code"><pre>
@@ -2757,7 +2755,7 @@ sophisticated languages.
 
 
 <p>
-Suppose that we have a new object that looks like this :
+Suppose that we have a new object that looks like this:
 </p>
 
 <div class="code"><pre>
@@ -2774,7 +2772,7 @@ struct Particle {
 In this case, the members of the structure are complex objects that
 have already been encapsulated in a Perl proxy class.  To handle
 these correctly, we use the <tt>%BLESSEDMEMBERS</tt> hash which would
-look like this (along with some supporting code) :
+look like this (along with some supporting code):
 </p>
 
 <div class="targetlang"><pre>
@@ -2796,7 +2794,7 @@ unmodified.
 </p>
 
 <p>
-This implementation allows us to operate on nested structures as follows :
+This implementation allows us to operate on nested structures as follows:
 </p>
 
 <div class="targetlang"><pre>
@@ -2811,7 +2809,7 @@ $p-&gt;{f}-&gt;{x} = 0.0;
 
 <p>
 When functions take arguments involving a complex object, it is
-sometimes necessary to write a proxy function.  For example :
+sometimes necessary to write a proxy function.  For example:
 </p>
 
 <div class="code"><pre>
@@ -2822,7 +2820,7 @@ double dot_product(Vector *v1, Vector *v2);
 Since Vector is an object already wrapped into a proxy class, we need
 to modify this function to accept arguments that are given in the form
 of tied hash tables.  This is done by creating a Perl function like
-this :
+this:
 </p>
 
 <div class="targetlang"><pre>
@@ -2846,7 +2844,7 @@ identical manner.
 <p>
 Simple C++ inheritance is handled using the Perl <tt>@ISA</tt> array
 in each class package. For example, if you have the following
-interface file :
+interface file:
 </p>
 
 <div class="code"><pre>
@@ -2881,7 +2879,7 @@ public:
 </pre></div>
 
 <p>
-The resulting, Perl wrapper class will create the following code :
+The resulting, Perl wrapper class will create the following code:
 </p>
 
 <div class="targetlang"><pre>