Requirements and Installation
-----------------------------
+
The recommended way to install this library is using Composer.
Detailed installation instructions are in the [INSTALL.md](INSTALL.md) file, along with system requirements listing.
Documentation
-------------
-See the documentation page at [gggeek.github.io/phpxmlrpc](https://gggeek.github.io/phpxmlrpc) for a list of the
-library main features and all project related information.
-
-The user manual can be found in the doc/manual directory: [phpxmlrpc_manual.adoc](doc/manual/phpxmlrpc_manual.adoc)
-
-Older release tarballs also contain HTML and PDF versions of the manual, as well as an automatically generated API
-documentation. The documentation for the API is currently available online at [http://gggeek.github.io/phpxmlrpc/doc-4/api/index.html](http://gggeek.github.io/phpxmlrpc/doc-4/api/index.html)
-
-*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*
-
-Upgrading
----------
-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.
-
-Running tests
--------------
-
-The recommended way to run the library test suite is via the provided Docker containers.
-A handy shell script is available that simplifies usage of Docker.
+See the documentation page at [gggeek.github.io/phpxmlrpc](https://gggeek.github.io/phpxmlrpc) for a list of the
+library main features and all project related information, including information about online resources such as debuggers
+and demo servers.
-The full sequence of operations is:
+The user manual can be found in the doc/manual directory: [phpxmlrpc_manual.adoc](doc/manual/phpxmlrpc_manual.adoc).
+It includes sections about upgrading from previous versions as well as running the library's testing suite.
- ./tests/ci/vm.sh build
- ./tests/ci/vm.sh start
- ./tests/ci/vm.sh runtests
- ./tests/ci/vm.sh stop
+The manual is formatted as an asciidoc file - if viewing it locally, it is recommended to either use an IDE which can
+natively render asciidoc, or view it as html via in-browser rendering by serving it via a webserver and accessing /doc/manual/index.html
- # and, once you have finished all testing related work:
- ./tests/ci/vm.sh cleanup
+Automatically-generated documentation for the API is available online at [http://gggeek.github.io/phpxmlrpc/doc-4/api/index.html](http://gggeek.github.io/phpxmlrpc/doc-4/api/index.html)
-By default, tests are run using php 7.4 in a Container based on Ubuntu 20 Focal.
-You can change the version of PHP and Ubuntu in use by setting the environment variables PHP_VERSION and UBUNTU_VERSION
-before building the Container.
+You are encouraged to look also at the code examples found in the demo/ directory.
-To generate the code-coverage report, run `./tests/ci/vm.sh runcoverage`
+Note: to reduce the size of the download, the demo files are not part of the default package installed with Composer.
+You can either make sure they are available locally, by installing the library using Composer option `--prefer-install=source`
+(when doing so, make sure that the demo folder is not directly accessible from the internet, ie. it is not within the
+webserver root directory), or just check them out online at https://github.com/gggeek/phpxmlrpc/tree/master/demo.
License
-------
and set appropriately the variable `+$editorpath+`.
+== Upgrading
+
+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 available online at https://github.com/gggeek/phpxmlrpc/blob/master/doc/api_changes_v4.md
+and report back any undocumented issue using GitHub.
+
+== Running tests
+
+The recommended way to run the library's test suite is via the provided Docker containers.
+A handy shell script is available that simplifies usage of Docker.
+
+The full sequence of operations is:
+
+ ./tests/ci/vm.sh build
+ ./tests/ci/vm.sh start
+ ./tests/ci/vm.sh runtests
+ ./tests/ci/vm.sh stop
+
+ # and, once you have finished all testing related work:
+ ./tests/ci/vm.sh cleanup
+
+By default, tests are run using php 7.4 in a Container based on Ubuntu 20 Focal.
+You can change the version of PHP and Ubuntu in use by setting the environment variables PHP_VERSION and UBUNTU_VERSION
+before building the Container.
+
+To generate the code-coverage report, run `./tests/ci/vm.sh runcoverage`
+
+Note: to reduce the size of the download, the test suite is not part of the default package installed with Composer.
+In order to have it onboard, install the library using Composer option `--prefer-install=source`.
+
++++++++++++++++++++++++++++++++++++++
<!-- Keep this comment at the end of the file
Local variables:
git://git.onelab.eu / plcapi.git / commitdiff