Update documentation [ci skip]

The documentation for building and installing has been moved into a new
Documentation section

Closes: #788 (cherry-picked)

3 files changed, 143 insertions, 141 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 38756939..2019af38 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,4 +1,4 @@
-# Contributing to the libevent
+# Contributing to libevent
 
 ## Coding style
 
@@ -33,3 +33,6 @@ git format-patch --stdout -2
 ## Testing
 - Write new unit test in `test/regress_{MORE_SUITABLE_FOR_YOU}.c`
 - `make verify`
+
+## Asking Questions
+It's all right to have questions! Instead of filing an issue here, go ahead and leave a message in our [Gitter Room](https://gitter.im/libevent/libevent)
diff --git a/Documentation/Building.md b/Documentation/Building.md
new file mode 100644
index 00000000..fe957641
--- /dev/null
+++ b/Documentation/Building.md
@@ -0,0 +1,125 @@
+# Building and installing Libevent
+### Jump to:
+- [Autoconf](#autoconf)
+  - [Flags](#autoconf-flags)
+- [Building on Windows](#building-on-windows)
+- [Building on Unix (With CMake)](#building-on-unix-cmake)
+- [CMake Variables](#cmake-variables)
+
+## Autoconf
+
+```
+$ ./configure
+$ make
+```
+
+**Note: If you had downloaded libevent from the Git repository, then you have to run `./autogen.sh` first!**
+
+You can run the regression tests by running
+```
+$ make verify
+```
+*Before reporting any problems, please run the regression tests.*
+
+Install as root via
+```
+$ make install
+```
+
+To enable low-level tracing, build the library as:
+```
+$ CFLAGS=-DUSE_DEBUG ./configure [...]
+```
+
+### Autoconf flags
+
+Standard configure flags should work. In particular, see:
+```
+ --disable-shared          Only build static libraries.
+ --prefix                  Install all files relative to this directory.
+```
+
+The configure script also supports the following flags:
+```
+ --enable-gcc-warnings     Enable extra compiler checking with GCC.
+ --disable-malloc-replacement
+                           Don't let applications replace our memory
+                           management functions.
+ --disable-openssl         Disable support for OpenSSL encryption.
+ --disable-thread-support  Don't support multithreaded environments.
+```
+
+## Building on Windows
+__Download CMake for Windows [here](https://cmake.org/download/)__
+```
+> md build && cd build
+> cmake -G "Visual Studio 10" .. # Or use any generator you want to use. Run cmake --help for a list
+> start libevent.sln
+```
+In the above, the ".." refers to the dir containing the Libevent source code. You can build multiple versions (with different compile time settings) from the same source tree by creating other build directories.
+
+It is highly recommended to build "out of source" when using CMake instead of "in source" like the normal behaviour of autoconf for this reason.
+
+The "NMake Makefiles" CMake generator can be used to build entirely via the command line:
+```
+> cmake -LH ..
+```
+
+## Building on Unix (CMake)
+__Install Cmake with your distribution's package manager `apt-get`/`dnf`/etc__
+```
+$ mkdir build && cd build
+$ cmake .. # Default to Unix Makefiles
+$ make
+$ make verify # Optional
+```
+
+## CMake Variables
+```
+# Type of the library to build (SHARED or STATIC)
+# Default is: SHARED for MSVC, otherwise BOTH
+EVENT__LIBRARY_TYPE:STRING=DEFAULT
+
+# Installation directory for CMake files
+EVENT_INSTALL_CMAKE_DIR:PATH=lib/cmake/libevent
+
+# Enable running gcov to get a test coverage report (only works with
+# GCC/CLang). Make sure to enable -DCMAKE_BUILD_TYPE=Debug as well.
+EVENT__COVERAGE:BOOL=OFF
+
+# Defines if Libevent should build without the benchmark executables
+EVENT__DISABLE_BENCHMARK:BOOL=OFF
+
+# Define if Libevent should build without support for a debug mode
+EVENT__DISABLE_DEBUG_MODE:BOOL=OFF
+
+# Define if Libevent should not allow replacing the mm functions
+EVENT__DISABLE_MM_REPLACEMENT:BOOL=OFF
+
+# Define if Libevent should build without support for OpenSSL encryption
+EVENT__DISABLE_OPENSSL:BOOL=OFF
+
+# Disable the regress tests
+EVENT__DISABLE_REGRESS:BOOL=OFF
+
+# Disable sample files
+EVENT__DISABLE_SAMPLES:BOOL=OFF
+
+# If tests should be compiled or not
+EVENT__DISABLE_TESTS:BOOL=OFF
+
+# Define if Libevent should not be compiled with thread support
+EVENT__DISABLE_THREAD_SUPPORT:BOOL=OFF
+
+# Enables verbose debugging
+EVENT__ENABLE_VERBOSE_DEBUG:BOOL=OFF
+
+# When cross compiling, forces running a test program that verifies that Kqueue
+# works with pipes. Note that this requires you to manually run the test program
+# on the the cross compilation target to verify that it works. See CMake
+# documentation for try_run for more details
+EVENT__FORCE_KQUEUE_CHECK:BOOL=OFF
+```
+__More variables can be found by running `cmake -LAH <sourcedir_path>`__
+
+[Back to top &uarr;](#jump-to)
diff --git a/README.md b/README.md
index db86d7ba..e51f6496 100644
--- a/README.md
+++ b/README.md
@@ -11,167 +11,41 @@
 
 
 
-# 0. BUILDING AND INSTALLATION (Briefly)
+# 1. BUILDING AND INSTALLATION
 
 ## Autoconf
 
-     $ ./configure
-     $ make
-     $ make verify   # (optional)
-     $ sudo make install
-
-## CMake (General)
-
-
-The following Libevent specific CMake variables are as follows (the values being
-the default).
-
 ```
-# Type of the library to build (SHARED or STATIC)
-# Default is: SHARED for MSVC, otherwise BOTH
-EVENT__LIBRARY_TYPE:STRING=DEFAULT
-
-# Installation directory for CMake files
-EVENT_INSTALL_CMAKE_DIR:PATH=lib/cmake/libevent
-
-# Enable running gcov to get a test coverage report (only works with
-# GCC/CLang). Make sure to enable -DCMAKE_BUILD_TYPE=Debug as well.
-EVENT__COVERAGE:BOOL=OFF
-
-# Defines if Libevent should build without the benchmark executables
-EVENT__DISABLE_BENCHMARK:BOOL=OFF
-
-# Define if Libevent should build without support for a debug mode
-EVENT__DISABLE_DEBUG_MODE:BOOL=OFF
-
-# Define if Libevent should not allow replacing the mm functions
-EVENT__DISABLE_MM_REPLACEMENT:BOOL=OFF
-
-# Define if Libevent should build without support for OpenSSL encryption
-EVENT__DISABLE_OPENSSL:BOOL=OFF
-
-# Disable the regress tests
-EVENT__DISABLE_REGRESS:BOOL=OFF
-
-# Disable sample files
-EVENT__DISABLE_SAMPLES:BOOL=OFF
-
-# If tests should be compiled or not
-EVENT__DISABLE_TESTS:BOOL=OFF
-
-# Define if Libevent should not be compiled with thread support
-EVENT__DISABLE_THREAD_SUPPORT:BOOL=OFF
-
-# Enables verbose debugging
-EVENT__ENABLE_VERBOSE_DEBUG:BOOL=OFF
-
-# When cross compiling, forces running a test program that verifies that Kqueue
-# works with pipes. Note that this requires you to manually run the test program
-# on the the cross compilation target to verify that it works. See CMake
-# documentation for try_run for more details
-EVENT__FORCE_KQUEUE_CHECK:BOOL=OFF
+$ ./configure
+$ make
+$ make verify   # (optional)
+$ sudo make install
 ```
 
-__More variables can be found by running `cmake -LAH <sourcedir_path>`__
-
+See [Documentation/Building#Autoconf](/Documentation/Building.md#autoconf) for more information
 
 ## CMake (Windows)
 
 Install CMake: <https://www.cmake.org>
 
-
-     $ md build && cd build
-     $ cmake -G "Visual Studio 10" ..   # Or whatever generator you want to use cmake --help for a list.
-     $ start libevent.sln
-
-## CMake (Unix)
-
-     $ mkdir build && cd build
-     $ cmake ..     # Default to Unix Makefiles.
-     $ make
-     $ make verify  # (optional)
-
-
-# 1. BUILDING AND INSTALLATION (In Depth)
-
-## Autoconf
-
-To build Libevent, type
-
-     $ ./configure && make
-
-
- (If you got Libevent from the git repository, you will
-  first need to run the included "autogen.sh" script in order to
-  generate the configure script.)
-
-You can run the regression tests by running
-
-     $ make verify
-
-Install as root via
-
-     $ make install
-
-Before reporting any problems, please run the regression tests.
-
-To enable low-level tracing, build the library as:
-
-     $ CFLAGS=-DUSE_DEBUG ./configure [...]
-
-Standard configure flags should work.  In particular, see:
-
-     --disable-shared          Only build static libraries.
-     --prefix                  Install all files relative to this directory.
-
-
-The configure script also supports the following flags:
-
-     --enable-gcc-warnings     Enable extra compiler checking with GCC.
-     --disable-malloc-replacement
-                               Don't let applications replace our memory
-                               management functions.
-     --disable-openssl         Disable support for OpenSSL encryption.
-     --disable-thread-support  Don't support multithreaded environments.
-
-## CMake (Windows)
-
-(Note that autoconf is currently the most mature and supported build
-environment for Libevent; the CMake instructions here are new and
-experimental, though they _should_ be solid.  We hope that CMake will
-still be supported in future versions of Libevent, and will try to
-make sure that happens.)
-
-First of all install <https://www.cmake.org>.
-
-To build Libevent using Microsoft Visual studio open the "Visual Studio Command prompt" and type:
-
 ```
-$ cd <libevent source dir>
-$ mkdir build && cd build
+$ md build && cd build
 $ cmake -G "Visual Studio 10" ..   # Or whatever generator you want to use cmake --help for a list.
 $ start libevent.sln
 ```
 
-In the above, the ".." refers to the dir containing the Libevent source code. 
-You can build multiple versions (with different compile time settings) from the same source tree
-by creating other build directories. 
-
-It is highly recommended to build "out of source" when using
-CMake instead of "in source" like the normal behaviour of autoconf for this reason.
-
-The "NMake Makefiles" CMake generator can be used to build entirely via the command line.
+See [Documentation/Building#Building on Windows](/Documentation/Building.md#building-on-windows) for more information
 
-To get a list of settings available for the project you can type:
+## CMake (Unix)
 
 ```
-$ cmake -LH ..
+$ mkdir build && cd build
+$ cmake ..     # Default to Unix Makefiles.
+$ make
+$ make verify  # (optional)
 ```
 
-### GUI
-
-CMake also provides a GUI that lets you specify the source directory and output (binary) directory
-that the build should be placed in.
+See [Documentation/Building#Building on Unix (With CMake)](/Documentation/Building.md#building-on-unix-cmake) for more information
 
 # 2. USEFUL LINKS: