Prepare docs for release of version 4.0

diff --git a/NEWS b/NEWS
index 48798f3..4fd0aad 100644 (file)
--- a/NEWS
+++ b/NEWS
@@ -1,4 +1,4 @@
-XML-RPC for PHP version 4.0.0 alpha - 2015/7/13
+XML-RPC for PHP version 4.0.0 - 2016/1/20

 
 This release does away with the past and starts a transition to modern-world php.
 
 
 This release does away with the past and starts a transition to modern-world php.
 

diff --git a/README.md b/README.md
index 304f080..2b48d5e 100644 (file)
--- a/README.md
+++ b/README.md
@@ -10,15 +10,25 @@ Detailed installation instructions are in the [INSTALL.md](INSTALL.md) file, alo
 
 Documentation
 -------------
 
 Documentation
 -------------

+
+*NB: the user manual has not been updated yet with all the changes made in version 4. Please consider it unreliable!*
+
+*You are encouraged to look instead the code examples found in the demo/ directory*
+

 The user manual can be found in the doc/manual directory, in Asciidoc format: [phpxmlrpc_manual.adoc](doc/manual/phpxmlrpc_manual.adoc)
 
 Release tarballs also contain the HTML and PDF versions, as well as an automatically generated API documentation.
 
 The user manual can be found in the doc/manual directory, in Asciidoc format: [phpxmlrpc_manual.adoc](doc/manual/phpxmlrpc_manual.adoc)
 
 Release tarballs also contain the HTML and PDF versions, as well as an automatically generated API documentation.
 

-*NB: the user manual has not been updated yet with all the changes made in version 4. Please consider it unreliable!*
-

 Upgrading
 ---------
 Upgrading
 ---------

-If you are upgrading from version 3 or earlier, please read the docs in [doc/api_changes_v4.md](doc/api_changes_v4.md)
+If you are upgrading from version 3 or earlier you have two options:
+
+1. adapt your code to the new API (all changes needed are described in [doc/api_changes_v4.md](doc/api_changes_v4.md))
+
+2. use instead the *compatibility layer* which is provided. Instructions and pitfalls described in [doc/api_changes_v4.md](doc/api_changes_v4.md##enabling-compatibility-with-legacy-code)
+
+In any case, read carefully the docs in [doc/api_changes_v4.md](doc/api_changes_v4.md) and report back any undocumented
+issue using GitHub.

 
 License
 -------
 
 License
 -------

diff --git a/doc/api_changes_v4.md b/doc/api_changes_v4.md
index 7b04ecd..1a01da9 100644 (file)
--- a/doc/api_changes_v4.md
+++ b/doc/api_changes_v4.md
@@ -8,18 +8,18 @@ It is not necessary any more to include the files xmlrpc.inc, xmlrpcs.inc and xm
 library classes available.
 
 Instead, it is recommended to rely on class autoloading.
 library classes available.
 
 Instead, it is recommended to rely on class autoloading.

- 
-* If you are using Composer, just install the library by declaring it as dependency for your project in composer.json 
+
+* If you are using Composer, just install the library by declaring it as dependency for your project in composer.json

 
         "require": {
             ...,
             "phpxmlrpc/phpxmlrpc": "~4.0"
         },
 
         "require": {
             ...,
             "phpxmlrpc/phpxmlrpc": "~4.0"
         },

-       
+

 * If you do not use Composer, an autoloader for the library can be found in src/Atuloader.php.
   The php example files in the demo/client folder do make use of it.
   Example code to set up the autoloader:
 * If you do not use Composer, an autoloader for the library can be found in src/Atuloader.php.
   The php example files in the demo/client folder do make use of it.
   Example code to set up the autoloader:

-    
+

         include_once <path to library> . "/src/Autoloader.php";
         PhpXmlRpc\Autoloader::register();
 
         include_once <path to library> . "/src/Autoloader.php";
         PhpXmlRpc\Autoloader::register();
 


@@ -32,7 +32,7 @@ New class naming
 ----------------
 
 All classes have ben renamed, are now properly namespaced and follow the CamelCase naming convention.
 ----------------
 
 All classes have ben renamed, are now properly namespaced and follow the CamelCase naming convention.

-Existing class methods and members have been preserved; all new method names follow camelCase. 
+Existing class methods and members have been preserved; all new method names follow camelCase.

 
 Conversion table:
 
 
 Conversion table:
 


@@ -137,9 +137,9 @@ Other
 * when serialize() is invoked on a response and its payload can not be serialized, an exception is thrown instead of
   ending all execution
 
 * when serialize() is invoked on a response and its payload can not be serialized, an exception is thrown instead of
   ending all execution
 

-* all error messages now mention the class and method which generated name
+* all error messages now mention the class and method which generated them

 
 

-* all library source code has been moved to the src/ directory 
+* all library source code has been moved to the src/ directory

 
 * all source code has been reformatted according to modern PSR standards
 
 
 * all source code has been reformatted according to modern PSR standards
 


@@ -173,7 +173,7 @@ Below is the list of all known changes and possible pitfalls when enabling 'comp
 ### Usage of global variables
 
 * ALL global variables which existed after including xmlrpc.inc in version 3 still do exist after including it in v. 4
 ### Usage of global variables
 
 * ALL global variables which existed after including xmlrpc.inc in version 3 still do exist after including it in v. 4

- 
+

 * Code which relies on using (as in 'reading') their value will keep working unchanged
 
 * Changing the value of some of those variables does not have any effect anymore on library operation.
 * Code which relies on using (as in 'reading') their value will keep working unchanged
 
 * Changing the value of some of those variables does not have any effect anymore on library operation.


@@ -204,9 +204,9 @@ Below is the list of all known changes and possible pitfalls when enabling 'comp
         $GLOBALS['xmlrpc_null_apache_encoding'] = true;
         // new line needed now
         PhpXmlRpc\PhpXmlRpc::importGlobals();
         $GLOBALS['xmlrpc_null_apache_encoding'] = true;
         // new line needed now
         PhpXmlRpc\PhpXmlRpc::importGlobals();

-        
+

     Alternative solution:
     Alternative solution:

-    
+

         include('xmlrpc.inc');
         PhpXmlRpc\PhpXmlRpc::$xmlrpc_null_apache_encoding = true;
 
         include('xmlrpc.inc');
         PhpXmlRpc\PhpXmlRpc::$xmlrpc_null_apache_encoding = true;
 


@@ -228,7 +228,7 @@ Below is the list of all known changes and possible pitfalls when enabling 'comp
   instances will return the new classes.
 
     Example:
   instances will return the new classes.
 
     Example:

-        
+

         is_a(php_xmlrpc_encode('hello world'), 'xmlrpcval') => false
         is_a(php_xmlrpc_encode('hello world'), 'PhpXmlRpc\Value') => true
 
         is_a(php_xmlrpc_encode('hello world'), 'xmlrpcval') => false
         is_a(php_xmlrpc_encode('hello world'), 'PhpXmlRpc\Value') => true