Rework README files (#1541)

17 files changed, 1732 insertions, 1175 deletions

diff --git a/README.md b/README.md
index 6be10c96c8e..d03f7f86372 100644
--- a/README.md
+++ b/README.md
@@ -20,6 +20,7 @@ or retrying failed connection attempts (to name just a few of dozens of such low
 Remote procedure calls ([RPCs][rpcs]) are at the heart of the Ice framework.
 
 You create RPCs with an easy 2-step process:
+
 1. Define the contract between your client and your server with the [Slice][slice] language—Ice's [IDL][idl].
 2. Run the Slice compiler on these Slice definitions to generate stubs in the programming language(s) of your choice.
 
@@ -85,7 +86,7 @@ languages.
 
 ## Building Ice from source
 
-[C++](cpp/BUILDING.md) | [C#](csharp/BUILDING.md) | [Java](java/BUILDING.md) | [Java Compat](java-compat/BUILDING.md) | [JavaScript/TypeScript](js) | [MATLAB](matlab) | [Objective-C](objective-c) | [PHP](php) | [Python](python) | [Ruby](ruby) | [Swift](swift)
+[C++](cpp/BUILDING.md) | [C#](csharp/BUILDING.md) | [Java](java/BUILDING.md) | [Java Compat](java-compat/BUILDING.md) | [JavaScript/TypeScript](js/BUILDING.md) | [MATLAB](matlab/BUILDING.md) | [Objective-C](objective-c/BUILDING.md) | [PHP](php/BUILDING.md) | [Python](python/BUILDING.md) | [Ruby](ruby/BUILDING.md) | [Swift](swift/BUILDING.md)
 
 ## Copyright and license
 
diff --git a/cpp/README.md b/cpp/README.md
index 048641540de..75ce7dd7609 100644
--- a/cpp/README.md
+++ b/cpp/README.md
@@ -2,7 +2,8 @@
 
 [Getting started C++11] | [Examples C++11] | [Getting started C++98] | [Examples C++98] | [NuGet packages] | [Documentation] | [Building from source]
 
-The [Ice framework] provides everything you need to build networked applications, including RPC, pub/sub, server deployment, and more.
+The [Ice framework] provides everything you need to build networked applications,
+including RPC, pub/sub, server deployment, and more.
 
 Ice for C++ is the C++ implementation of Ice.
 
diff --git a/csharp/README.md b/csharp/README.md
index 30996bab6eb..a648cc51faa 100644
--- a/csharp/README.md
+++ b/csharp/README.md
@@ -4,7 +4,7 @@
 
 The [Ice framework] provides everything you need to build networked applications, including RPC, pub/sub, server deployment, and more.
 
-Ice for .NET is the C# / .NET implementation of Ice.
+Ice for .NET is the C# / .NET implementation of the Ice framework.
 
 ## Sample Code
 
diff --git a/js/BUILDING.md b/js/BUILDING.md
new file mode 100644
index 00000000000..474c7f0322d
--- /dev/null
+++ b/js/BUILDING.md
@@ -0,0 +1,220 @@
+# Ice for JavaScript Build Instructions
+
+This file describes how to build and install Ice for JavaScript from source
+code. If you prefer, you can also download [binary distributions] for the
+supported platforms.
+
+<!-- TOC depthFrom:2 -->
+
+- [JavaScript Build Requirements](#javascript-build-requirements)
+- [Building the JavaScript libraries and NodeJS packages](#building-the-javascript-libraries-and-nodejs-packages)
+- [Running the JavaScript Tests](#running-the-javascript-tests)
+  - [Browser Information](#browser-information)
+    - [Self-Signed Certificate](#self-signed-certificate)
+    - [Windows 8](#windows-8)
+    - [Secure WebSockets on iOS and Android](#secure-websockets-on-ios-and-android)
+      - [Installing Certificates on iOS](#installing-certificates-on-ios)
+      - [Installing Certificates on Android](#installing-certificates-on-android)
+- [Installing a Source Build](#installing-a-source-build)
+
+<!-- /TOC -->
+
+## JavaScript Build Requirements
+
+To build Ice for JavaScript you must have the following:
+
+- The `slice2js` compiler from Ice for C++. If you have not built Ice for C++
+  in this source distribution, refer to the
+  [C++ build instructions](../cpp/README.md).
+- Node.js 4.6 or later
+
+## Building the JavaScript libraries and NodeJS packages
+
+Change to the Ice for JavaScript source subdirectory:
+
+```shell
+cd js
+```
+
+Run these commands to build the libraries and tests:
+
+```shell
+npm install
+npm run build
+```
+
+On Windows, you need to set the platform and configuration in order to locate
+`slice2js`. For example, if you have built C++ with the x64 Release
+configuration, you can use the following command to build JavaScript:
+
+```shell
+npm run build -- --cppPlatform x64 --cppConfiguration Release
+```
+
+Alternatively you can use the `CPP_PLATFORM` and `CPP_CONFIGURATION` environment
+variables:
+
+```shell
+set CPP_PLATFORM=x64
+set CPP_CONFIGURATION=Debug
+npm run build
+```
+
+Upon successful completion, the build generates libraries in the `lib`
+subdirectory, including compressed and minified versions.
+
+For older browsers that do not support all of the required ECMAScript 6
+features used by Ice for JavaScript, we provide pre-compiled versions of
+the libraries using the [Babel] JavaScript compiler. These libraries
+depend on the [core-js] and [regenerator-runtime] packages
+and  are available in the `lib/es5` subdirectory with the same names as
+the main libraries.
+
+## Running the JavaScript Tests
+
+Python is required to run the test suite. Additionally, the Glacier2 tests
+require the Python module `passlib`, which you can install with the command:
+
+```shell
+pip install passlib
+```
+
+The scripts also require Ice for Python, you can build Ice for Python from
+[python](../python) folder of this source distribution or install the Python
+module `zeroc-ice`, using the following command:
+
+```shell
+pip install zeroc-ice
+```
+
+The test suites require that the Ice for C++ tests be built in the `cpp`
+subdirectory of this source distribution.
+
+You can start the NodeJS tests with:
+
+```shell
+python allTests.py
+```
+
+If everything worked out, you should see lots of `ok` messages. In case of a
+failure, the tests abort with `failed`.
+
+You can start the browser tests with:
+
+```shell
+python allTests.py --browser Manual
+```
+
+Then open the test page (http://127.0.0.1:8080/start) using a web browser.
+These tests require a web browser with ECMAScript 6 support, such as
+a recent version of Chrome, Firefox, Microsoft Edge or Safari.
+
+If you are using another web browser, such as Internet Explorer, you should
+use instead:
+
+```shell
+python allTests.py --browser Manual --es5
+```
+
+Then open the test page (http://127.0.0.1:8080/es5/start)
+
+This runs a version of the test suite transpiled to ECMAScript 5 using [Babel].
+
+On macOS the first time you run the tests, you will be prompted for your
+password. This is necessary to configure the trust setting for the HTTP
+server certificate, which will enable you to connect to the HTTP server
+with SSL via your web browser.
+
+### Browser Information
+
+#### Self-Signed Certificate
+
+The browser-based tests allow you to choose whether to run the tests over
+non-secure WebSocket (WS) or secure WebSocket (WSS) connections. The WSS
+connections in these tests rely on a self-signed certificate, `cacert`,
+provided in the certs(../certs) directory.
+
+To successfully run the tests over WSS, additional action may be necessary
+depending on the browser you're using:
+
+- Chrome
+   You'll be presented with a warning about the site's security certificate.
+   Click the "Proceed anyway" button to temporarily accept the certificate.
+
+- Firefox
+   You'll see a warning saying "This Connection is Untrusted". Open Firefox's
+   Preferences or Options dialog, click on the Advanced section, select the
+   Certificates tab and click on the "View Certificates..." button. In the
+   Authorities tab, click the "Import..." button, navigate to the `cacert.pem`
+   file, and add it as a certificate authority (CA) for trusting web sites.
+   After closing the dialogs, reload the test page to continue. You should
+   uninstall this certificate after running the tests.
+
+- Internet Explorer and Microsoft Edge
+   Run the management console (mmc.exe) and add the Certificates snap-in for
+   the computer account. Then select Console Root > Certificates (Local
+   Computer) > Trusted Root Certificate Authorities. In the Action menu, choose
+   All Tasks and Import. Navigate to the `cacert.der` file and import it into
+   the Trusted Root Certificate Authorities. Reload the test page to continue.
+   You should uninstall this certificate after running the tests.
+
+#### Windows 8
+
+On Windows 8, network isolation prevents Internet Explorer from
+connecting to 127.0.0.1. To work around this limitation, you'll need to disable
+Internet Explorer's "Protected Mode". Open the "Internet Options" dialog and in
+the "Security" settings tab, deselect the "Enable Protected Mode" checkbox.
+
+#### Secure WebSockets on iOS and Android
+
+To use WSS on iOS and Android it may be required (depending on browser and
+platform) that the server certificate's common name matches the computer hosting
+the tests, and that the test certificate authority be installed on your device.
+
+First you'll need to generate new certificates to match the IP address of the
+computer hosting the tests:
+
+```shell
+certs/makecerts.py [IP address]
+```
+
+Next you must install the certificate authority on your device. The simplest way
+is to email the CA certificate (`certs/cacert.pem`) to yourself and then follow
+the instructions below to install the certificate on your device.
+
+Once installed, you connect to the server using the same IP address used to
+create the certificates.
+
+##### Installing Certificates on iOS
+
+Open the certificate (`cacert.pem`) from the device's email client. You
+will be prompted to create a configuration profile containing this certificate.
+
+##### Installing Certificates on Android
+
+Download the certificate (`cacert.pem`) to the device from an email client.
+Next go to _Settings -> Security -> Install from storage_, and choose
+`cacert.pem`. Enter a name and press OK.
+
+## Installing a Source Build
+
+After a successful build, you can generate a package by running the
+following command:
+
+```shell
+npm pack
+```
+
+This will generate the file `ice-3.7.100.tgz`, which can be installed by running:
+
+```shell
+npm install ice-3.7.100.tgz
+```
+
+To use Ice for JavaScript with a browser, copy the appropriate JavaScript
+library files located in the `lib` directory to your web server.
+
+[binary distributions]: https://zeroc.com/downloads/ice
+[Babel]: https://babeljs.io
+[core-js]: https://www.npmjs.com/package/core-js
+[regenerator-runtime]: https://www.npmjs.com/package/regenerator-runtime
diff --git a/js/README.md b/js/README.md
index f7617a2d7cc..07b488d7dc9 100644
--- a/js/README.md
+++ b/js/README.md
@@ -1,208 +1,52 @@
-# Building Ice for JavaScript
-
-This file describes how to build and install Ice for JavaScript from source
-code. If you prefer, you can also download [binary distributions][1] for the
-supported platforms.
-
-<!-- TOC depthFrom:2 -->
-
-- [JavaScript Build Requirements](#javascript-build-requirements)
-- [Building the JavaScript libraries and NodeJS packages](#building-the-javascript-libraries-and-nodejs-packages)
-- [Running the JavaScript Tests](#running-the-javascript-tests)
-    - [Browser Information](#browser-information)
-        - [Self-Signed Certificate](#self-signed-certificate)
-        - [Windows 8](#windows-8)
-        - [Secure WebSockets on iOS and Android](#secure-websockets-on-ios-and-android)
-            - [Installing Certificates on iOS](#installing-certificates-on-ios)
-            - [Installing Certificates on Android](#installing-certificates-on-android)
-- [Installing a Source Build](#installing-a-source-build)
-
-<!-- /TOC -->
-
-## JavaScript Build Requirements
-
-To build Ice for JavaScript you must have the following:
-
-- The `slice2js` compiler from Ice for C++. If you have not built Ice for C++
-  in this source distribution, refer to the
-  [C++ build instructions](../cpp/README.md).
-- Node.js 4.6 or later
-
-## Building the JavaScript libraries and NodeJS packages
-
-Change to the Ice for JavaScript source subdirectory:
-```
-cd js
-```
-
-Run these commands to build the libraries and tests:
-```
-npm install
-npm run build
-```
-
-On Windows, you need to set the platform and configuration in order to locate
-`slice2js`. For example, if you have built C++ with the x64 Release
-configuration, you can use the following command to build JavaScript:
-```
-npm run build -- --cppPlatform x64 --cppConfiguration Release
-```
-
-Alternatively you can use the `CPP_PLATFORM` and `CPP_CONFIGURATION` environment
-variables:
-```
-set CPP_PLATFORM=x64
-set CPP_CONFIGURATION=Debug
-npm run build
-```
-
-Upon successful completion, the build generates libraries in the `lib`
-subdirectory, including compressed and minified versions.
-
-For older browsers that do not support all of the required ECMAScript 6
-features used by Ice for JavaScript, we provide pre-compiled versions of
-the libraries using the [Babel][2] JavaScript compiler. These libraries
-depend on the `core-js`[3] and `regenerator-runtime`[4] packages
-and  are available in the `lib/es5` subdirectory with the same names as
-the main libraries.
-
-## Running the JavaScript Tests
-
-Python is required to run the test suite. Additionally, the Glacier2 tests
-require the Python module `passlib`, which you can install with the command:
-```
-pip install passlib
-```
-
-The scripts also require Ice for Python, you can build Ice for Python from
-[python](../python) folder of this source distribution or install the Python
-module `zeroc-ice`, using the following command:
-```
-pip install zeroc-ice
-```
-
-The test suites require that the Ice for C++ tests be built in the `cpp`
-subdirectory of this source distribution.
-
-You can start the NodeJS tests with:
-```
-python allTests.py
-```
-
-If everything worked out, you should see lots of `ok` messages. In case of a
-failure, the tests abort with `failed`.
-
-You can start the browser tests with:
-```
-python allTests.py --browser Manual
-```
-
-Then open the test page (http://127.0.0.1:8080/start) using a web browser.
-These tests require a web browser with ECMAScript 6 support, such as
-a recent version of Chrome, Firefox, Microsoft Edge or Safari.
-
-If you are using another web browser, such as Internet Explorer, you should
-use instead:
-```
-python allTests.py --browser Manual --es5
-```
-
-Then open the test page (http://127.0.0.1:8080/es5/start)
-
-This runs a version of the test suite transpiled to ECMAScript 5 using [Babel][2].
-
-On macOS the first time you run the tests, you will be prompted for your
-password. This is necessary to configure the trust setting for the HTTP
-server certificate, which will enable you to connect to the HTTP server
-with SSL via your web browser.
-
-### Browser Information
-
-#### Self-Signed Certificate
-
-The browser-based tests allow you to choose whether to run the tests over
-non-secure WebSocket (WS) or secure WebSocket (WSS) connections. The WSS
-connections in these tests rely on a self-signed certificate, `cacert`,
-provided in the certs(../certs) directory.
-
-To successfully run the tests over WSS, additional action may be necessary
-depending on the browser you're using:
-
-- Chrome
-   You'll be presented with a warning about the site's security certificate.
-   Click the "Proceed anyway" button to temporarily accept the certificate.
-
-- Firefox
-   You'll see a warning saying "This Connection is Untrusted". Open Firefox's
-   Preferences or Options dialog, click on the Advanced section, select the
-   Certificates tab and click on the "View Certificates..." button. In the
-   Authorities tab, click the "Import..." button, navigate to the `cacert.pem`
-   file, and add it as a certificate authority (CA) for trusting web sites.
-   After closing the dialogs, reload the test page to continue. You should
-   uninstall this certificate after running the tests.
-
-- Internet Explorer and Microsoft Edge
-   Run the management console (mmc.exe) and add the Certificates snap-in for
-   the computer account. Then select Console Root > Certificates (Local
-   Computer) > Trusted Root Certificate Authorities. In the Action menu, choose
-   All Tasks and Import. Navigate to the `cacert.der` file and import it into
-   the Trusted Root Certificate Authorities. Reload the test page to continue.
-   You should uninstall this certificate after running the tests.
-
-#### Windows 8
-
-On Windows 8, network isolation prevents Internet Explorer from
-connecting to 127.0.0.1. To work around this limitation, you'll need to disable
-Internet Explorer's "Protected Mode". Open the "Internet Options" dialog and in
-the "Security" settings tab, deselect the "Enable Protected Mode" checkbox.
-
-#### Secure WebSockets on iOS and Android
-
-To use WSS on iOS and Android it may be required (depending on browser and
-platform) that the server certificate's common name matches the computer hosting
-the tests, and that the test certificate authority be installed on your device.
-
-First you'll need to generate new certificates to match the IP address of the
-computer hosting the tests:
-```
-certs/makecerts.py [IP address]
-```
-
-Next you must install the certificate authority on your device. The simplest way
-is to email the CA certificate (`certs/cacert.pem`) to yourself and then follow
-the instructions below to install the certificate on your device.
-
-Once installed, you connect to the server using the same IP address used to
-create the certificates.
-
-##### Installing Certificates on iOS
-
-Open the certificate (`cacert.pem`) from the device's email client. You
-will be prompted to create a configuration profile containing this certificate.
-
-##### Installing Certificates on Android
-
-Download the certificate (`cacert.pem`) to the device from an email client.
-Next go to _Settings -> Security -> Install from storage_, and choose
-`cacert.pem`. Enter a name and press OK.
-
-## Installing a Source Build
-
-After a successful build, you can generate a package by running the
-following command:
-```
-npm pack
-```
-
-This will generate the file `ice-3.7.10.tgz`, which can be installed by running:
-```
-npm install ice-3.7.10.tgz
-```
-
-To use Ice for JavaScript with a browser, copy the appropriate JavaScript
-library files located in the `lib` directory to your web server.
-
-[1]: https://zeroc.com/downloads/ice
-[2]: https://babeljs.io
-[3]: https://www.npmjs.com/package/core-js
-[4]: https://www.npmjs.com/package/regenerator-runtime
+# Ice For JavaScript
+
+[Getting started] | [Examples] | [NPM packages] | [Documentation] | [Building from source]
+
+The [Ice framework] provides everything you need to build networked applications,
+including RPC, pub/sub, server deployment, and more.
+
+Ice for JavaScript is the JavaScript implementation of the Ice framework.
+
+## Sample Code
+
+```slice
+// Slice definitions (Hello.ice)
+
+module Demo
+{
+    interface Hello
+    {
+        void sayHello();
+    }
+}
+```
+
+```javascript
+// Client application (client.js)
+let communicator;
+try
+{
+    communicator = Ice.initialize(process.argv);
+    const hello = await Demo.HelloPrx.checkedCast(
+        communicator.stringToProxy("hello:tcp -h localhost -p 10000"));
+    await hello.sayHello();
+}
+catch(ex)
+{
+    console.log(ex.toString());
+}
+finally
+{
+   if(communicator)
+   {
+      await communicator.destroy();
+   }
+}
+```
+
+[Getting started]: https://doc.zeroc.com/ice/3.7/hello-world-application/writing-an-ice-application-with-javascript
+[Examples]: https://github.com/zeroc-ice/ice-demos/tree/3.7/js
+[NPM Packages]: https://www.npmjs.com/~zeroc
+[Documentation]: https://doc.zeroc.com/ice/3.7
+[Building from source]: https://github.com/zeroc-ice/ice/blob/3.7/js/BUILDING.md
+[Ice framework]: https://github.com/zeroc-ice/ice
\ No newline at end of file
diff --git a/matlab/BUILDING.md b/matlab/BUILDING.md
new file mode 100644
index 00000000000..eb7647d4766
--- /dev/null
+++ b/matlab/BUILDING.md
@@ -0,0 +1,169 @@
+# Ice for MATLAB Build Instructions
+
+This document describes how to build and install Ice for MATLAB from source.
+
+ZeroC provides Ice for MATLAB [toolboxes][1] for MATLAB on Windows and Linux, so building Ice for MATLAB from source is
+usually unnecessary.
+
+* [Building Ice for MATLAB on Windows](#building-ice-for-matlab-on-windows)
+  * [Prerequisites](#prerequisites)
+  * [Build Instructions](#build-instructions)
+  * [Packaging the Ice Toolbox](#packaging-the-ice-toolbox)
+* [Building Ice for MATLAB on Linux](#building-ice-for-matlab-on-linux)
+  * [Prerequisites](#prerequisites-1)
+  * [Build Instructions](#build-instructions-1)
+* [Using Ice for MATLAB](#using-ice-for-matlab)
+  * [Search Path](#search-path)
+  * [Slice Files](#slice-files)
+  * [Loading the Library](#loading-the-library)
+  * [Running the Tests](#running-the-tests)
+
+## Building Ice for MATLAB on Windows
+
+### Prerequisites
+
+The build system requires MATLAB 2016a or later for Windows, Visual Studio 2015
+and a Perl installation.
+
+### Build Instructions
+
+Open a Visual Studio x64 command prompt, `VS2015 x64 Native Tools Command Prompt`. In this Command Prompt, change to the
+`matlab` subdirectory:
+
+```shell
+cd matlab
+```
+
+Now you're ready to build Ice for MATLAB:
+
+```shell
+msbuild msbuild\ice.proj
+```
+
+To build in debug mode instead:
+
+```shell
+msbuild msbuild\ice.proj /p:Configuration=Debug
+```
+
+Upon completion, a build in release mode generates the following components:
+
+* Ice for C++11 libraries, located in `cpp\bin\x64\Release`
+* slice2matlab executable, located in `cpp\bin\x64\Release`
+* ice.mexw64 MEX file, located in `matlab\lib\x64\Release`
+* Prototype and thunk files, located in `matlab\lib\x64\Release`
+* MATLAB code for core Slice files, located in `matlab\lib\generated`
+* MATLAB code for test Slice files, located in `matlab\test\**\generated`
+
+The MATLAB extension depends on Ice for C++ components from the `cpp`
+subdirectory, and those are built if required. It is also possible to build the
+MATLAB extension using Ice C++ NuGet packages by setting the `ICE_BIN_DIST`
+MSBuild property to `cpp`:
+
+```shell
+msbuild msbuild\ice.proj /p:ICE_BIN_DIST=cpp
+```
+
+### Packaging the Ice Toolbox
+
+Use the following command to build the Ice toolbox package:
+
+```shell
+msbuild msbuild\ice.proj /t:Package
+```
+
+This creates the toolbox package `toolbox\ice-<Ice Version>-<MATLAB Version>-win.mltbx`.
+
+You can install the toolbox from within MATLAB by double-clicking on the file.
+
+## Building Ice for MATLAB on Linux
+
+### Prerequisites
+
+The build system requires MATLAB 2017b or MATLAB 2019b for Linux, with a supported C++ compiler and a Perl installation.
+
+* Use GCC 4.9 for 2017b, see [MATLAB 2017b supported compilers][2].
+* Use GCC 6.3 for 2019b, see [MATLAB 2019b supported compilers][3].
+
+We recommend using the following build environments:
+
+* Ubuntu 16.04 (Xenial) with g++-4.9 compiler, for MATLAB 2017b.
+* Debian 9 (Stretch) with the default g++ compiler, for MATLAB 2019b.
+
+### Build Instructions
+
+The MATLAB extension depends on Ice for C++ components from the cpp subdirectory, and those need to be built, using the
+`cpp11-shared` configuration, if you have not built the C++ distribution first review [cpp/README.md](../cpp/README.md).
+
+In a command window, change to the matlab subdirectory:
+
+```shell
+cd matlab
+```
+
+Review the [matlab/config/Make.rules](config/Make.rules) in your build tree and update the configuration if needed. The
+comments in the file provide more information.
+
+Run `make` to build the Ice for MATLAB toolbox and the MATLAB tests. Set `V=1` to get a more detailed build output.
+
+```shell
+make
+```
+
+This creates the toolbox package `toolbox/ice-<Ice Version>-<MATLAB Version>-linux.mltbx`. You can install the toolbox from
+within MATLAB by double-clicking on the file.
+
+To build the Ice for MATLAB toolbox using the C++ binary distribution, set `ICE_BIN_DIST=cpp`, note this is only possible
+with the MATLAB 2019b builds, because MATLAB 2017b needs to use the g++-4.9 that is not compatible with the Xenial
+binary distribution.
+
+When building for MATALB 2017b you must set `CC` and `CXX` variables to use the `gcc-4.9` and `g++-4.9` compilers
+respectively.
+
+```shell
+CC=gcc-4.9
+CXX=g++-4.9
+```
+
+## Using Ice for MATLAB
+
+### Search Path
+
+To use a source build, add the following directories to your MATLAB path:
+
+* `matlab\lib`
+* `matlab\lib\generated`
+* `matlab\lib\x64\Release` (only on Windows platforms)
+* `matlab\lib\x86_64-linux-gnu` (only on Linux platforms)
+
+### Slice Files
+
+Use `slice2matlab` to compile your Slice files. Run `slice2matlab -h` for a description of its command-line options. You
+can place the generated `*.m` files anywhere you like, but the enclosing directory must be in your MATLAB path.
+
+### Loading the Library
+
+The Ice for MATLAB library can be loaded with this command:
+
+```shell
+loadlibrary('ice', @iceproto)
+```
+
+### Running the Tests
+
+The Ice for MATLAB tests are located in `matlab\test`.
+
+Since Ice for MATLAB only supports client functionality, you need test servers from a different language mapping.
+
+Assuming you've installed Ice for Python, run `allTests.py`:
+
+```shell
+python allTests.py
+```
+
+This script automatically starts a Python server for each MATLAB client. MATLAB clients are executed using a minimized
+MATLAB interpreter and the test output is copied to the Command Prompt window.
+
+[1]: https://zeroc.com/downloads/ice
+[2]: https://www.mathworks.com/content/dam/mathworks/mathworks-dot-com/support/sysreq/files/SystemRequirements-Release2017b_SupportedCompilers.pdf
+[3]: https://www.mathworks.com/content/dam/mathworks/mathworks-dot-com/support/sysreq/files/system-requirements-release-2019b-supported-compilers.pdf
diff --git a/matlab/README.md b/matlab/README.md
index 3dd7f3b457c..1805868d40a 100644
--- a/matlab/README.md
+++ b/matlab/README.md
@@ -1,164 +1,55 @@
-# Building Ice for MATLAB
+# Ice for MATLAB
 
-This document describes how to build and install Ice for MATLAB from source.
+[Getting started] | [Examples] | [Documentation] | [Building from source]
 
-ZeroC provides Ice for MATLAB [toolboxes][1] for MATLAB on Windows and Linux, so building Ice for MATLAB from source is
-usually unnecessary.
+The [Ice framework] provides everything you need to build networked applications,
+including RPC, pub/sub, server deployment, and more.
 
-* [Building Ice for MATLAB on Windows](#building-ice-for-matlab-on-windows)
-  * [Prerequisites](#prerequisites)
-  * [Build Instructions](#build-instructions)
-  * [Packaging the Ice Toolbox](#packaging-the-ice-toolbox)
-* [Building Ice for MATLAB on Linux](#building-ice-for-matlab-on-linux)
-  * [Prerequisites](#prerequisites-1)
-  * [Build Instructions](#build-instructions-1)
-* [Using Ice for MATLAB](#using-ice-for-matlab)
-  * [Search Path](#search-path)
-  * [Slice Files](#slice-files)
-  * [Loading the Library](#loading-the-library)
-  * [Running the Tests](#running-the-tests)
+Ice for MATLAB is the MATLAB implementation of the Ice framework.
 
-## Building Ice for MATLAB on Windows
+## Sample Code
 
-### Prerequisites
+```slice
+// Slice definitions (Hello.ice)
 
-The build system requires MATLAB 2016a or later for Windows, Visual Studio 2015
-and a Perl installation.
-
-### Build Instructions
-
-Open a Visual Studio x64 command prompt, `VS2015 x64 Native Tools Command Prompt`. In this Command Prompt, change to the
-`matlab` subdirectory:
-
-```
-cd matlab
+module Demo
+{
+    interface Hello
+    {
+        void sayHello();
+    }
+}
 ```
 
-Now you're ready to build Ice for MATLAB:
-```
-msbuild msbuild\ice.proj
-```
+```matlab
+// Client application (client.m)
+function client(args)
+    addpath('generated');
+    if ~libisloaded('ice')
+        loadlibrary('ice', @iceproto);
+    end
 
-To build in debug mode instead:
-```
-msbuild msbuild\ice.proj /p:Configuration=Debug
-```
+    import Demo.*
 
-Upon completion, a build in release mode generates the following components:
+    if nargin == 0
+        args = {};
+    end
 
- - Ice for C++11 libraries, located in `cpp\bin\x64\Release`
- - slice2matlab executable, located in `cpp\bin\x64\Release`
- - ice.mexw64 MEX file, located in `matlab\lib\x64\Release`
- - Prototype and thunk files, located in `matlab\lib\x64\Release`
- - MATLAB code for core Slice files, located in `matlab\lib\generated`
- - MATLAB code for test Slice files, located in `matlab\test\**\generated`
-
-The MATLAB extension depends on Ice for C++ components from the `cpp`
-subdirectory, and those are built if required. It is also possible to build the
-MATLAB extension using Ice C++ NuGet packages by setting the `ICE_BIN_DIST`
-msbuild property to `cpp`:
-
-```
-msbuild msbuild\ice.proj /p:ICE_BIN_DIST=cpp
-```
-
-### Packaging the Ice Toolbox
-
-Use the following command to build the Ice toolbox package:
-```
-msbuild msbuild\ice.proj /t:Package
-```
-
-This creates the toolbox package `toolbox\ice-<Ice Version>-<MATLAB Version>-win.mltbx`.
-
-You can install the toolbox from within MATLAB by double-clicking on the file.
-
-## Building Ice for MATLAB on Linux
-
-### Prerequisites
-
-The build system requires MATLAB 2017b or MATLAB 2019b for Linux, with a supported C++ compiler and a Perl installation.
-
-* Use GCC 4.9 for 2017b, see [MATLAB 2017b supported compilers][2].
-* Use GCC 6.3 for 2019b, see [MATLAB 2019b supported compilers][3].
-
-We recommend using the following build environments:
-
-* Ubuntu 16.04 (Xenial) with g++-4.9 compiler, for MATLAB 2017b.
-* Debian 9 (Stretch) with the default g++ compiler, for MATLAB 2019b.
-
-### Build Instructions
-
-The MATLAB extension depends on Ice for C++ components from the cpp subdirectory, and those need to be built, using the
-`cpp11-shared` configuration, if you have not built the C++ distribution first review [cpp/README.md](../cpp/README.md).
-
-In a command window, change to the matlab subdirectory:
-
-```
-cd matlab
+    try
+        communicator = Ice.initialize(args);
+        cleanup = onCleanup(@() communicator.destroy());
+        hello = Demo.HelloPrx.checkedCast(
+            communicator.stringToProxy('hello:default -h localhost -p 10000'));
+        hello.sayHello();
+    catch ex
+        fprintf('%s\n', getReport(ex));
+    end
+    rmpath('generated');
+end
 ```
 
-Review the [matlab/config/Make.rules](config/Make.rules) in your build tree and update the configuration if needed. The
-comments in the file provide more information.
-
-Run `make` to build the Ice for MATLAB toolbox and the MATLAB tests. Set `V=1` to get a more detailed build output.
-
-```
-make
-```
-
-This creates the toolbox package `toolbox/ice-<Ice Version>-<MATLAB Version>-linux.mltbx`. You can install the toolbox from
-within MATLAB by double-clicking on the file.
-
-To build the Ice for MATLAB toolbox using the C++ binary distribution, set `ICE_BIN_DIST=cpp`, note this is only possible
-with the MATLAB 2019b builds, because MATLAB 2017b needs to use the g++-4.9 that is not compatible with the Xenial
-binary distribution.
-
-When building for MATALB 2017b you must set `CC` and `CXX` variables to use the `gcc-4.9` and `g++-4.9` compilers
-respectively.
-
-```
-CC=gcc-4.9
-CXX=g++-4.9
-```
-
-## Using Ice for MATLAB
-
-### Search Path
-
-To use a source build, add the following directories to your MATLAB path:
- - `matlab\lib`
- - `matlab\lib\generated`
- - `matlab\lib\x64\Release` (only on Windows platforms)
- - `matlab\lib\x86_64-linux-gnu` (only on Linux platforms)
-
-### Slice Files
-
-Use `slice2matlab` to compile your Slice files. Run `slice2matlab -h` for a description of its command-line options. You
-can place the generated `*.m` files anywhere you like, but the enclosing directory must be in your MATLAB path.
-
-### Loading the Library
-
-The Ice for MATLAB library can be loaded with this command:
-```
-loadlibrary('ice', @iceproto)
-```
-
-### Running the Tests
-
-The Ice for MATLAB tests are located in `matlab\test`.
-
-Since Ice for MATLAB only supports client functionality, you need test servers from a different language mapping.
-
-Assuming you've installed Ice for Python, run `allTests.py`:
-
-```
-python allTests.py
-```
-
-This script automatically starts a Python server for each MATLAB client. MATLAB clients are executed using a minimized
-MATLAB interpreter and the test output is copied to the Command Prompt window.
-
-[1]: https://zeroc.com/downloads/ice
-[2]: https://www.mathworks.com/content/dam/mathworks/mathworks-dot-com/support/sysreq/files/SystemRequirements-Release2017b_SupportedCompilers.pdf
-[3]: https://www.mathworks.com/content/dam/mathworks/mathworks-dot-com/support/sysreq/files/system-requirements-release-2019b-supported-compilers.pdf
+[Getting started]: https://doc.zeroc.com/ice/3.7/hello-world-application/writing-an-ice-application-with-matlab
+[Examples]: https://github.com/zeroc-ice/ice-demos/tree/3.7/matlab
+[Documentation]: https://doc.zeroc.com/ice/3.7
+[Building from source]: https://github.com/zeroc-ice/ice/blob/3.7/matlab/BUILDING.md
+[Ice framework]: https://github.com/zeroc-ice/ice
diff --git a/objective-c/BUILDING.md b/objective-c/BUILDING.md
new file mode 100644
index 00000000000..2207ae69a2d
--- /dev/null
+++ b/objective-c/BUILDING.md
@@ -0,0 +1,159 @@
+# Ice for Objective-C Build Instructions
+
+This page describes how to build and install Ice for Objective-C from source
+code on macOS. If you prefer, you can install a [Homebrew] package instead.
+
+* [Objective\-C Build Requirements](#objective-c-build-requirements)
+  * [Operating Systems and Compilers](#operating-systems-and-compilers)
+* [Building Ice for Objective\-C](#building-ice-for-objective-c)
+  * [Build configurations and platforms](#build-configurations-and-platforms)
+  * [Ice Xcode SDK](#ice-xcode-sdk)
+* [Installing an Objective\-C Source Build](#installing-an-objective-c-source-build)
+* [Building the Test Suite](#building-the-test-suite)
+* [Running the Test Suite](#running-the-test-suite)
+  * [macOS](#macos)
+  * [iOS Simulator](#ios-simulator)
+  * [iOS](#ios)
+
+## Objective-C Build Requirements
+
+### Operating Systems and Compilers
+
+Ice for Objective-C is currently only supported on macOS and iOS, and was
+extensively tested using the operating system and compiler versions listed for
+our [supported platforms].
+
+## Building Ice for Objective-C
+
+The build of Ice for Objective-C requires that you first build Ice for C++ in
+the `cpp` subdirectory for the same configuration(s) and platform(s).
+
+Review the top-level [config/Make.rules](../config/Make.rules) in your build
+tree and update the configuration if needed. The comments in the file provide
+more information.
+
+Change to the Ice for Objective-C source subdirectory:
+
+```shell
+cd objective-c
+```
+
+Run `make` to build the Ice Objective-C libraries and test suite. Set `V=1` to
+get a more detailed build output. You can build only the libraries with the
+`srcs` target, or only the tests with the `tests` target. For example:
+
+```shell
+make V=1 -j8 srcs
+```
+
+### Build configurations and platforms
+
+The Objective-C source tree supports multiple build configurations and
+platforms. To see the supported configurations and platforms:
+
+```shell
+make print V=supported-configs
+make print V=supported-platforms
+```
+
+To build all the supported configurations and platforms:
+
+```shell
+make CONFIGS=all PLATFORMS=all -j8
+```
+
+The `arc-` configurations (for [Automatic Reference Counting]) apply only to
+the test suite; the Ice libraries don't use these configurations, and the same
+Ice for Objective-C library can be used with and without ARC.
+
+### Ice Xcode SDK
+
+The build system supports building Xcode SDKs for Ice. These SDKs allow you to
+easily develop Ice applications with Xcode. To build Xcode SDKs, use the
+`xcodesdk` configurations:
+
+```shell
+make CONFIGS=xcodesdk -j8 srcs  # Build the Objective-C mapping Xcode SDK
+                                # for the default platform
+```
+
+The Xcode SDKs are built into `ice/sdk`.
+
+## Installing an Objective-C Source Build
+
+Simply run `make install`. This will install Ice in the directory specified by
+the `prefix` variable in `../config/Make.rules`.
+
+When compiling Ice programs, you must pass the location of the
+`<prefix>/include` directory to the compiler with the `-I` option, and the
+location of the library directory with the `-L` option.
+
+## Building the Test Suite
+
+`make all` or `make tests` builds the test suite for the platform(s) and
+configuration(s) you selected.
+
+However, in order to run the test suite on `iphoneos`, you need to build the
+Objective-C Controller app from Xcode:
+
+* Open the Objective-C Test Controller project located in the
+  `objective-c/test/ios/controller` directory.
+* Build the `Objective-C Controller` or `Objective-C ARC Controller` app.
+
+## Cleaning the source build
+
+Running `make clean` will remove the binaries created for the default
+configuration and platform.
+
+To clean the binaries produced for a specific configuration or platform, you
+need to specify the `CONFIGS` or `PLATFORMS` variable. For example,
+`make CONFIGS=xcodesdk clean` will clean the Xcode SDK build.
+
+To clean the build for all the supported configurations and platforms, run
+`make CONFIGS=all PLATFORMS=all clean`.
+
+Running `make distclean` will also clean the build for all the configurations
+and platforms. In addition, it will also remove the generated files created by
+the Slice compilers.
+
+## Running the Test Suite
+
+Python is required to run the test suite. After a successful source build, you
+can run the tests as shown below. If everything worked out, you should see lots
+of `ok` messages. In case of a failure, the tests abort with `failed`.
+
+### macOS
+
+```shell
+python3 allTests.py # default config and default platform
+python3 allTests --config=... --platform=... # use the specified config and platform
+```
+
+### iOS Simulator
+
+```shell
+python3 allTests.py --config=xcodesdk --platform=iphonesimulator --controller-app
+```
+
+### iOS
+
+* Start the `Objective-C Controller` or `Objective-C ARC Controller` app on
+ your iOS device, from Xcode.
+* On your Mac:
+
+ ```shell
+python3 allTests.py --config=xcodesdk --platform=iphoneos
+ ```
+
+or
+
+```shell
+python3 allTests.py --config=arc-xcodesdk --platform=iphoneos
+```
+
+All the test clients and servers run on the iOS device, not on your Mac
+computer.
+
+[Homebrew]: https://doc.zeroc.com/ice/3.7/release-notes/using-the-macos-binary-distribution
+[supported platforms]: https://doc.zeroc.com/ice/3.7/release-notes/supported-platforms-for-ice-3-7-10
+[Automatic Reference Counting]: https://en.wikipedia.org/wiki/Automatic_Reference_Counting
diff --git a/objective-c/README.md b/objective-c/README.md
index 0cbfa83dd28..b2bf7348a1d 100644
--- a/objective-c/README.md
+++ b/objective-c/README.md
@@ -1,140 +1,120 @@
-# Building Ice for Objective-C on macOS
+# Ice for Objective-C
 
-This page describes how to build and install Ice for Objective-C from source
-code on macOS. If you prefer, you can install a [Homebrew][1] package instead.
+[Getting started] | [Examples] | [Documentation] | [Building from source]
 
-* [Objective\-C Build Requirements](#objective-c-build-requirements)
-  * [Operating Systems and Compilers](#operating-systems-and-compilers)
-* [Building Ice for Objective\-C](#building-ice-for-objective-c)
-  * [Build configurations and platforms](#build-configurations-and-platforms)
-  * [Ice Xcode SDK](#ice-xcode-sdk)
-* [Installing an Objective\-C Source Build](#installing-an-objective-c-source-build)
-* [Building the Test Suite](#building-the-test-suite)
-* [Running the Test Suite](#running-the-test-suite)
-  * [macOS](#macos)
-  * [iOS Simulator](#ios-simulator)
-  * [iOS](#ios)
+The [Ice framework] provides everything you need to build networked applications, including RPC, pub/sub, server deployment, and more.
 
-## Objective-C Build Requirements
+Ice for Objective-C is the Objective-C implementation of the Ice framework.
 
-### Operating Systems and Compilers
+## Sample Code
 
-Ice for Objective-C is currently only supported on macOS and iOS, and was
-extensively tested using the operating system and compiler versions listed for
-our [supported platforms][2].
+```slice
+// Slice definitions (Hello.ice)
 
-## Building Ice for Objective-C
-
-The build of Ice for Objective-C requires that you first build Ice for C++ in
-the `cpp` subdirectory for the same configuration(s) and platform(s).
-
-Review the top-level [config/Make.rules](../config/Make.rules) in your build
-tree and update the configuration if needed. The comments in the file provide
-more information.
-
-Change to the Ice for Objective-C source subdirectory:
-```
-    cd objective-c
+module Demo
+{
+    interface Hello
+    {
+        void sayHello();
+    }
+}
 ```
-Run `make` to build the Ice Objective-C libraries and test suite. Set `V=1` to
-get a more detailed build output. You can build only the libraries with the
-`srcs` target, or only the tests with the `tests` target. For example:
-```
-    make V=1 -j8 srcs
-```
-
-### Build configurations and platforms
 
-The Objective-C source tree supports multiple build configurations and
-platforms. To see the supported configurations and platforms:
+```objective-c
+// Client application (Client.m)
+#import <objc/Ice.h>
+#import <Hello.h>
+
+int
+main(int argc, char* argv[])
+{
+    int status = 0;
+    @autoreleasepool
+    {
+        id<ICECommunicator> communicator = nil;
+        @try
+        {
+            communicator = [ICEUtil createCommunicator:&argc argv:argv];
+            if(argc > 1)
+            {
+                NSLog(@"%s: too many arguments", argv[0]);
+                return 1;
+            }
+            id<DemoHelloPrx> hello = [DemoHelloPrx uncheckedCast:
+                [communicator stringToProxy:@"hello:default -p 10000"]];
+            [hello sayHello];
+        }
+        @catch(ICELocalException* ex)
+        {
+            NSLog(@"%@", ex);
+            status = 1;
+        }
+
+        [communicator destroy];
+    }
+    return status;
+}
 ```
-    make print V=supported-configs
-    make print V=supported-platforms
-```
-To build all the supported configurations and platforms:
-```
-    make CONFIGS=all PLATFORMS=all -j8
-```
-The `arc-` configurations (for [Automatic Reference Counting][3]) apply only to
-the test suite; the Ice libraries don't use these configurations, and the same
-Ice for Objective-C library can be used with and without ARC.
 
-### Ice Xcode SDK
-
-The build system supports building Xcode SDKs for Ice. These SDKs allow you to
-easily develop Ice applications with Xcode. To build Xcode SDKs, use the
-`xcodesdk` configurations:
-```
-    make CONFIGS=xcodesdk -j8 srcs     # Build the Objective-C mapping Xcode SDK
-                                       # for the default platform
+```objective-c
+// Server application (Server.m)
+#import <objc/Ice.h>
+#import <HelloI.h>
+
+int
+main(int argc, char* argv[])
+{
+    int status = 0;
+    @autoreleasepool
+    {
+        id<ICECommunicator> communicator = nil;
+        @try
+        {
+            communicator = [ICEUtil createCommunicator:&argc argv:argv];
+
+            id<ICEObjectAdapter> adapter = [communicator
+                createObjectAdapterWithEndpoints: @"Hello"
+                endpoints:@"default -p 10000"];
+            [adapter add:[HelloI hello] identity:[ICEUtil stringToIdentity:@"hello"]];
+            [adapter activate];
+            [communicator waitForShutdown];
+        }
+        @catch(ICELocalException* ex)
+        {
+            NSLog(@"%@", ex);
+            status = 1;
+        }
+        [communicator destroy];
+    }
+    return status;
+}
 ```
-The Xcode SDKs are built into `ice/sdk`.
-
-## Installing an Objective-C Source Build
 
-Simply run `make install`. This will install Ice in the directory specified by
-the `prefix` variable in `../config/Make.rules`.
+```objective-c
+// Printer declaration (Printer.h)
+#import <Hello.h>
 
-When compiling Ice programs, you must pass the location of the
-`<prefix>/include` directory to the compiler with the `-I` option, and the
-location of the library directory with the `-L` option.
-
-## Building the Test Suite
-
-`make all` or `make tests` builds the test suite for the platform(s) and
-configuration(s) you selected.
-
-However, in order to run the test suite on `iphoneos`, you need to build the
-Objective-C Controller app from Xcode:
- - Open the Objective-C Test Controller project located in the
- `objective-c/test/ios/controller` directory.
- - Build the `Objective-C Controller` or `Objective-C ARC Controller` app.
-
-## Cleaning the source build
-
-Running `make clean` will remove the binaries created for the default
-configuration and platform.
-
-To clean the binaries produced for a specific configuration or platform, you
-need to specify the `CONFIGS` or `PLATFORMS` variable. For example,
-`make CONFIGS=xcodesdk clean` will clean the Xcode SDK build.
-
-To clean the build for all the supported configurations and platforms, run
-`make CONFIGS=all PLATFORMS=all clean`.
-
-Running `make distclean` will also clean the build for all the configurations
-and platforms. In addition, it will also remove the generated files created by
-the Slice compilers.
+@interface Printer : DemoHello<DemoHello>
+@end
+```
 
-## Running the Test Suite
+```objective-c
+// Printer implementation (Printer.m)
+#import <Printer.h>
 
-Python is required to run the test suite. After a successful source build, you
-can run the tests as shown below. If everything worked out, you should see lots
-of `ok` messages. In case of a failure, the tests abort with `failed`.
+#include <stdio.h>
 
-### macOS
-```
-    python3 allTests.py # default config and default platform
-    python3 allTests --config=... --platform=... # use the specified config and platform
+@implementation Printer
+-(void) sayHello:(ICECurrent*)current
+{
+    printf("Hello World!\n");
+    fflush(stdout);
+}
+@end
 ```
-### iOS Simulator
-```
-    python3 allTests.py --config=xcodesdk --platform=iphonesimulator --controller-app
-```
-### iOS
- - Start the `Objective-C Controller` or `Objective-C ARC Controller` app on
- your iOS device, from Xcode.
- - On your Mac:
- ```
-   python3 allTests.py --config=xcodesdk --platform=iphoneos
- ```
- or
- ```
-   python3 allTests.py --config=arc-xcodesdk --platform=iphoneos
- ```
- All the test clients and servers run on the iOS device, not on your Mac
- computer.
-
-[1]: https://doc.zeroc.com/ice/3.7/release-notes/using-the-macos-binary-distribution
-[2]: https://doc.zeroc.com/ice/3.7/release-notes/supported-platforms-for-ice-3-7-10
-[3]: https://en.wikipedia.org/wiki/Automatic_Reference_Counting
+
+[Getting started]: https://doc.zeroc.com/ice/3.7/hello-world-application/writing-an-ice-application-with-objective-c
+[Examples]: https://github.com/zeroc-ice/ice-demos/tree/3.7/objective-c
+[Documentation]: https://doc.zeroc.com/ice/3.7
+[Building from source]: https://github.com/zeroc-ice/ice/blob/3.7/objective-c/BUILDING.md
+[Ice framework]: https://github.com/zeroc-ice/ice
diff --git a/php/BUILDING.md b/php/BUILDING.md
new file mode 100644
index 00000000000..bf9281b2974
--- /dev/null
+++ b/php/BUILDING.md
@@ -0,0 +1,362 @@
+# Ice for PHP Build Instructions
+
+This page describes how to build and install Ice for PHP from source.
+
+ZeroC provides [binary distributions] for many platforms, including
+Linux and Windows, so building Ice for PHP from source is usually
+unnecessary.
+
+* [PHP Build Requirements](#php-build-requirements)
+* [Building the PHP Extension](#building-the-php-extension)
+  * [Linux or macOS](#linux-or-macos)
+  * [Windows](#windows)
+* [Installing the PHP Extension](#installing-the-php-extension)
+  * [Linux or macOS](#linux-or-macos-1)
+  * [Windows](#windows-1)
+* [PHP Dependencies](#php-dependencies)
+* [PHP Source Files](#php-source-files)
+* [Running the PHP Tests](#running-the-php-tests)
+* [Web Server Permissions](#web-server-permissions)
+* [SELinux Notes for PHP](#selinux-notes-for-php)
+
+## PHP Build Requirements
+
+Ice was extensively tested using the operating systems and compiler versions
+listed on [supported platforms].
+
+On Windows, the build requires a recent version of Visual Studio and the
+[Ice Builder for Visual Studio].
+
+## Building the PHP Extension
+
+### Linux or macOS
+
+The build of Ice for PHP requires that you first build Ice for C++ in the `cpp`
+subdirectory.
+
+From the top-level source directory, edit `config/Make.rules` to establish
+your build configuration. The comments in the file provide more information.
+
+Our source code only supports building Ice for PHP as a dynamic PHP extension;
+the product of the build is a shared library that you must configure PHP to
+load.
+
+Change to the `php` source subdirectory:
+
+```shell
+cd php
+```
+
+Ensure that `php` and `php-config` for the version of PHP you wish to
+build against are first in your PATH.
+
+Run `make` to build the extension.
+
+### Windows
+
+Open a Visual Studio command prompt. For example, with Visual Studio 2015, you
+can open one of:
+
+* VS2015 x86 Native Tools Command Prompt
+* VS2015 x64 Native Tools Command Prompt
+
+Using the first Command Prompt produces `Win32` binaries by default, while
+the second Command Prompt produces `x64` binaries by default.
+
+In the Command Prompt, change to the `php` subdirectory:
+
+```shell
+cd php
+```
+
+Now you're ready to build Ice for PHP:
+
+```shell
+msbuild msbuild\ice.proj
+```
+
+This builds the extension with `Release` binaries for the default platform. The
+extension will be placed in `lib\x64\Release\php_ice.dll` for the `x64` platform
+and `lib\Win32\Release\php_ice.dll` for the `Win32` platform.
+
+The default configuration builds the extension against the thread-safe PHP run
+time. You can build with the non-thread-safe run time using the `NTS-Release` or
+`NTS-Debug` configuration:
+
+```shell
+msbuild msbuild\ice.proj /p:Configuration=NTS-Release
+```
+
+The extension will be placed in `lib\x64\Release\php_ice_nts.dll` directory for
+the `x64` platform and `lib\Win32\Release\php_ice_nts.dll` for the `Win32`
+platform.
+
+The extension is built by default with namespaces enabled. You can build the PHP
+extension with namespaces disabled by setting the MSBuild property
+`PhpUseNamespaces` to `no`:
+
+```shell
+msbuild msbuild\ice.proj /p:PhpUseNamespaces=no
+```
+
+The PHP extension is build by default using PHP 7.1, the extension can be build
+with PHP 7.1, 7.2 or 7.3 by setting MSBuildProperty `BuildWithPhpVersion` to the
+desired version for example you can use the following command to build the
+extension with PHP 7.2:
+
+```shell
+msbuild msbuild\ice.proj /p:BuildWithPhpVersion=7.2
+```
+
+The PHP extension depends on Ice for C++ components from the `cpp` subdirectory,
+and those are built if required. It is also possible to build the PHP extension
+using the Ice for C++ NuGet packages by setting the`ICE_BIN_DIST` msbuild
+property to `cpp`:
+
+```shell
+msbuild msbuild\ice.proj /p:ICE_BIN_DIST=cpp
+```
+
+## Installing the PHP Extension
+
+### Linux or macOS
+
+To install the Ice extension, you must move the extension's shared library into
+PHP's extension directory. This directory is determined by the PHP configuration
+directive `extension_dir`. You can determine the default value for this
+directive by running the command-line version of PHP with the `-i` option:
+
+```shell
+php -i
+```
+
+Review the output for a line like this:
+
+```shell
+extension_dir => /usr/lib/php/modules => /usr/lib/php/modules
+```
+
+Once you've copied the extension to PHP's extension directory, you will need to
+enable the extension in your PHP configuration. Your PHP installation likely
+supports the `/etc/php.d` configuration directory, which you can verify by
+examining the output of `php -i` and looking for the presence of
+`--with-config-file-scan-dir` in the "Configure Command" entry. If present,
+you can create a file in `/etc/php.d` that contains the directive to load the
+Ice extension. For example, create the file `/etc/php.d/ice.ini` containing
+the following line:
+
+```shell
+extension = ice.so
+```
+
+If PHP does not support the `/etc/php.d` directory, determine the path name of
+PHP's configuration file as reported by the `php -i` command:
+
+```shell
+Configuration File (php.ini) Path => /etc/php.ini
+```
+
+Open the configuration file and append the following line:
+
+```shell
+extension = ice.so
+```
+
+You can verify that PHP is loading the Ice extension by running the command
+shown below:
+
+```shell
+php -m
+```
+
+Look for `ice` among the installed modules. Note that your library search path
+(`LD_LIBRARY_PATH` on Linux or `DYLD_LIBRARY_PATH` on macOS) must include the
+directory containing the Ice shared libraries.
+
+Read the PHP Dependencies and PHP Source Files sections below for more
+information about installing the Ice extension.
+
+### Windows
+
+To install the Ice extension, you must move the extension's shared library into
+PHP's extension directory. This directory is determined by the PHP configuration
+directive `extension_dir`. You can determine the default value for this
+directive by running the command-line version of PHP with the `-i` option:
+
+```shell
+php -i
+```
+
+Review the output for a line like this:
+```
+extension_dir => C:\Program Files\iis express\PHP\v7.1\ext\ => C:\Program Files\iis express\PHP\v7.1\ext\
+```
+
+Once you've copied the extension to the appropriate directory, you will need
+to enable the extension in your PHP configuration. First you must discover the
+location of PHP's configuration file (`php.ini`), which is also displayed by
+the `-i` option. Look for the following line:
+
+```shell
+Loaded Configuration File => C:\Program Files\iis express\PHP\v7.1\php.ini
+```
+
+Open `php.ini` and append the following directive:
+
+```shell
+extension=php_ice_nts.dll
+```
+
+Read the PHP Dependencies and PHP Source Files sections below for more
+information about installing the Ice extension.
+
+## PHP Dependencies
+
+PHP needs to locate the libraries for the Ice run-time libraries and its
+third-party dependencies.
+
+* Linux and macOS
+
+```shell
+libIce
+libIceDiscovery
+libIceLocatorDiscovery
+libIceSSL
+libbz2
+```
+
+* Windows
+
+```shell
+bzip2.dll
+ice37.dll
+icediscovery37.dll
+icelocatordiscovery37.dll
+icessl37.dll
+```
+
+In general, these libraries must reside in a directory of the user's PATH.
+For Web servers, the libraries may need to reside in a system directory. For
+example, on Linux you can add the directory containing the Ice run-time
+libraries to `/etc/ld.so.conf` and run `ldconfig`.
+
+For IIS configured to run PHP as FastCGI, the simplest solution is to copy the
+libraries next to the `php-cgi.exe` in `C:\Program Files\iis express\PHP\v7.1`.
+
+You can verify that the Ice extension is installed properly by examining the
+output of the `php -m` command, or by calling the `phpInfo()` function from a
+script. For example, you can create a file in the Web server's document
+directory containing the following PHP script:
+
+```php
+<?php
+phpInfo();
+?>
+```
+
+Then start a browser window and open the URL corresponding to this script. If
+the Ice extension is successfully installed, you will see an `ice` section
+among the configuration information.
+
+## PHP Source Files
+
+In addition to the binary Ice extension module and its library dependencies,
+you will also need to make the Ice for PHP source files available to your
+scripts. These files are located in the `lib` subdirectory and consist of the
+Ice run time definitions (`Ice.php`) along with PHP source
+files generated from the Slice files included in the Ice distribution.
+
+The Ice extension makes no assumptions about the location of these files, so you
+can install them anywhere you like. For example, you can simply include them in
+the same directory as your application scripts. Alternatively, if you prefer to
+install them in a common directory, you may need to modify PHP's `include_path`
+directive so that the PHP interpreter is able to locate these files. For
+example, you could append to `php.ini`:
+
+```ini
+include_path=${include_path}";C\ice\php\lib"
+```
+
+Another option is to modify the include path from within your script prior to
+including any Ice run-time file. Here is an example that assumes Ice is
+installed in `/opt`:
+
+```php
+ini_set('include_path',
+ini_get('include_path') . PATH_SEPARATOR . '/opt/Ice/php');
+require 'Ice.php'; // Load the core Ice run time definitions.
+```
+
+## Running the PHP Tests
+
+The test subdirectory contains PHP implementations of the core Ice test suite.
+Python is required to run the test suite.
+
+The test suites also require that the Ice for C++ tests be built in the `cpp`
+subdirectory of this source distribution. In addition, the scripts require
+that the CLI version of the PHP interpreter be available in your PATH.
+
+After a successful build, you can run the tests as follows:
+
+```shell
+python allTests.py
+```
+
+If you have built the extension using the Ice for C++ NuGet packages, you must
+also set the `ICE_BIN_DIST` environment variable to `cpp` for testing:
+
+```shell
+set ICE_BIN_DIST=cpp
+python allTests.py
+```
+
+If everything worked out, you should see lots of `ok` messages. In case of a
+failure, the tests abort with `failed`.
+
+## Web Server Permissions
+
+The Web server normally runs in a special user account that may not necessarily
+have access to the Ice extension, its dependent libraries and PHP source files,
+and other resources such as Ice configuration and your application scripts. It
+is very important that you review the permissions of these files and verify
+that the Web server has sufficient access.
+
+On Linux, Apache typically runs in the `apache` account, so you will either
+need to change the owner or group of the libraries and other resources, or
+modify their permissions to make them sufficiently accessible.
+
+## SELinux Notes for PHP
+
+SELinux augments the traditional Unix permissions with a number of new features.
+In particular, SELinux can prevent the httpd daemon from opening network
+connections and reading files without the proper SELinux types.
+
+If you suspect that your Ice for PHP application does not work due to SELinux
+restrictions, we recommend that you first try it with SELinux disabled.
+As root, run:
+
+```shell
+setenforce 0
+```
+
+to disable SELinux until the next reboot of your computer.
+
+If you want to run httpd with Ice for PHP and SELinux enabled, there are two
+steps you need to take. First, allow httpd to open network connections:
+
+```shell
+setsebool httpd_can_network_connect=1
+```
+
+Add the `-P` option to make this setting persistent across reboots.
+
+Second, make sure any `.ice` file used by your PHP scripts can be read by httpd.
+The enclosing directory also needs to be accessible. For example:
+
+```shell
+chcon -R -t httpd_sys_content_t /opt/MyApp/slice
+```
+
+[binary distributions]: https://zeroc.com/downloads/ice
+[supported platforms]: https://doc.zeroc.com/ice/3.7/release-notes/supported-platforms-for-ice-3-7-10
+[Ice Builder for Visual Studio]: https://github.com/zeroc-ice/ice-builder-visualstudio
diff --git a/php/README.md b/php/README.md
index 0c2c4261e0a..c7b07ec51c2 100644
--- a/php/README.md
+++ b/php/README.md
@@ -1,339 +1,39 @@
-# Building Ice for PHP
+# Ice for PHP
 
-This page describes how to build and install Ice for PHP from source.
+[Getting started] | [Examples] | [Documentation] | [Building from source]
 
-ZeroC provides [binary distributions][1] for many platforms, including
-Linux and Windows, so building Ice for PHP from source is usually
-unnecessary.
+The [Ice framework] provides everything you need to build networked applications,
+including RPC, pub/sub, server deployment, and more.
 
-* [PHP Build Requirements](#php-build-requirements)
-* [Building the PHP Extension](#building-the-php-extension)
-  * [Linux or macOS](#linux-or-macos)
-  * [Windows](#windows)
-* [Installing the PHP Extension](#installing-the-php-extension)
-  * [Linux or macOS](#linux-or-macos-1)
-  * [Windows](#windows-1)
-* [PHP Dependencies](#php-dependencies)
-* [PHP Source Files](#php-source-files)
-* [Running the PHP Tests](#running-the-php-tests)
-* [Web Server Permissions](#web-server-permissions)
-* [SELinux Notes for PHP](#selinux-notes-for-php)
+Ice for PHP is the PHP implementation of the Ice framework.
 
-## PHP Build Requirements
+## Sample Code
 
-Ice was extensively tested using the operating systems and compiler versions
-listed on [supported platforms][2].
+```slice
+// Slice definitions (Hello.ice)
 
-On Windows, the build requires a recent version of Visual Studio and the
-[Ice Builder for Visual Studio][3].
-
-## Building the PHP Extension
-
-### Linux or macOS
-
-The build of Ice for PHP requires that you first build Ice for C++ in the `cpp`
-subdirectory.
-
-From the top-level source directory, edit `config/Make.rules` to establish
-your build configuration. The comments in the file provide more information.
-
-Our source code only supports building Ice for PHP as a dynamic PHP extension;
-the product of the build is a shared library that you must configure PHP to
-load.
-
-Change to the `php` source subdirectory:
-```
-cd php
-```
-
-Ensure that `php` and `php-config` for the version of PHP you wish to
-build against are first in your PATH.
-
-Run `make` to build the extension.
-
-### Windows
-
-Open a Visual Studio command prompt. For example, with Visual Studio 2015, you
-can open one of:
-
-- VS2015 x86 Native Tools Command Prompt
-- VS2015 x64 Native Tools Command Prompt
-
-Using the first Command Prompt produces `Win32` binaries by default, while
-the second Command Promt produces `x64` binaries by default.
-
-In the Command Prompt, change to the `php` subdirectory:
-```
-cd php
-```
-
-Now you're ready to build Ice for PHP:
-```
-msbuild msbuild\ice.proj
-```
-
-This builds the extension with `Release` binaries for the default platform. The
-extension will be placed in `lib\x64\Release\php_ice.dll` for the `x64` platform
-and `lib\Win32\Release\php_ice.dll` for the `Win32` platform.
-
-The default configuration builds the extension against the thread-safe PHP run
-time. You can build with the non-thread-safe run time using the `NTS-Release` or
-`NTS-Debug` configuration:
-```
-msbuild msbuild\ice.proj /p:Configuration=NTS-Release
-```
-
-The extension will be placed in `lib\x64\Release\php_ice_nts.dll` directory for
-the `x64` platform and `lib\Win32\Release\php_ice_nts.dll` for the `Win32`
-platform.
-
-The extension is built by default with namespaces enabled. You can build the PHP
-extension with namespaces disabled by setting the MSBuild property
-`PhpUseNamespaces` to `no`:
-```
-msbuild msbuild\ice.proj /p:PhpUseNamespaces=no
-```
-
-The PHP extension is build by default using PHP 7.1, the extension can be build
-with PHP 7.1, 7.2 or 7.3 by setting MSBuildProperty `BuildWithPhpVersion` to the
-desired version for example you can use the following command to build the
-extension with PHP 7.2:
-
-```
-msbuild msbuild\ice.proj /p:BuildWithPhpVersion=7.2
-```
-
-The PHP extension depends on Ice for C++ components from the `cpp` subdirectory,
-and those are built if required. It is also possible to build the PHP extension
-using the Ice for C++ NuGet packages by setting the`ICE_BIN_DIST` msbuild
-property to `cpp`:
-```
-msbuild msbuild\ice.proj /p:ICE_BIN_DIST=cpp
-```
-
-## Installing the PHP Extension
-
-### Linux or macOS
-
-To install the Ice extension, you must move the extension's shared library into
-PHP's extension directory. This directory is determined by the PHP configuration
-directive `extension_dir`. You can determine the default value for this
-directive by running the command-line version of PHP with the `-i` option:
-```
-php -i
-```
-
-Review the output for a line like this:
-```
-extension_dir => /usr/lib/php/modules => /usr/lib/php/modules
-```
-
-Once you've copied the extension to PHP's extension directory, you will need to
-enable the extension in your PHP configuration. Your PHP installation likely
-supports the `/etc/php.d` configuration directory, which you can verify by
-examining the output of `php -i` and looking for the presence of
-`--with-config-file-scan-dir` in the "Configure Command" entry. If present,
-you can create a file in `/etc/php.d` that contains the directive to load the
-Ice extension. For example, create the file `/etc/php.d/ice.ini` containing
-the following line:
-```
-extension = ice.so
-```
-
-If PHP does not support the `/etc/php.d` directory, determine the path name of
-PHP's configuration file as reported by the `php -i` command:
-```
-Configuration File (php.ini) Path => /etc/php.ini
-```
-
-Open the configuration file and append the following line:
-```
-extension = ice.so
-```
-
-You can verify that PHP is loading the Ice extension by running the command
-shown below:
-
-```
-php -m
-```
-
-Look for `ice` among the installed modules. Note that your library search path
-(`LD_LIBRARY_PATH` on Linux or `DYLD_LIBRARY_PATH` on macOS) must include the
-directory containing the Ice shared libraries.
-
-Read the PHP Dependencies and PHP Source Files sections below for more
-information about installing the Ice extension.
-
-### Windows
-
-To install the Ice extension, you must move the extension's shared library into
-PHP's extension directory. This directory is determined by the PHP configuration
-directive `extension_dir`. You can determine the default value for this
-directive by running the command-line version of PHP with the `-i` option:
-```
-php -i
-```
-
-Review the output for a line like this:
-```
-extension_dir => C:\Program Files\iis express\PHP\v7.1\ext\ => C:\Program Files\iis express\PHP\v7.1\ext\
-```
-
-Once you've copied the extension to the appropriate directory, you will need
-to enable the extension in your PHP configuration. First you must discover the
-location of PHP's configuration file (`php.ini`), which is also displayed by
-the `-i` option. Look for the following line:
-```
-Loaded Configuration File => C:\Program Files\iis express\PHP\v7.1\php.ini
-```
-
-Open `php.ini` and append the following directive:
-```
-extension=php_ice_nts.dll
-```
-
-Read the PHP Dependencies and PHP Source Files sections below for more
-information about installing the Ice extension.
-
-## PHP Dependencies
-
-PHP needs to locate the libraries for the Ice run-time libraries and its
-third-party dependencies.
-
-* Linux and macOS
-```
-libIce
-libIceDiscovery
-libIceLocatorDiscovery
-libIceSSL
-libbz2
-```
-
-* Windows
-```
-bzip2.dll
-ice37.dll
-icediscovery37.dll
-icelocatordiscovery37.dll
-icessl37.dll
-```
-
-In general, these libraries must reside in a directory of the user's PATH.
-For Web servers, the libraries may need to reside in a system directory. For
-example, on Linux you can add the directory containing the Ice run-time
-libraries to `/etc/ld.so.conf` and run `ldconfig`.
-
-For IIS configured to run PHP as FastCGI, the simplest solution is to copy the
-libraries next to the `php-cgi.exe` in `C:\Program Files\iis express\PHP\v7.1`.
-
-You can verify that the Ice extension is installed properly by examining the
-output of the `php -m` command, or by calling the `phpInfo()` function from a
-script. For example, you can create a file in the Web server's document
-directory containing the following PHP script:
-```
-<?php
-phpInfo();
-?>
-```
-
-Then start a browser window and open the URL corresponding to this script. If
-the Ice extension is successfully installed, you will see an `ice` section
-among the configuration information.
-
-## PHP Source Files
-
-In addition to the binary Ice extension module and its library dependencies,
-you will also need to make the Ice for PHP source files available to your
-scripts. These files are located in the `lib` subdirectory and consist of the
-Ice run time definitions (`Ice.php`) along with PHP source
-files generated from the Slice files included in the Ice distribution.
-
-The Ice extension makes no assumptions about the location of these files, so you
-can install them anywhere you like. For example, you can simply include them in
-the same directory as your application scripts. Alternatively, if you prefer to
-install them in a common directory, you may need to modify PHP's `include_path`
-directive so that the PHP interpreter is able to locate these files. For
-example, you could append to `php.ini`:
-```
-include_path=${include_path}";C\ice\php\lib"
-```
-
-Another option is to modify the include path from within your script prior to
-including any Ice run-time file. Here is an example that assumes Ice is
-installed in `/opt`:
-```
-// PHP
-ini_set('include_path',
-ini_get('include_path') . PATH_SEPARATOR . '/opt/Ice/php');
-require 'Ice.php'; // Load the core Ice run time definitions.
-```
-
-## Running the PHP Tests
-
-The test subdirectory contains PHP implementations of the core Ice test suite.
-Python is required to run the test suite.
-
-The test suites also require that the Ice for C++ tests be built in the `cpp`
-subdirectory of this source distribution. In addition, the scripts require
-that the CLI version of the PHP interpreter be available in your PATH.
-
-After a successful build, you can run the tests as follows:
-```
-python allTests.py
-```
-
-If you have built the extension using the Ice for C++ NuGet packages, you must
-also set the `ICE_BIN_DIST` environment variable to `cpp` for testing:
-```
-set ICE_BIN_DIST=cpp
-python allTests.py
+module Demo
+{
+    interface Hello
+    {
+        void sayHello();
+    }
+}
 ```
 
-If everything worked out, you should see lots of `ok` messages. In case of a
-failure, the tests abort with `failed`.
+```php
+// Client application (Client.php)
+require_once 'Ice.php';
+require_once 'Hello.php';
 
-## Web Server Permissions
-
-The Web server normally runs in a special user account that may not necessarily
-have access to the Ice extension, its dependent libraries and PHP source files,
-and other resources such as Ice configuration and your application scripts. It
-is very important that you review the permissions of these files and verify
-that the Web server has sufficient access.
-
-On Linux, Apache typically runs in the `apache` account, so you will either
-need to change the owner or group of the libraries and other resources, or
-modify their permissions to make them sufficiently accessible.
-
-## SELinux Notes for PHP
-
-SELinux augments the traditional Unix permissions with a number of new features.
-In particular, SELinux can prevent the httpd daemon from opening network
-connections and reading files without the proper SELinux types.
-
-If you suspect that your Ice for PHP application does not work due to SELinux
-restrictions, we recommend that you first try it with SELinux disabled.
-As root, run:
-```
-# setenforce 0
-```
-
-to disable SELinux until the next reboot of your computer.
-
-If you want to run httpd with Ice for PHP and SELinux enabled, there are two
-steps you need to take. First, allow httpd to open network connections:
-```
-# setsebool httpd_can_network_connect=1
-```
-
-Add the `-P` option to make this setting persistent across reboots.
-
-Second, make sure any `.ice` file used by your PHP scripts can be read by httpd.
-The enclosing directory also needs to be accessible. For example:
-```
-# chcon -R -t httpd_sys_content_t /opt/MyApp/slice
+$communicator = Ice\initialize();
+$hello = Demo\HelloPrxHelper::uncheckedCast(
+    $communicator->stringToProxy("hello:default -h localhost -p 10000"));
+$hello->sayHello();
 ```
 
-[1]: https://zeroc.com/downloads/ice
-[2]: https://doc.zeroc.com/ice/3.7/release-notes/supported-platforms-for-ice-3-7-10
-[3]: https://github.com/zeroc-ice/ice-builder-visualstudio
+[Getting started]: https://doc.zeroc.com/ice/3.7/hello-world-application/writing-an-ice-application-with-php
+[Examples]: https://github.com/zeroc-ice/ice-demos/tree/3.7/php
+[Documentation]: https://doc.zeroc.com/ice/3.7
+[Building from source]: https://github.com/zeroc-ice/ice/blob/3.7/php/BUILDING.md
+[Ice framework]: https://github.com/zeroc-ice/ice
diff --git a/python/BUILDING.md b/python/BUILDING.md
new file mode 100644
index 00000000000..7005362ef40
--- /dev/null
+++ b/python/BUILDING.md
@@ -0,0 +1,165 @@
+# Ice for Python Build Instructions
+
+This document describes how to build and install Ice for Python from source.
+You can also download and install a [binary distribution].
+
+* [Building with Pip](#building-with-pip)
+* [Building with Visual Studio 2015 and MSBuild (Python 3\.11 for Windows)](#building-with-visual-studio-2015-and-msbuild-python-311-for-windows)
+* [Building on Linux or macOS](#building-on-linux-or-macos)
+* [Configuring your Environment for Python](#configuring-your-environment-for-python)
+* [Running the Python Tests](#running-the-python-tests)
+
+## Building with Pip
+
+You can build the Ice for Python extension from source using `pip`:
+
+```shell
+pip install <URL of Ice source distribution for Python>
+```
+
+## Building with Visual Studio 2015 and MSBuild (Python 3.11 for Windows)
+
+You can build an Ice for Python extension that links with the Ice C++ DLLs using Visual Studio and MSBuild.
+
+First, open a Visual Studio 2015 command prompt:
+
+* VS2015 x86 Native Tools Command Prompt
+
+or
+
+* VS2015 x64 Native Tools Command Prompt
+
+Using the first Command Prompt produces `Win32` binaries by default, while
+the second Command Prompt produces `x64` binaries by default.
+
+In the Command Prompt, change to the `python` subdirectory:
+
+```shell
+cd python
+```
+
+You must build Ice for C++ from the `cpp` subdirectory. If you have not done so,
+refer to the [C++ build instructions](../cpp/BUILDING.md).
+
+Then build the extension:
+
+```shell
+msbuild msbuild\ice.proj
+```
+
+This builds the extension with `Release` binaries for the default platform. The
+extension will be placed in `python\x64\Release\IcePy.pyd` for the `x64`
+platform and `python\Win32\Release\IcePy.pyd` for the `Win32` platform.
+
+If you want to build a debug version of the extension, set the MSBuild
+`Configuration` property to `Debug`:
+
+```shell
+msbuild msbuild\ice.proj /p:Configuration=Debug
+```
+
+The debug version of the extension will be placed in
+`python\x64\Debug\IcePy_d.pyd` for the `x64` platform and
+`python\Win32\Debug\IcePy_d.pyd` for the `Win32` platform.
+
+For Debug builds, a debug version of the Python interpreter must be installed
+as well.
+
+If you want to build the extension for a different platform than the Command
+Prompt's default platform, you need to set the MSBuild property `Platform`. The
+supported values for this property are `Win32` and `x64`.
+
+The following command builds the `x64` platform binaries with the `Release`
+configuration:
+
+```shell
+msbuild msbuild\ice.proj /p:Configuration=Release /p:Platform=x64
+```
+
+This command builds the `Win32` platform binaries with the `Release`
+configuration:
+
+```shell
+msbuild msbuild\ice.proj /p:Configuration=Release /p:Platform=Win32
+```
+
+When using the MSBuild Platform property, the build platform doesn't depend
+on the command prompt's default platform.
+
+The build will use the default location for Python defined in
+`python\msbuild\ice.props`. You can override it by setting the `PythonHome`
+MSBuild property. For example, the following command will use the Python
+installation from `C:\Python310-AMD64` instead of the default location:
+
+```shell
+msbuild msbuild\ice.proj /p:Configuration=Release /p:Platform=x64 /p:PythonHome=C:\Python310-AMD64
+```
+
+## Building on Linux or macOS
+
+Ice for Python supports Python versions 2.7 and 3.11. Note however that
+your Python installation must have been built with a C++ compiler that is
+compatible with the compiler used to build Ice for C++.
+
+The build of Ice for Python requires to first build Ice for C++ in the `cpp`
+subdirectory.
+
+From the top-level source directory, edit `config/Make.rules` to establish your
+build configuration. The comments in the file provide more information.
+
+Change to the Ice for Python source subdirectory:
+
+```shell
+cd python
+```
+
+Execute `python -V` to verify that the correct Python interpreter is in your
+executable search path.
+
+Run `make` to build the extension.
+
+Upon successful completion, run `make install`. You may need additional user
+permissions to install in the directory specified by `config/Make.rules`.
+
+## Configuring your Environment for Python
+
+Modify your environment to allow Python to find the Ice extension for Python.
+The python interpreter must be able to locate the IcePy extension as well as
+the Python source files in the `python` subdirectory. This is normally
+accomplished by setting the `PYTHONPATH` environment variable to contain the
+necessary subdirectory.
+
+For example on Windows, with Ice for Python installed in `C:\Ice`:
+
+```shell
+set PYTHONPATH=C:\Ice\python;C:\Ice\python\Win32\Release
+```
+
+For example on Linux or macOS, with Ice for Python installed in `/opt/Ice`:
+
+```shell
+export PYTHONPATH=/opt/Ice/python
+```
+
+## Running the Python Tests
+
+After a successful build, you can run the tests as follows:
+
+Windows:
+
+```shell
+python allTests.py --config=Release --platform=Win32
+```
+
+(adjust `--config` and `--platform` to match your build)
+
+Linux/macOS:
+
+```shell
+python allTests.py
+```
+
+If everything worked out, you should see lots of `ok` messages. In case of a
+failure, the tests abort with `failed`.
+
+[binary distribution]: https://zeroc.com/downloads/ice
diff --git a/python/README.md b/python/README.md
index 6643b8a2b3a..397d087eb78 100644
--- a/python/README.md
+++ b/python/README.md
@@ -1,145 +1,72 @@
-# Building Ice for Python
+# Ice for Python
 
-This document describes how to build and install Ice for Python from source.
-You can also download and install a [binary distribution][1].
+[Getting started] | [Examples] | [Documentation] | [Building from source]
 
-* [Building with Pip](#building-with-pip)
-* [Building with Visual Studio 2015 and MSBuild (Python 3\.10 for Windows)](#building-with-visual-studio-2015-and-msbuild-python-310-for-windows)
-* [Building on Linux or macOS](#building-on-linux-or-macos)
-* [Configuring your Environment for Python](#configuring-your-environment-for-python)
-* [Running the Python Tests](#running-the-python-tests)
+The [Ice framework] provides everything you need to build networked applications,
+including RPC, pub/sub, server deployment, and more.
 
-## Building with Pip
+Ice for Python is the Python implementation of the Ice framework.
 
-You can build the Ice for Python extension from source using `pip`:
-```
-pip install <URL of Ice source distribution for Python>
-```
-
-## Building with Visual Studio 2015 and MSBuild (Python 3.11 for Windows)
-
-You can build an Ice for Python extension that links with the Ice C++ DLLs using Visual Studio and MSBuild.
-
-First, open a Visual Studio 2015 command prompt:
-
-- VS2015 x86 Native Tools Command Prompt
-or
-- VS2015 x64 Native Tools Command Prompt
-
-Using the first Command Prompt produces `Win32` binaries by default, while
-the second Command Prompt produces `x64` binaries by default.
-
-In the Command Prompt, change to the `python` subdirectory:
-```
-cd python
-```
-You must build Ice for C++ from the `cpp` subdirectory. If you have not done so,
-refer to the [C++ build instructions](../cpp/BuildInstructionsWindows.md).
+## Sample Code
 
-Then build the extension:
-```
-msbuild msbuild\ice.proj
-```
-This builds the extension with `Release` binaries for the default platform. The
-extension will be placed in `python\x64\Release\IcePy.pyd` for the `x64`
-platform and `python\Win32\Release\IcePy.pyd` for the `Win32` platform.
+```slice
+// Slice definitions (Hello.ice)
 
-If you want to build a debug version of the extension, set the MSBuild
-`Configuration` property to `Debug`:
-```
-msbuild msbuild\ice.proj /p:Configuration=Debug
+module Demo
+{
+    interface Hello
+    {
+        void sayHello();
+    }
+}
 ```
-The debug version of the extension will be placed in
-`python\x64\Debug\IcePy_d.pyd` for the `x64` platform and
-`python\Win32\Debug\IcePy_d.pyd` for the `Win32` platform.
 
-For Debug builds, a debug version of the Python interpreter must be installed
-as well.
+```python
+// Client application (client.py)
+import sys
+import Ice
 
-If you want to build the extension for a different platform than the Command
-Prompt's default platform, you need to set the MSBuild property `Platform`. The
-supported values for this property are `Win32` and `x64`.
+Ice.loadSlice('Hello.ice')
+import Demo
 
-The following command builds the `x64` platform binaries with the `Release`
-configuration:
-```
-msbuild msbuild\ice.proj /p:Configuration=Release /p:Platform=x64
-```
-This command builds the `Win32` platform binaries with the `Release`
-configuration:
+# Ice.initialize returns an initialized Ice communicator, the communicator is destroyed
+# once it goes out of scope.
+with Ice.initialize(sys.argv) as communicator:
+    hello = Demo.HelloPrx.checkedCast(
+        communicator.stringToProxy("hello:default -h localhost -p 10000"))
+    hello.sayHello()
 ```
-msbuild msbuild\ice.proj /p:Configuration=Release /p:Platform=Win32
-```
-When using the MSBuild Platform property, the build platform doesn't depend
-on the command prompt's default platform.
 
-The build will use the default location for Python defined in
-`python\msbuild\ice.props`. You can override it by setting the `PythonHome`
-MSBuild property. For example, the following command will use the Python
-installation from `C:\Python310-AMD64` instead of the default location:
-```
-msbuild msbuild\ice.proj /p:Configuration=Release /p:Platform=x64 /p:PythonHome=C:\Python310-AMD64
-```
+```python
+// Server application (server.py)
 
-## Building on Linux or macOS
+import signal
+import sys
+import Ice
 
-Ice for Python supports Python versions 2.7 and 3.11. Note however that
-your Python installation must have been built with a C++ compiler that is
-compatible with the compiler used to build Ice for C++.
+Ice.loadSlice('Hello.ice')
+import Demo
 
-The build of Ice for Python requires to first build Ice for C++ in the `cpp`
-subdirectory.
+class Printer(Demo.Hello):
+    def sayHello(self, current):
+        print("Hello World!")
 
-From the top-level source directory, edit `config/Make.rules` to establish your
-build configuration. The comments in the file provide more information.
+# Ice.initialize returns an initialized Ice communicator, the communicator is destroyed
+# once it goes out of scope.
+with Ice.initialize(sys.argv) as communicator:
 
-Change to the Ice for Python source subdirectory:
+    # Install a signal handler to shutdown the communicator on Ctrl-C
+    signal.signal(signal.SIGINT, lambda signum, frame: communicator.shutdown())
+    if hasattr(signal, 'SIGBREAK'):
+        signal.signal(signal.SIGBREAK, lambda signum, frame: communicator.shutdown())
+    adapter = communicator.createObjectAdapterWithEndpoints("Hello", "default -h localhost -p 10000")
+    adapter.add(Printer(), Ice.stringToIdentity("hello"))
+    adapter.activate()
+    communicator.waitForShutdown()
 ```
-cd python
-```
-
-Execute `python -V` to verify that the correct Python interpreter is in your
-executable search path.
-
-Run `make` to build the extension.
-
-Upon successful completion, run `make install`. You may need additional user
-permissions to install in the directory specified by `config/Make.rules`.
-
-## Configuring your Environment for Python
-
-Modify your environment to allow Python to find the Ice extension for Python.
-The python interpreter must be able to locate the IcePy extension as well as
-the Python source files in the `python` subdirectory. This is normally
-accomplished by setting the `PYTHONPATH` environment variable to contain the
-necessary subdirectory.
-
-For example on Windows, with Ice for Python installed in `C:\Ice`:
-```
-set PYTHONPATH=C:\Ice\python;C:\Ice\python\Win32\Release
-```
-
-For example on Linux or macOS, with Ice for Python installed in `/opt/Ice`:
-```
-export PYTHONPATH=/opt/Ice/python
-```
-
-## Running the Python Tests
-
-After a successful build, you can run the tests as follows:
-
-Windows:
-```
-python allTests.py --config=Release --platform=Win32
-```
-(adjust `--config` and `--platform` to match your build)
-
-Linux/macOS:
-```
-python allTests.py
-```
-
-If everything worked out, you should see lots of `ok` messages. In case of a
-failure, the tests abort with `failed`.
 
-[1]: https://zeroc.com/downloads/ice
+[Getting started]: https://doc.zeroc.com/ice/3.7/hello-world-application/writing-an-ice-application-with-python
+[Examples]: https://github.com/zeroc-ice/ice-demos/tree/3.7/python
+[Documentation]: https://doc.zeroc.com/ice/3.7
+[Building from source]: https://github.com/zeroc-ice/ice/blob/3.7/python/BUILDING.md
+[Ice framework]: https://github.com/zeroc-ice/ice
diff --git a/ruby/BUILDING.md b/ruby/BUILDING.md
new file mode 100644
index 00000000000..df49c3210a5
--- /dev/null
+++ b/ruby/BUILDING.md
@@ -0,0 +1,172 @@
+# Ice for Ruby Build Instructions
+
+This file describes how to build and install Ice for Ruby from source code on
+Linux and macOS. If you prefer, you can also download [binary distributions][1]
+for the supported platforms.
+
+* [Ruby Build Requirements](#ruby-build-requirements)
+  * [Operating Systems and Compilers](#operating-systems-and-compilers)
+  * [Ruby Versions](#ruby-versions)
+* [Building the Ruby Extension](#building-the-ruby-extension)
+* [Installing Ice for Ruby](#installing-ice-for-ruby)
+* [Configuring your Environment for Ruby](#configuring-your-environment-for-ruby)
+* [Running the Ruby Tests](#running-the-ruby-tests)
+* [SELinux Notes for Ruby](#selinux-notes-for-ruby)
+
+## Ruby Build Requirements
+
+### Operating Systems and Compilers
+
+Ice for Ruby is expected to build and run properly on macOS and on any recent
+Linux distribution for x86 and x86_64, and was extensively tested using the
+operating systems and Ruby versions listed for our [supported platforms][2].
+
+### Ruby Versions
+
+Ice for Ruby supports Ruby versions 2.0 or later. You can use a source or
+binary installation of Ruby.
+
+If you use an RPM installation, the following packages are required:
+
+* ruby
+* ruby-devel
+* ruby-libs (RHEL)
+
+## Building the Ruby Extension
+
+The instructions for compiling the Ice extension assume that you have already
+installed Ruby.
+
+The build of Ice for Ruby requires that you first build Ice for C++ in the
+`cpp` subdirectory.
+
+From the top-level source directory, edit `config/Make.rules` to establish your
+build configuration. The comments in the file provide more information.
+
+Change to the Ice for Ruby source subdirectory:
+
+```shell
+cd ruby
+```
+
+Run `make` to build the extension.
+
+## Installing Ice for Ruby
+
+You can perform an automated installation with the following command:
+
+```shell
+make install
+```
+
+This process uses the `prefix` variable in `../config/Make.rules` as the
+installation's root directory. The subdirectory `<prefix>/ruby` is created as a
+copy of the local `ruby` directory and contains the Ice for Ruby extension
+library as well as Ruby source code. Using this installation method requires
+that you modify your environment as described in *Configuring your Environment
+for Ruby* below.
+
+Another option is to copy the contents of the local `ruby` directory to your
+Ruby installation's `site_ruby` directory. For example, if you installed Ruby
+via RPM, you can use the steps below:
+
+```shell
+cd <Ice source directory>/ruby/ruby
+sudo tar cf - * | (cd /usr/lib/ruby/site_ruby/1.8/i386-linux; tar xvf -)
+```
+
+On x86_64 systems, change the last command to:
+
+```shell
+sudo tar cf - * | (cd /usr/lib64/ruby/site_ruby/1.8/x86_64-linux; tar xvf -)
+```
+
+There is no need to modify your environment if you use this approach.
+
+## Configuring your Environment for Ruby
+
+The Ruby interpreter must be able to locate the Ice extension. If you used the
+automated installation described above, you need to define the `RUBYLIB`
+environment variable as follows:
+
+```shell
+export RUBYLIB=/opt/Ice/ruby:$RUBYLIB
+```
+
+This example assumes that your Ice for Ruby installation is located in the
+`/opt/Ice` directory.
+
+You must also modify `LD_LIBRARY_PATH` or `DYLD_LIBRARY_PATH` to include the
+directory `/opt/Ice/lib`:
+
+```shell
+export LD_LIBRARY_PATH=/opt/Ice/lib:$LD_LIBRARY_PATH       (Linux)
+export DYLD_LIBRARY_PATH=/opt/Ice/lib:$DYLD_LIBRARY_PATH   (macOS)
+```
+
+To verify that Ruby can load the Ice extension successfully, open a command
+window and start the interpreter using `irb`.
+
+At the prompt, enter:
+
+```shell
+require "Ice"
+```
+
+If the interpreter responds with the value true, the Ice extension was loaded
+successfully. Enter `exit` to quit the interpreter.
+
+## Running the Ruby Tests
+
+The `test` subdirectory contains Ruby implementations of the core Ice test
+suite. Python is required to run the test suite.
+
+The test suites require that the Ice for C++ tests be built in the `cpp`
+subdirectory of this source distribution.
+
+Open a command window and change to the top-level directory. At the command
+prompt, execute:
+
+```shell
+python allTests.py
+```
+
+You can also run tests individually by changing to the test directory and
+running this command:
+
+```shell
+python run.py
+```
+
+If everything worked out, you should see lots of `ok` messages. In case of a
+failure, the tests abort with `failed`.
+
+## SELinux Notes for Ruby
+
+If SELinux is enabled on your RHEL system, you may encounter this error message
+when Ruby attempts to load the Ice extension:
+
+```shell
+cannot restore segment prot after reloc: Permission denied
+```
+
+There are two ways to solve this problem:
+
+* Change the default security context for the Ice extension using the following
+  command:
+
+```shell
+chcon -t texrel_shlib_t /opt/Ice/ruby/IceRuby.so
+```
+
+Replace `/opt/Ice` with your installation directory.
+
+* Disable SELinux completely by adding the following line to your
+  `/etc/sysconfig/selinux` file:
+
+```shell
+SELINUX=disabled
+```
+
+[1]: https://zeroc.com/downloads/ice
+[2]: https://doc.zeroc.com/ice/3.7/release-notes/supported-platforms-for-ice-3-7-10
diff --git a/ruby/README.md b/ruby/README.md
index bd6d8f678b2..cc7a7162cbe 100644
--- a/ruby/README.md
+++ b/ruby/README.md
@@ -1,162 +1,41 @@
-# Building Ice for Ruby on Linux and macOS
+# Ice for Ruby
 
-This file describes how to build and install Ice for Ruby from source code on
-Linux and macOS. If you prefer, you can also download [binary distributions][1]
-for the supported platforms.
+[Getting started] | [Examples] | [Documentation] | [Building from source]
 
-* [Ruby Build Requirements](#ruby-build-requirements)
-  * [Operating Systems and Compilers](#operating-systems-and-compilers)
-  * [Ruby Versions](#ruby-versions)
-* [Building the Ruby Extension](#building-the-ruby-extension)
-* [Installing Ice for Ruby](#installing-ice-for-ruby)
-* [Configuring your Environment for Ruby](#configuring-your-environment-for-ruby)
-* [Running the Ruby Tests](#running-the-ruby-tests)
-* [SELinux Notes for Ruby](#selinux-notes-for-ruby)
+The [Ice framework] provides everything you need to build networked applications,
+including RPC, pub/sub, server deployment, and more.
 
-## Ruby Build Requirements
+Ice for Ruby is the Ruby implementation of the Ice framework.
 
-### Operating Systems and Compilers
+## Sample Code
 
-Ice for Ruby is expected to build and run properly on macOS and on any recent
-Linux distribution for x86 and x86_64, and was extensively tested using the
-operating systems and Ruby versions listed for our [supported platforms][2].
+```slice
+// Slice definitions (Hello.ice)
 
-### Ruby Versions
-
-Ice for Ruby supports Ruby versions 2.0 or later. You can use a source or
-binary installation of Ruby.
-
-If you use an RPM installation, the following packages are required:
-```
-ruby
-ruby-devel
-ruby-libs (RHEL)
-```
-
-## Building the Ruby Extension
-
-The instructions for compiling the Ice extension assume that you have already
-installed Ruby.
-
-The build of Ice for Ruby requires that you first build Ice for C++ in the
-`cpp` subdirectory.
-
-From the top-level source directory, edit `config/Make.rules` to establish your
-build configuration. The comments in the file provide more information.
-
-Change to the Ice for Ruby source subdirectory:
-```
-cd ruby
-```
-
-Run `make` to build the extension.
-
-## Installing Ice for Ruby
-
-You can perform an automated installation with the following command:
+module Demo
+{
+    interface Hello
+    {
+        void sayHello();
+    }
+}
 ```
-make install
-```
-
-This process uses the `prefix` variable in `../config/Make.rules` as the
-installation's root directory. The subdirectory `<prefix>/ruby` is created as a
-copy of the local `ruby` directory and contains the Ice for Ruby extension
-library as well as Ruby source code. Using this installation method requires
-that you modify your environment as described in *Configuring your Environment
-for Ruby* below.
-
-Another option is to copy the contents of the local `ruby` directory to your
-Ruby installation's `site_ruby` directory. For example, if you installed Ruby
-via RPM, you can use the steps below:
-```
-cd <Ice source directory>/ruby/ruby
-sudo tar cf - * | (cd /usr/lib/ruby/site_ruby/1.8/i386-linux; tar xvf -)
-```
-
-On x86_64 systems, change the last command to:
-```
-sudo tar cf - * | (cd /usr/lib64/ruby/site_ruby/1.8/x86_64-linux; tar xvf -)
-```
-
-There is no need to modify your environment if you use this approach.
 
-## Configuring your Environment for Ruby
+```ruby
+// Client application (client.rb)
+require 'Ice'
 
-The Ruby interpreter must be able to locate the Ice extension. If you used the
-automated installation described above, you need to define the `RUBYLIB`
-environment variable as follows:
-```
-export RUBYLIB=/opt/Ice/ruby:$RUBYLIB
-```
+Ice::loadSlice('Hello.ice')
 
-This example assumes that your Ice for Ruby installation is located in the
-`/opt/Ice` directory.
-
-You must also modify `LD_LIBRARY_PATH` or `DYLD_LIBRARY_PATH` to include the
-directory `/opt/Ice/lib`:
-```
-export LD_LIBRARY_PATH=/opt/Ice/lib:$LD_LIBRARY_PATH       (Linux)
-export DYLD_LIBRARY_PATH=/opt/Ice/lib:$DYLD_LIBRARY_PATH   (macOS)
-```
-
-To verify that Ruby can load the Ice extension successfully, open a command
-window and start the interpreter using `irb`.
-
-At the prompt, enter:
-```
-require "Ice"
-```
-
-If the interpreter responds with the value true, the Ice extension was loaded
-successfully. Enter `exit` to quit the interpreter.
-
-## Running the Ruby Tests
-
-The `test` subdirectory contains Ruby implementations of the core Ice test
-suite. Python is required to run the test suite.
-
-The test suites require that the Ice for C++ tests be built in the `cpp`
-subdirectory of this source distribution.
-
-Open a command window and change to the top-level directory. At the command
-prompt, execute:
-```
-python allTests.py
-```
-
-You can also run tests individually by changing to the test directory and
-running this command:
-```
-python run.py
-```
-
-If everything worked out, you should see lots of `ok` messages. In case of a
-failure, the tests abort with `failed`.
-
-## SELinux Notes for Ruby
-
-If SELinux is enabled on your RHEL system, you may encounter this error message
-when Ruby attempts to load the Ice extension:
-```
-cannot restore segment prot after reloc: Permission denied
-```
-There are two ways to solve this problem:
-
-- Change the default security context for the Ice extension using the following
-command:
-
-```
-chcon -t texrel_shlib_t /opt/Ice/ruby/IceRuby.so
-```
-
-Replace `/opt/Ice` with your installation directory.
-
-- Disable SELinux completely by adding the following line to your
-`/etc/sysconfig/selinux` file:
-
-```
-SELINUX=disabled
+Ice::initialize(ARGV) do |communicator|
+    hello = Demo::HelloPrx::checkedCast(
+        communicator.stringToProxy("hello:default -h localhost -p 10000"))
+    hello.sayHello()
+end
 ```
 
-[1]: https://zeroc.com/downloads/ice
-[2]: https://doc.zeroc.com/ice/3.7/release-notes/supported-platforms-for-ice-3-7-10
+[Getting started]: https://doc.zeroc.com/ice/3.7/hello-world-application/writing-an-ice-application-with-ruby
+[Examples]: https://github.com/zeroc-ice/ice-demos/tree/3.7/ruby
+[Documentation]: https://doc.zeroc.com/ice/3.7
+[Building from source]: https://github.com/zeroc-ice/ice/blob/3.7/ruby/BUILDING.md
+[Ice framework]: https://github.com/zeroc-ice/ice
diff --git a/swift/BUILDING.md b/swift/BUILDING.md
new file mode 100644
index 00000000000..75f3beea222
--- /dev/null
+++ b/swift/BUILDING.md
@@ -0,0 +1,105 @@
+# Ice for Swift Build Instructions
+
+This file describes how to build Ice for Swift from source and how to test the
+resulting build.
+
+- [Swift Build Requirements](#swift-build-requirements)
+  - [Operating Systems](#operating-systems)
+  - [Slice to Swift Compiler](#slice-to-swift-compiler)
+  - [Swift Version](#swift-version)
+  - [Carthage](#carthage)
+- [Building Ice for Swift](#building-ice-for-swift)
+- [Running the Swift Test Suite](#running-the-swift-test-suite)
+  - [macOS](#macos)
+  - [iOS](#ios)
+
+## Swift Build Requirements
+
+### Operating Systems
+
+Ice for Swift builds and runs on macOS and is supported on the platforms listed
+on the [supported platforms] page.
+
+### Slice to Swift Compiler
+
+You need the Slice to Swift compiler to build Ice for Swift and also to use Ice
+for Swift. The Slice to Swift compiler (`slice2swift`) is a command-line tool
+written in C++. You can build the Slice to Swift compiler from source, or
+alternatively you can install an Ice [binary distribution] that includes this
+compiler.
+
+### Swift Version
+
+Ice for Swift requires Swift 5 or later.
+
+### Carthage
+
+Carthage must be installed to build Ice for Swift. You can install Carthage
+using Homebrew:
+
+```shell
+brew install carthage
+```
+
+## Building Ice for Swift
+
+First download and build the PromiseKit framework by running:
+
+```shell
+carthage bootstrap --use-xcframeworks
+```
+
+from the root directory of your ice repository.
+
+Then open `ice.xcodeproj` with Xcode and build the `Ice macOS` or `Ice iOS`
+targets.
+
+The test programs for macOS and iOS can be built using `TestDriver macOS` and
+`TestDriver iOS` respectively.
+
+Building the `TestDriver iOS` application to deploy to an iOS device requires
+signing the application with a developer certificate. You need to update the Xcode projects
+to use your Apple development certificates by setting `DEVELOPMENT_TEAM` environment
+variable to the Id of your development team and regenerate the projects with `rake`.
+
+```shell
+export DEVELOPMENT_TEAM=U4TBVKNQ7F
+rake
+```
+
+## Running the Swift Test Suite
+
+Python is required to run the test suite.
+
+### macOS
+
+After a successful build, you can run the tests as follows:
+
+```shell
+python3 allTests.py --config Debug
+```
+
+If everything worked out, you should see lots of `ok` messages. In case of a
+failure, the tests abort with `failed`.
+
+### iOS
+
+Start the `TestDriver iOS` application on your iOS device or simulator, from
+Xcode.
+
+Then on your mac, run:
+
+```shell
+python3 allTests.py --config Debug --platform iphoneos
+```
+
+or
+
+```shell
+python3 allTests.py --config Debug --platform iphonesimulator
+```
+
+depending on your target.
+
+[binary distribution]: https://zeroc.com/downloads/ice
+[supported platforms]: https://doc.zeroc.com/ice/3.7/release-notes/supported-platforms-for-ice-3-7-10
diff --git a/swift/README.md b/swift/README.md
index fdb8b4ce7ab..478647ecd8c 100644
--- a/swift/README.md
+++ b/swift/README.md
@@ -1,98 +1,80 @@
-# Building Ice for Swift
-This file describes how to build Ice for Swift from source and how to test the
-resulting build.
+# Ice For Swift
 
-- [Building Ice for Swift](#building-ice-for-swift)
-  - [Swift Build Requirements](#swift-build-requirements)
-    - [Operating Systems](#operating-systems)
-    - [Slice to Swift Compiler](#slice-to-swift-compiler)
-    - [Swift Version](#swift-version)
-    - [Carthage](#carthage)
-  - [Building Ice for Swift](#building-ice-for-swift-1)
-  - [Running the Swift Test Suite](#running-the-swift-test-suite)
-    - [macOS](#macos)
-    - [iOS](#ios)
+[Getting started] | [Examples] | [NuGet package] | [Documentation] | [Building from source]
 
-## Swift Build Requirements
+The [Ice framework] provides everything you need to build networked applications, including RPC, pub/sub, server deployment, and more.
 
-### Operating Systems
+Ice for Swift is the swift implementation of the Ice framework.
 
-Ice for Swift builds and runs on macOS and is supported on the platforms listed
-on the [supported platforms][2] page.
+## Sample Code
 
-### Slice to Swift Compiler
+```slice
+// Slice definitions (Hello.ice)
 
-You need the Slice to Swift compiler to build Ice for Swift and also to use Ice
-for Swift. The Slice to Swift compiler (`slice2swift`) is a command-line tool
-written in C++. You can build the Slice to Swift compiler from source, or
-alternatively you can install an Ice [binary distribution][1] that includes this
-compiler.
-
-### Swift Version
-
-Ice for Swift requires Swift 5 or later.
-
-### Carthage
-
-Carthage must be installed to build Ice for Swift. You can install Carthage
-using Homebrew:
-```
-brew install carthage
-```
-
-## Building Ice for Swift
-
-First download and build the PromiseKit framework by running:
-```
-carthage bootstrap --use-xcframeworks
-```
-from the root directory of your ice repository.
-
-Then open `ice.xcodeproj` with Xcode and build the `Ice macOS` or `Ice iOS`
-targets.
-
-The test programs for macOS and iOS can be built using `TestDriver macOS` and
-`TestDriver iOS` respectively.
-
-Building the `TestDriver iOS` application to deploy to an iOS device requires
-signing the application with a developer certificate. You need to update the Xcode projects
-to use your Apple development certificates by setting `DEVELOPMENT_TEAM` environment
-variable to the Id of your development team and regenerate the projects with `rake`.
-
-```
-export DEVELOPMENT_TEAM=U4TBVKNQ7F
-rake
+module Demo
+{
+    interface Hello
+    {
+        void sayHello();
+    }
+}
 ```
 
-## Running the Swift Test Suite
-
-Python is required to run the test suite.
-
-### macOS
-
-After a successful build, you can run the tests as follows:
-
-```
-python allTests.py --config Debug
+```swift
+// Client application
+import Foundation
+import Ice
+
+do {
+    let communicator = try Ice.initialize(CommandLine.arguments)
+    defer {
+        communicator.destroy()
+    }
+
+    let hello = try uncheckedCast(
+        prx: communicator.stringToProxy("hello:default -h localhost -p 10000")!,
+        type: HelloPrx.self)
+    try hello.sayHello()
+} catch {
+    print("Error: \(error)\n")
+    exit(1)
+}
 ```
 
-If everything worked out, you should see lots of `ok` messages. In case of a
-failure, the tests abort with `failed`.
-
-### iOS
-
-Start the `TestDriver iOS` application on your iOS device or simulator, from
-Xcode.
-
-Then on your mac, run:
-```
-python allTests.py --config Debug --platform iphoneos
-```
-or
-```
-python allTests.py --config Debug --platform iphonesimulator
+```swift
+// Server application
+import Foundation
+import Ice
+
+// Automatically flush stdout
+setbuf(__stdoutp, nil)
+
+struct Printer: Hello {
+    func sayHello(current _: Ice.Current) throws {
+        print("Hello World!")
+    }
+}
+
+do {
+    let communicator = try Ice.initialize(CommandLine.arguments)
+    defer {
+        communicator.destroy()
+    }
+
+    let adapter = try communicator.createObjectAdapterWithEndpoints(
+        name: "Hello",
+        endpoints: "default -h localhost -p 10000")
+    try adapter.add(servant: HelloDisp(Printer()), id: Ice.stringToIdentity("hello"))
+    try adapter.activate()
+    communicator.waitForShutdown()
+} catch {
+    print("Error: \(error)\n")
+    exit(1)
+}
 ```
-depending on your target.
 
-[1]: https://zeroc.com/downloads/ice
-[2]: https://doc.zeroc.com/ice/3.7/release-notes/supported-platforms-for-ice-3-7-10
+[Getting started]: https://doc.zeroc.com/ice/3.7/hello-world-application/writing-an-ice-application-with-swift
+[Examples]: https://github.com/zeroc-ice/ice-demos/tree/3.7/swift
+[Documentation]: https://doc.zeroc.com/ice/3.7
+[Building from source]: https://github.com/zeroc-ice/ice/blob/3.7/swift/BUILDING.md
+[Ice framework]: https://github.com/zeroc-ice/ice
\ No newline at end of file