changes to documentation

4 files changed, 55 insertions, 96 deletions

diff --git a/documentation/functions.html b/documentation/functions.html
index d0f0bbf..58f2394 100644
--- a/documentation/functions.html
+++ b/documentation/functions.html
@@ -5,16 +5,14 @@
     astonishingly simple. As long as you have a native C++ function that has 
     one of the following four signatures, you can call it almost directly from PHP:
 </p>
-
 <p>
 <pre class="language-c++"><code>void example1();
 void example2(Php::Parameters &amp;params);
 Php::Value example3();
 Php::Value example4(Php::Parameters &amp;params);</code></pre>
 </p>
-
 <p>
-    These function signatures show you two important PHP-CPP classes, the
+    The function signatures show you two important PHP-CPP classes, the
     Php::Value class and the Php::Parameters class. The Php::Value class is a
     powerful class that does the same as a regular PHP $variable: it can hold
     almost any value (integers, floating pointer numbers, strings, but also
@@ -46,14 +44,14 @@ extern "C" {
 }</code></pre>
 </p>
 <p>
-    It is not difficult to imagine what the above code does. If you enable
+    It is not difficult to imagine what the above code does. If you deploy
     this extension, you can create PHP scripts in which you can call myFunction(),
-    which will print "example output" to stdout.
+    that will print "example output" to stdout.
 </p>
 <p>
     As we've said before, there are four types of functions that can be used. In
     this first example we showed the most simple one: a function that does not
-    take any parameter, and that returns nothing. What if you
+    take any parameters, and that returns nothing. What if you
     want to return a value from your function?
 </p>
 <p>
@@ -113,11 +111,11 @@ string
 </p>
 <p>
     We've mentioned that there are four types of native functions that can be
-    added to the extension object. We've showed you two example functions
-    that did not accept any parameters. Let's round up with the most 
-    complicated function: one that accepts parameters and also returns a result. 
-    The following example function takes a variable number of parameters, 
-    and returns the sum of all its parameters:
+    added to the extension object. We've showed you two examples, but none of
+    these example functions accepted any parameters. Let's therefore round up with a 
+    final example, one that accepts parameters and also returns a result. 
+    The following function takes a variable number of parameters, 
+    and sums up the integer value of all the parameters:
 </p>
 <pre class="language-c++"><code>#include &lt;phpcpp.h&gt;
 
@@ -136,14 +134,15 @@ extern "C" {
     }
 }</code></pre>
 <p>
+    It looks so simple, doesn't it? 
     The Php::Parameters class is in reality nothing less than a std::vector 
-    filled with Php::Value objects - and you can thus iterate over it. In the
-    example we use the new C++11 way of doing this, and we use the new-for-C++11 
+    filled with Php::Value objects - and you can thus iterate over it. 
+    We use the new C++11 way of doing this, and we use the new-for-C++11 
     "auto" keyword to ask the compiler to find out what type of variables are 
     stored in the parameters vector (it are Php::Value objects, of course).
 </p>
 <p>
-    And in this example you can again see how powerful the Php::Value class is. 
+    And you can again see how powerful the Php::Value class is. 
     It can be used on the right hand side of a += operator to be added to 
     an integer value, and the final integer result variable is automatically 
     converted back into a Php::Value object when the function returns - just as if 
@@ -165,10 +164,14 @@ extern "C" {
     which is exactly the same behavior of a PHP script.
 </p>
 <p>
-    All functions that accept parameters are called with a variable number of
-    parameters. It is up to you, the extension programmer, to check the number
-    of parameters, and to check whether the parameters that are passed to your
-    function are of the right type. In most situations however, you want
+    All parameter-accepting functions can be called with a variable number of
+    parameters. It is therefore valid to call them from PHP with zero, one, two 
+    or even ten thousand parameters. It is up to you, the extension programmer, to check 
+    this, and to check whether the parameters that are passed to your
+    function are of the right type.
+</p>
+<p>
+    In most situations however, you want
     your functions to be called with a fixed number of parameters, or with
     parameters of a certain type. To achieve that, you will have to specify
     the parameter types when you add your function to the extension object.
diff --git a/documentation/loading-extensions.html b/documentation/loading-extensions.html
index e126743..00524de 100644
--- a/documentation/loading-extensions.html
+++ b/documentation/loading-extensions.html
@@ -1,59 +1,24 @@
 <h1>How does PHP load its extensions?</h1>
 <p>
-    You probably already know that native PHP extensions are compiled into *.so 
+    You probably know that native PHP extensions are compiled into *.so 
     files on unix-like systems, and *.dll files in Windows environments, and that
     the global php.ini file holds a list of all extensions available on your system.
     This means that if you're building your own extension, you are also going to
     create such a *.so or *.dll file and you have to update the PHP 
     configuration file so that your own extension is loaded by PHP.
 </p>
-<h3>Where to find your PHP configuration files?</h3>
-<p>
-    If for one reason or another you can not find the PHP configuration file(s) 
-    on your system, you can run the following command from the command line:
-</p>
-<p>
-<pre>
-php --ini
-</pre>
-</p>
-<p>
-    This will output a list of all configuration files that are loaded by PHP.
-    Extensions are enabled by adding "extension=name.so" lines to the
-    configuration file - where 'name' should of course be replaced by the name of 
-    your extension. A default PHP installation already comes with many default 
-    extensions, so in the configuration file(s) on your system you will certainly 
-    find a number of these "extension=name.so" lines.
-</p>
-<p>
-    The extension lines either take an absolute path ("extension=/path/to/extension.so")
-    or a relative path ("extension=extension.so"). If you'd like to use relative
-    paths, you must make sure that you've copied your extension *.so file to the
-    default extension directory, so that PHP can find it. To find out this default
-    extension directory, use the following command line instruction:
-</p>
-<p>
-<pre>
-php -i|grep extension_dir
-</pre>
-</p>
-<p>
-    The extension dir often has the form /usr/lib/php5/20121212 - or a different
-    date string depending on the PHP version you use.
-</p>
-
 <h2>The get_module() startup function</h2>
 <p>
     Before we explain how you can create your own extension, we first explain
-    what PHP does to load an extension. When PHP starts, it loads the *.ini configuration 
-    file(s) that we just described and for each "extension=name.so" line in these
-    files, it opens the appropriate library, and calls the "get_module()"
-    function from it. Each extension library (your extension too) must therefore 
-    define and implement this "get_module()" C function. The function is called by 
-    PHP right after the library is loaded (and thus way before pageviews are handled), 
-    and it should return a memory address that points to a structure that holds information 
-    about all functions, classes, variables and constants that are made available 
-    by the extension. 
+    what PHP does to load an extension. When PHP starts, it loads the *.ini 
+    configuration file(s) from its configuration directory and for each 
+    "extension=name.so" line in these config files, it opens the appropriate 
+    library, and calls the "get_module()" function from it. Each extension library 
+    (your extension too) must therefore define and implement this "get_module()" 
+    function. The function is called by PHP right after the library is loaded 
+    (and thus way before pageviews are handled), and it should return a memory 
+    address that points to a structure that holds information about all functions, 
+    classes, variables and constants that are made available by the extension. 
 </p>
 <p>
     The structure that the get_module() returns is defined in the header files of 
@@ -104,7 +69,7 @@ extern "C" {
     you a simple to use API.
 </p>
 <p>
-    The next thing that you'll notice it that we placed the get_module() function
+    The next thing that you'll notice is that we placed the get_module() function
     inside an 'extern "C"' code block. As the name of the library already gives away, 
     PHP-CPP is a C++ library. However, PHP expects your library, and especially your 
     get_module() function, to be implemented in C and not in C++. That's why we've 
@@ -120,7 +85,7 @@ extern "C" {
 </p>
 <p>
     This, by the way, is also the only macro that PHP-CPP offers. PHP-CPP intends to 
-    be a very straightforward C++ library, without using magic or tricks from 
+    be a plain C++ library, without using magic or tricks from 
     pre-processors. What you see is what you get: If something looks like a 
     function, you can be sure that it actually IS a function, and when something 
     looks like a variable, you can be sure that it also IS a variable.
@@ -146,5 +111,5 @@ extern "C" {
 <p>
     Note that the example above does not yet export any native functions or 
     native classes to PHP - it only creates the extension. That is going to be 
-    the next step.
+    <a href="your-first-extension">the next step</a>.
 </p>
diff --git a/documentation/parameters.html b/documentation/parameters.html
index daaf73c..b40bd5b 100644
--- a/documentation/parameters.html
+++ b/documentation/parameters.html
@@ -3,8 +3,9 @@
     PHP has a mechanism to enforce the types of function parameters, and to accept
     parameters either by reference or by value. In the <a href="functions">
     earlier examples</a>, we had not yet used that mechanism, and we left it to 
-    the function implementations to inspect the 'Php::Parameters' object, and to 
-    check whether the number of parameters were correct, and of the right type.
+    the function implementations to inspect the 'Php::Parameters' object (which
+    is a std::vector of Php::Value objects), and to check whether the number of 
+    parameters is correct, and of the right type.
 </p>
 <p>
     However, the 'Extension::add()' method takes a third optional parameter that
@@ -32,7 +33,7 @@ extern "C" {
 }</pre></code>
 </p>
 <p>
-    Above you see that we passed in additional information when we registered the
+    Above you see that we pass in additional information when we register the
     "example" function. We tell the PHP engine that our function accepts three parameters:
     the first parameter must be numeric, while the other ones are 
     instances of type "ExampleClass" and "OtherClass". In the end, your native C++ 
@@ -43,9 +44,10 @@ extern "C" {
 </p>
 <h2>Can you really enforce scalar parameters?</h2>
 <p>
-    In PHP there is no way to enforce the type of a scalar parameter. When you
-    write a function in PHP, it is possible to enforce that the function receives
-    an object of a certain type, or an array, but not that you want to receive 
+    You may be surprised to see that we specified the first parameter to be of
+    type Numeric. After all, in PHP there is no offical way to enforce the type of a 
+    scalar parameter. When you write a function in PHP, it is possible to enforce 
+    that the function receives an object or an array, but not that you want to receive 
     a string or an integer.
 </p>
 <p>
@@ -73,13 +75,14 @@ function example3(int $param)
 </code></pre>
 </p>
 <p>
-    The same is true for native functions. Although the core PHP engine offers
-    the possibility to specify that your function only accepts parameters of type 
+    The same is true for native functions. Although the core PHP engine and PHP-CPP
+    library both offer the possibility to specify that your function accepts parameters of type 
     "Php::Type::Numeric" or of type "Php::Type::String", this setting is further 
     completely ignored. Maybe this is going to change in the 
     future (let's hope so), but for now it is only meaningful to specify the
     parameter type for objects and arrays. We have however chosen to still offer 
-    this feature in PHP-CPP to be ready for future versions of PHP.
+    this feature in PHP-CPP to be ready for future versions of PHP, but for now
+    the specification of the numeric parameter in our example is meaningless.
 </p>
 <p>
     To come back to our example, the following functions calls can now be done
@@ -108,7 +111,7 @@ example("x", "y", "z");
 </p>
 <p>
     The PHP engine will trigger an error if your function is called with wrong
-    parameters, and will not make the call to your function.
+    parameters, and will not make the actual call to the native function.
 </p>
 <h2>The Php::ByVal class further explained</h2>
 <p>
diff --git a/documentation/your-first-extension.html b/documentation/your-first-extension.html
index cebc44f..bb262a3 100644
--- a/documentation/your-first-extension.html
+++ b/documentation/your-first-extension.html
@@ -1,28 +1,16 @@
 <h1>Your first extension</h1>
 <p>
-    When you create your own PHP-CPP extensions, you also have to compile and
-    deploy them. A normal PHP script only has to be copied to a web server to be 
-    deployed, but it takes a little more effort to deploy an extension.
-</p>
-<p>
-    To help your users, customers, and/or operations department with deploying
-    your native extensions, you best create a Makefile with settings and 
-    instructions for the compiler. All that is then left for someone to do, 
-    is run "make" and "make install". 
-</p>
-<p>
-    But creating a Makefile is not the only thing that you have to do. You 
-    will also have to make changes to the system wide php.ini
-    file to actually enable the extension. The best way to do that is create
-    your own small yourextension.ini file, and copy that to the PHP config file
-    directory of your webserver.
+    When you create your own PHP-CPP extension, you also have to compile and
+    deploy it. A normal PHP script only has to be copied to a web server to be 
+    deployed, but it takes a little more effort to deploy an extension: you need
+    a Makefile, an extension specific php.ini file and of course the *.cpp files
+    in which you implement your extension.
 </p>
 <p>
     To help you out with these steps, we have created an almost empty extension with 
-    all the required utilities for starting up a new extension. It contains a 
-    sample Makefile, a sample configuration file, and a first main.cpp file
-    in which the get_module() call is already implemented. This gives you a
-    kickstart in developing an extension.
+    all these required files. It contains a sample Makefile, a sample configuration 
+    file, and a first main.cpp file in which the get_module() call is already 
+    implemented. This gives you a kickstart in developing an extension.
 </p>
 <p>
     <ul>