From df282f8f3dac0707151e12a723b85a3068e1ba01 Mon Sep 17 00:00:00 2001
From: Valdis Vitolins <valdis.vitolins@odo.lv>
Date: Tue, 21 Jul 2020 17:58:01 +0300
Subject: [PATCH] docs: add dedicated user guide for installation and usage

---
 README.md     |  2 +-
 docs/guide.md | 78 +++++++++++++++++++++++++++++++++++++++++++++++++++
 docs/index.md |  4 +--
 3 files changed, 81 insertions(+), 3 deletions(-)
 create mode 100644 docs/guide.md

diff --git a/README.md b/README.md
index 8a148929..0111ace8 100644
--- a/README.md
+++ b/README.md
@@ -62,7 +62,7 @@ The following platforms are supported:
 
 ## Documentation
 
-1. [User guide](src/espeak-ng.1.ronn) provides reference and examples for command-line options.
+1. [User guide](docs/guide.md) explains how to set up and use eSpeak NG from command line or as a library.
 2. [Building guide](docs/building.md) provides info how to compile and build eSpeak NG from the source.
 3. [Integration guide](docs/integration.md) provides samples how to use eSpeak NG as a library.
 4. [Index](docs/index.md) provides full list of more detailed information for contributors and developers.
diff --git a/docs/guide.md b/docs/guide.md
new file mode 100644
index 00000000..cc739a3f
--- /dev/null
+++ b/docs/guide.md
@@ -0,0 +1,78 @@
+# eSpeak NG user guide
+
+- [Installation](#installation)
+  - [Linux](#linux)
+  - [Windows](#windows)
+- Command line usage
+  - [espeak-ng Command Line](../src/espeak-ng.1.ronn)
+  - [speak-ng Command Line](../src/speak-ng.1.ronn)
+- Library usage
+  - [Integration guide](docs/integration.md)
+- [Error solutions](#error-solutions)
+  - [Problems with pcaudiolib](#problems-with-pcaudiolib)
+  - [Problems with pulseaudio](#problems-with-pulseaudio)
+- [Index](docs/index.md)
+
+## Installation
+### Linux
+
+To install precompiled package of eSpeak NG on Linux, use standard package manager of your
+distribution. (Probably is very high, eSpeak NG will be included in package repository).
+
+E.g. for Debian-like distribution (e.g. Ubuntu, Mint, etc.) execute command:
+
+    sudo apt-get install espeak-ng
+
+For RedHat-like distribution (e.g. CentOS, Fedora, etc.) execute command:
+
+    sudo yum install espeak-ng
+
+### Windows
+
+To install precompiled binaries of eSpeak NG on Windows:
+
+1. open (https://github.com/espeak-ng/espeak-ng/releases) and click on **Latest release** and then appropriate *.msi file, e.g. **espeak-ng-20191129-b702b03-x64.msi**
+
+2. Execute downloaded installer package.
+
+## Error solutions
+
+## Problems with pcaudiolib
+
+if `espeak-ng` is compiled and installed without [pcaudiolib](https://github.com/espeak-ng/pcaudiolib) compiled and installed before, then calling it simply
+
+    espeak-ng hello
+
+doesn't produce any sound.
+Then usual workaround with sending data standard output and piping it to `aplay` (Lubuntu) or `paplay` (Ubuntu) works:
+
+    espeak-ng hello --stdout|aplay
+
+But, when `pcaudiolib` is compiled and installed and espeak-ng is reconfigured, recompiled and reinstalled again, simple call works properly.
+
+If espeak-ng is built from source code, ensure that `libpulse-dev` package is installed, or [pcaudiolib](https://github.com/espeak-ng/pcaudiolib) built and installed and, when do `./configure` command, check that status says:
+
+    PulseAudio support:            yes
+
+Then recmpile and install espeak-ng aganin.
+
+
+## Problems with pulseaudio
+
+If Linux distribution doesn't support pulseaudio sound system (or it doesn't work):
+
+1. Remove _pulseaudio_ package install _alsa_:
+
+       sudo apt purge pulseaudio
+       sudo apt autoremove
+       sudo apt install --reinstall alsa
+2. Reboot
+
+       sudo reboot
+3. Recompile espeak-ng with ` --with-pulseaudio=no` support:
+
+       ./autogen.sh
+       ./configure --prefix=/usr --with-pulseaudio=no
+       make -B
+       sudo make install
+
diff --git a/docs/index.md b/docs/index.md
index 75c97fd8..f8deacb8 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,13 +1,13 @@
 # eSpeak NG online documentation
 
-- User Guide
+- [User Guide](guide.md)
   - [espeak-ng Command Line](../src/espeak-ng.1.ronn)
   - [speak-ng Command Line](../src/speak-ng.1.ronn)
   - [Supported Languages](languages.md)
   - [SSML and HTML Support](markup.md)
+  - [Using eSpeak NG as a C library](integration.md)
 - [Contributor Guide](contributing.md)
   - [Building eSpeak NG](building.md)
-  - [Using eSpeak NG as a C library](integration.md)
 - Creating and Editing Languages and Voices
     - [Adding or Improving a Language](add_language.md)
     - [Text to Phoneme Translation](dictionary.md)