diff --git a/README.md b/README.md
index 5accc50a..99f82295 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,6 @@
# eSpeak NG Text-to-Speech
+- [Features](#features)
- [Windows](#windows)
- [Binaries](#binaries)
- [Building](#building)
@@ -21,11 +22,10 @@
- [Installing](#installing-1)
- [Documentation](#documentation)
- [eSpeak Compatibility](#espeak-compatibility)
-- [Historical Versions](#historical-versions)
+- [History](#history)
- [Feedback](#feedback)
- [License Information](#license-information)
-
----------
The eSpeak NG is a compact open source software text-to-speech synthesizer for
@@ -80,322 +80,6 @@ The following platforms are supported:
| Windows | Windows 8 | |
| Mac | | |
-## Windows
-
-### Binaries
-
-The Windows version of eSpeak NG 1.49.2 is available as:
-
-* [espeak-ng-x64.msi](https://github.com/espeak-ng/espeak-ng/releases/download/1.49.2/espeak-ng-x64.msi) --
- 64-bit Windows installer
-* [espeak-ng-x86.msi](https://github.com/espeak-ng/espeak-ng/releases/download/1.49.2/espeak-ng-x86.msi) --
- 32-bit Windows installer
-
-You also need to install the [Visual C++ Redistributable for Visual Studio 2015](https://www.microsoft.com/en-us/download/details.aspx?id=48145).
-
-__NOTE:__ SAPI 5 voices are not currently available in this release of eSpeak NG.
-There is an [issue](https://github.com/espeak-ng/espeak-ng/issues/7) to track
-support for this feature.
-
-### Building
-
-To build eSpeak NG on Windows, you will need:
-
-1. a copy of Visual Studio 2013 or later, such as the Community Edition;
-2. the Windows 8.1 SDK;
-3. the [WiX installer](http://wixtoolset.org) plugin;
-4. the [pcaudiolib](https://github.com/espeak-ng/pcaudiolib) project checked out to
- `src` (as `src/pcaudiolib`).
-
-You can then open and build the `src/windows/espeak-ng.sln` solution in Visual
-Studio.
-
-You can also use the Visual Studio tools to build espeak-ng with `msbuild` from
-the `src/windows` directory:
-
- msbuild espeak-ng.sln
-
-To build with a specific version of Visual Studio, you need to use:
-
- msbuild /p:PlatformToolset=v120 espeak-ng.sln
-
-replacing `v120` with the appropriate value for the target Visual Studio version:
-
-| PlatformToolset | Visual Studio |
-|-----------------|---------------|
-| v120 | 2013 |
-| v140 | 2015 |
-| v141 (default) | 2017 |
-
-## Linux, Mac, BSD
-
-### Dependencies
-
-In order to build eSpeak NG, you need:
-
-1. a functional autotools system (`make`, `autoconf`, `automake`, `libtool`
- and `pkg-config`);
-2. a functional c compiler that supports C99 (e.g. gcc or clang).
-
-Optionally, you need:
-
-1. the [pcaudiolib](https://github.com/espeak-ng/pcaudiolib) development library
- to enable audio output;
-3. the [sonic](https://github.com/espeak-ng/sonic) development library to
- enable sonic audio speed up support;
-4. the `ronn` man-page markdown processor to build the man pages.
-
-To build the documentation, you need:
-
-1. the `kramdown` markdown processor.
-
-On Debian-based systems such as Debian, Ubuntu and Mint, these dependencies can
-be installed using the following commands:
-
-| Dependency | Install |
-|---------------|------------------------------------------------------------------|
-| autotools | `sudo apt-get install make autoconf automake libtool pkg-config` |
-| c99 compiler | `sudo apt-get install gcc` |
-| sonic | `sudo apt-get install libsonic-dev` |
-| ronn | `sudo apt-get install ruby-ronn` |
-| kramdown | `sudo apt-get install ruby-kramdown` |
-
-For recent Debian or Ubuntu >= 18.04 you should also install:
-
-| Dependency | Install |
-|---------------|------------------------------------------------------------------|
-| pcaudiolib | `sudo apt-get install libpcaudio-dev` |
-
-### Building
-
-The first time you build eSpeak NG, or when you want to change how to build
-eSpeak NG, you need to run the following standard autotools commands:
-
- ./autogen.sh
- ./configure --prefix=/usr
-
-__NOTE:__ The `--prefix` option above will install the files to the `/usr`
-directory, instead of the default `/usr/local` location. You can use other
-standard `configure` options to control the output. For more information,
-you can run:
-
- ./configure --help
-
-To use a different compiler, or compiler flags, you can specify these before
-the `configure` command. For example:
-
- CC=clang-3.5 CFLAGS=-Wextra ./configure --prefix=/usr
-
-The `espeak-ng` and `speak-ng` programs, along with the espeak-ng voices, can
-then be built with:
-
- make
-
-__NOTE:__ Building the voice data does not work when using the `-jN` option.
-If you want to use that option, you can run:
-
- make -j8 src/espeak-ng src/speak-ng
- make
-
-The documentation can be built by running:
-
- make docs
-
-Specific languages can be compiled by running:
-
- make LANG
-
-where `LANG` is the language code of the given language. More information can
-be found in the [Adding or Improving a Language](docs/add_language.md)
-documentation.
-
-#### Cross Compilation
-
-Because the eSpeak NG build process uses the built program to compile the
-language and voice data, you need to build it locally first. Once you have
-built it locally you can perform the cross compilation using:
-
- ./configure --build=... --host=... --target=...
- make -B src/espeak-ng src/speak-ng
-
-#### Sanitizer Flag Configuration
-
-It is possible to build eSpeak NG with the gcc or clang sanitizer by passing
-the appropriate `CFLAGS` and `LDFLAGS` options to `configure`. For example:
-
- CFLAGS="-fsanitize=address,undefined -g" \
- LDFLAGS="-fsanitize=address,undefined" \
- CC=clang-6.0 ./configure
- make
- make check
-
-__NOTE:__ The `-fsanitize=fuzzer` option does not work when using the above
-configuration method. This is because `clang` will use the `libFuzzer` library
-which defines its own `main` and requires `LLVMFuzzerTestOneInput` to be
-defined. This breaks the autoconf check to see if the C compiler works.
-
-#### LLVM Fuzzer Support
-
-To enable libFuzzer support you need clang 6.0 or later. It is enabled with
-the following:
-
- CC=clang-6.0 ./configure --with-libfuzzer=yes
- make
- make check
-
-#### eSpeak NG Feature Configuration
-
-The following `configure` options control which eSpeak NG features are enabled:
-
-| Option | Description | Default |
-|-----------------|----------------------------------------------|---------|
-| `--with-klatt` | Enable Klatt formant synthesis. | yes |
-| `--with-mbrola` | Enable MBROLA voice support. | yes |
-| `--with-sonic` | Use the sonic library to support higher WPM. | yes |
-| `--with-async` | Enable asynchronous commands. | yes |
-
-__NOTE:__ The `--with-sonic` option requires that the sonic library and header
-is accessible on the system.
-
-#### Extended Dictionary Configuration
-
-The following `configure` options control which of the extended dictionary files
-to build:
-
-| Option | Extended Dictionary | Default |
-|----------------------|---------------------|---------|
-| `--with-extdict-ru` | Russian | no |
-| `--with-extdict-zh` | Mandarin Chinese | no |
-| `--with-extdict-zhy` | Cantonese | no |
-
-The extended dictionaries are taken from
-[http://espeak.sourceforge.net/data/](http://espeak.sourceforge.net/data/) and
-provide better coverage for those languages, while increasing the resulting
-dictionary size.
-
-### Testing
-
-Before installing, you can test the built espeak-ng using the following command
-from the top-level directory of this project:
-
- ESPEAK_DATA_PATH=`pwd` LD_LIBRARY_PATH=src:${LD_LIBRARY_PATH} src/espeak-ng ...
-
-The `ESPEAK_DATA_PATH` variable needs to be set to use the espeak-ng data from
-the source tree. Otherwise, espeak-ng will look in `$(HOME)` or
-`/usr/share/espeak-ng-data`.
-
-The `LD_LIBRARY_PATH` is set as `espeak` uses the `libespeak-ng.so` shared
-library. This ensures that `espeak` uses the built shared library in the
-`src` directory and not the one on the system (which could be an older
-version).
-
-### Installing
-
-You can install eSpeak NG by running the following command:
-
- sudo make LIBDIR=/usr/lib/x86_64-linux-gnu install
-
-__NOTE:__ The `LIBDIR` path may be different to the one on your system (the
-above is for 64-bit Debian/Ubuntu releases that use the multi-arch package
-structure -- that is, Debian Wheezy or later).
-
-You can find out where espeak-ng is installed to on your system if you
-already have an espeak-ng install by running:
-
- find /usr/lib | grep libespeak-ng
-
-## Android
-
-

-
-The espeak-ng sources contain the code for the Android™ port of the application.
-This is published as the [eSpeak for Android](http://reecedunn.co.uk/espeak-for-android)
-program on the Google Play store. It is based on the eyes-free port of eSpeak
-to the Android platform. This code was originally maintained in a separate
-branch when the repository tracked eSpeak releases.
-
-### Dependencies
-
-In order to build the Android APK file, you need:
-
-1. the [Android Studio](https://developer.android.com/studio/) with API 26 support;
-2. the [Android NDK](http://developer.android.com/tools/sdk/ndk/index.html);
-3. Gradle 3.2.1 or later.
-
-### Building with Gradle
-
-1. Set the location of the Android SDK:
-
- $ export ANDROID_HOME=
-(where `` is your actual path of SDK folder e.g. `/home/user/Android/Sdk`)
-
-2. Add location of NDK to the PATH variable:
-
- $ export PATH=$PATH:
-(where `` is your actual path of NDK folder, e.g. `/home/user/Android/Ndk`)
-
-3. Configure the project:
-
- $ ./autogen.sh
- $ ./configure --with-gradle=
-
-Check that log shows following lines:
-
- ...
- gradle (Android): gradle
- ndk-build (Android): yes
- ...
-`` may be just `gradle` if it is found in your path by simple name.
-
-4. Build the project:
-
- $ make apk-release
-
-This will create an `android/build/outputs/apk/espeak-release-unsigned.apk` file.
-
-### Signing the APK
-
-In order to install the built APK you need to self-sign the package. You can do
-this by:
-
-1. Creating a certificate, if you do not already have one:
-
- $ keytool -genkey -keystore [YOUR_CERTIFICATE] -alias [ALIAS] -keyalg RSA -storetype PKCS12
-2. Sign the package using your certificate:
-
- $ jarsigner -sigalg MD5withRSA -digestalg SHA1 \
- -keystore [YOUR_CERTIFICATE] \
- android/build/outputs/apk/release/espeak-release-unsigned.apk [ALIAS]
-3. Align the apk using the zipalign tool.
-
- $ zipalign 4 android/build/outputs/apk/release/espeak-release-unsigned.apk \
- android/build/outputs/apk/release/espeak-release-signed.apk
-
-
-### Opening project in Android Studio
-
-To open project in **Android Studio** select **Import project (Gradle, Eclipse ADT, etc)**
-and select `android` folder of the `espeak-ng` project.
-
-Then select menu **File — Project Structure...**, tab **SDK Location**, field **Android NDK location**
-and set your location of NDK, e.g. `/home/user/Android/Ndk`.
-
-### Installing
-
-Now, you can install the APK using the `adb` tool:
-
- $ adb install -r android/build/outputs/apk/release/espeak-release-signed.apk
-
-After running, `eSpeakActivity` will extract the `espeakdata.zip` file into its
-own data directory to set up the available voices.
-
-To enable eSpeak, you need to:
-
-1. go into the Android `Text-to-Speech settings` UI;
-2. enable `eSpeak TTS` in the `Engines` section;
-3. select `eSpeak TTS` as the default engine;
-4. use the `Listen to an example` option to check if everything is working.
-
## Documentation
1. [User guide](src/espeak-ng.1.ronn) provides reference and examples for command-line options.
diff --git a/docs/building.md b/docs/building.md
new file mode 100644
index 00000000..c64aa3c9
--- /dev/null
+++ b/docs/building.md
@@ -0,0 +1,338 @@
+# Building eSpeak NG
+
+- [Windows](#windows)
+ - [Binaries](#binaries)
+ - [Building](#building)
+- [Linux, Mac, BSD](#linux-mac-bsd)
+ - [Dependencies](#dependencies)
+ - [Building](#building-1)
+ - [Cross Compilation](#cross-compilation)
+ - [Sanitizer Flag Configuration](#sanitizer-flag-configuration)
+ - [LLVM Fuzzer Support](#llvm-fuzzer-support)
+ - [eSpeak NG Feature Configuration](#espeak-ng-feature-configuration)
+ - [Extended Dictionary Configuration](#extended-dictionary-configuration)
+ - [Testing](#testing)
+ - [Installing](#installing)
+- [Android](#android)
+ - [Dependencies](#dependencies-1)
+ - [Building with Gradle](#building-with-gradle)
+ - [Signing the APK](#signing-the-apk)
+ - [Opening project in Android Studio](#opening-project-in-android-studio)
+ - [Installing](#installing-1)
+
+## Windows
+
+### Binaries
+
+The Windows version of eSpeak NG 1.49.2 is available as:
+
+* [espeak-ng-x64.msi](https://github.com/espeak-ng/espeak-ng/releases/download/1.49.2/espeak-ng-x64.msi) --
+ 64-bit Windows installer
+* [espeak-ng-x86.msi](https://github.com/espeak-ng/espeak-ng/releases/download/1.49.2/espeak-ng-x86.msi) --
+ 32-bit Windows installer
+
+You also need to install the [Visual C++ Redistributable for Visual Studio 2015](https://www.microsoft.com/en-us/download/details.aspx?id=48145).
+
+__NOTE:__ SAPI 5 voices are not currently available in this release of eSpeak NG.
+There is an [issue](https://github.com/espeak-ng/espeak-ng/issues/7) to track
+support for this feature.
+
+### Building
+
+To build eSpeak NG on Windows, you will need:
+
+1. a copy of Visual Studio 2013 or later, such as the Community Edition;
+2. the Windows 8.1 SDK;
+3. the [WiX installer](http://wixtoolset.org) plugin;
+4. the [pcaudiolib](https://github.com/espeak-ng/pcaudiolib) project checked out to
+ `src` (as `src/pcaudiolib`).
+
+You can then open and build the `src/windows/espeak-ng.sln` solution in Visual
+Studio.
+
+You can also use the Visual Studio tools to build espeak-ng with `msbuild` from
+the `src/windows` directory:
+
+ msbuild espeak-ng.sln
+
+To build with a specific version of Visual Studio, you need to use:
+
+ msbuild /p:PlatformToolset=v120 espeak-ng.sln
+
+replacing `v120` with the appropriate value for the target Visual Studio version:
+
+| PlatformToolset | Visual Studio |
+|-----------------|---------------|
+| v120 | 2013 |
+| v140 | 2015 |
+| v141 (default) | 2017 |
+
+## Linux, Mac, BSD
+
+### Dependencies
+
+In order to build eSpeak NG, you need:
+
+1. a functional autotools system (`make`, `autoconf`, `automake`, `libtool`
+ and `pkg-config`);
+2. a functional c compiler that supports C99 (e.g. gcc or clang).
+
+Optionally, you need:
+
+1. the [pcaudiolib](https://github.com/espeak-ng/pcaudiolib) development library
+ to enable audio output;
+3. the [sonic](https://github.com/espeak-ng/sonic) development library to
+ enable sonic audio speed up support;
+4. the `ronn` man-page markdown processor to build the man pages.
+
+To build the documentation, you need:
+
+1. the `kramdown` markdown processor.
+
+On Debian-based systems such as Debian, Ubuntu and Mint, these dependencies can
+be installed using the following commands:
+
+| Dependency | Install |
+|---------------|------------------------------------------------------------------|
+| autotools | `sudo apt-get install make autoconf automake libtool pkg-config` |
+| c99 compiler | `sudo apt-get install gcc` |
+| sonic | `sudo apt-get install libsonic-dev` |
+| ronn | `sudo apt-get install ruby-ronn` |
+| kramdown | `sudo apt-get install ruby-kramdown` |
+
+For recent Debian or Ubuntu >= 18.04 you should also install:
+
+| Dependency | Install |
+|---------------|------------------------------------------------------------------|
+| pcaudiolib | `sudo apt-get install libpcaudio-dev` |
+
+### Building
+
+The first time you build eSpeak NG, or when you want to change how to build
+eSpeak NG, you need to run the following standard autotools commands:
+
+ ./autogen.sh
+ ./configure --prefix=/usr
+
+__NOTE:__ The `--prefix` option above will install the files to the `/usr`
+directory, instead of the default `/usr/local` location. You can use other
+standard `configure` options to control the output. For more information,
+you can run:
+
+ ./configure --help
+
+To use a different compiler, or compiler flags, you can specify these before
+the `configure` command. For example:
+
+ CC=clang-3.5 CFLAGS=-Wextra ./configure --prefix=/usr
+
+The `espeak-ng` and `speak-ng` programs, along with the espeak-ng voices, can
+then be built with:
+
+ make
+
+__NOTE:__ Building the voice data does not work when using the `-jN` option.
+If you want to use that option, you can run:
+
+ make -j8 src/espeak-ng src/speak-ng
+ make
+
+The documentation can be built by running:
+
+ make docs
+
+Specific languages can be compiled by running:
+
+ make LANG
+
+where `LANG` is the language code of the given language. More information can
+be found in the [Adding or Improving a Language](docs/add_language.md)
+documentation.
+
+#### Cross Compilation
+
+Because the eSpeak NG build process uses the built program to compile the
+language and voice data, you need to build it locally first. Once you have
+built it locally you can perform the cross compilation using:
+
+ ./configure --build=... --host=... --target=...
+ make -B src/espeak-ng src/speak-ng
+
+#### Sanitizer Flag Configuration
+
+It is possible to build eSpeak NG with the gcc or clang sanitizer by passing
+the appropriate `CFLAGS` and `LDFLAGS` options to `configure`. For example:
+
+ CFLAGS="-fsanitize=address,undefined -g" \
+ LDFLAGS="-fsanitize=address,undefined" \
+ CC=clang-6.0 ./configure
+ make
+ make check
+
+__NOTE:__ The `-fsanitize=fuzzer` option does not work when using the above
+configuration method. This is because `clang` will use the `libFuzzer` library
+which defines its own `main` and requires `LLVMFuzzerTestOneInput` to be
+defined. This breaks the autoconf check to see if the C compiler works.
+
+#### LLVM Fuzzer Support
+
+To enable libFuzzer support you need clang 6.0 or later. It is enabled with
+the following:
+
+ CC=clang-6.0 ./configure --with-libfuzzer=yes
+ make
+ make check
+
+#### eSpeak NG Feature Configuration
+
+The following `configure` options control which eSpeak NG features are enabled:
+
+| Option | Description | Default |
+|-----------------|----------------------------------------------|---------|
+| `--with-klatt` | Enable Klatt formant synthesis. | yes |
+| `--with-mbrola` | Enable MBROLA voice support. | yes |
+| `--with-sonic` | Use the sonic library to support higher WPM. | yes |
+| `--with-async` | Enable asynchronous commands. | yes |
+
+__NOTE:__ The `--with-sonic` option requires that the sonic library and header
+is accessible on the system.
+
+#### Extended Dictionary Configuration
+
+The following `configure` options control which of the extended dictionary files
+to build:
+
+| Option | Extended Dictionary | Default |
+|----------------------|---------------------|---------|
+| `--with-extdict-ru` | Russian | no |
+| `--with-extdict-zh` | Mandarin Chinese | no |
+| `--with-extdict-zhy` | Cantonese | no |
+
+The extended dictionaries are taken from
+[http://espeak.sourceforge.net/data/](http://espeak.sourceforge.net/data/) and
+provide better coverage for those languages, while increasing the resulting
+dictionary size.
+
+### Testing
+
+Before installing, you can test the built espeak-ng using the following command
+from the top-level directory of this project:
+
+ ESPEAK_DATA_PATH=`pwd` LD_LIBRARY_PATH=src:${LD_LIBRARY_PATH} src/espeak-ng ...
+
+The `ESPEAK_DATA_PATH` variable needs to be set to use the espeak-ng data from
+the source tree. Otherwise, espeak-ng will look in `$(HOME)` or
+`/usr/share/espeak-ng-data`.
+
+The `LD_LIBRARY_PATH` is set as `espeak` uses the `libespeak-ng.so` shared
+library. This ensures that `espeak` uses the built shared library in the
+`src` directory and not the one on the system (which could be an older
+version).
+
+### Installing
+
+You can install eSpeak NG by running the following command:
+
+ sudo make LIBDIR=/usr/lib/x86_64-linux-gnu install
+
+__NOTE:__ The `LIBDIR` path may be different to the one on your system (the
+above is for 64-bit Debian/Ubuntu releases that use the multi-arch package
+structure -- that is, Debian Wheezy or later).
+
+You can find out where espeak-ng is installed to on your system if you
+already have an espeak-ng install by running:
+
+ find /usr/lib | grep libespeak-ng
+
+## Android
+
+
+
+The espeak-ng sources contain the code for the Android™ port of the application.
+This is published as the [eSpeak for Android](http://reecedunn.co.uk/espeak-for-android)
+program on the Google Play store. It is based on the eyes-free port of eSpeak
+to the Android platform. This code was originally maintained in a separate
+branch when the repository tracked eSpeak releases.
+
+### Dependencies
+
+In order to build the Android APK file, you need:
+
+1. the [Android Studio](https://developer.android.com/studio/) with API 26 support;
+2. the [Android NDK](http://developer.android.com/tools/sdk/ndk/index.html);
+3. Gradle 3.2.1 or later.
+
+### Building with Gradle
+
+1. Set the location of the Android SDK:
+
+ $ export ANDROID_HOME=
+(where `` is your actual path of SDK folder e.g. `/home/user/Android/Sdk`)
+
+2. Add location of NDK to the PATH variable:
+
+ $ export PATH=$PATH:
+(where `` is your actual path of NDK folder, e.g. `/home/user/Android/Ndk`)
+
+3. Configure the project:
+
+ $ ./autogen.sh
+ $ ./configure --with-gradle=
+
+Check that log shows following lines:
+
+ ...
+ gradle (Android): gradle
+ ndk-build (Android): yes
+ ...
+`` may be just `gradle` if it is found in your path by simple name.
+
+4. Build the project:
+
+ $ make apk-release
+
+This will create an `android/build/outputs/apk/espeak-release-unsigned.apk` file.
+
+### Signing the APK
+
+In order to install the built APK you need to self-sign the package. You can do
+this by:
+
+1. Creating a certificate, if you do not already have one:
+
+ $ keytool -genkey -keystore [YOUR_CERTIFICATE] -alias [ALIAS] -keyalg RSA -storetype PKCS12
+2. Sign the package using your certificate:
+
+ $ jarsigner -sigalg MD5withRSA -digestalg SHA1 \
+ -keystore [YOUR_CERTIFICATE] \
+ android/build/outputs/apk/release/espeak-release-unsigned.apk [ALIAS]
+3. Align the apk using the zipalign tool.
+
+ $ zipalign 4 android/build/outputs/apk/release/espeak-release-unsigned.apk \
+ android/build/outputs/apk/release/espeak-release-signed.apk
+
+
+### Opening project in Android Studio
+
+To open project in **Android Studio** select **Import project (Gradle, Eclipse ADT, etc)**
+and select `android` folder of the `espeak-ng` project.
+
+Then select menu **File — Project Structure...**, tab **SDK Location**, field **Android NDK location**
+and set your location of NDK, e.g. `/home/user/Android/Ndk`.
+
+### Installing
+
+Now, you can install the APK using the `adb` tool:
+
+ $ adb install -r android/build/outputs/apk/release/espeak-release-signed.apk
+
+After running, `eSpeakActivity` will extract the `espeakdata.zip` file into its
+own data directory to set up the available voices.
+
+To enable eSpeak, you need to:
+
+1. go into the Android `Text-to-Speech settings` UI;
+2. enable `eSpeak TTS` in the `Engines` section;
+3. select `eSpeak TTS` as the default engine;
+4. use the `Listen to an example` option to check if everything is working.
+