docs: refresh installation instructions and general cleanup

Change-Id: Ibfe945887e5cad979c1f9a78fd5a3062bb20a8b5
diff --git a/docs/INSTALL.rst b/docs/INSTALL.rst
index 428c064..864bb10 100644
--- a/docs/INSTALL.rst
+++ b/docs/INSTALL.rst
@@ -11,9 +11,9 @@
 
 -  Ubuntu 16.04 (amd64, armhf, i386)
 -  Ubuntu 18.04 (amd64)
--  OS X 10.11
 -  macOS 10.12
 -  macOS 10.13
+-  macOS 10.14
 
 ndn-cxx is known to work on the following platforms, although they are not officially
 supported:
@@ -22,6 +22,9 @@
 -  Fedora >= 24
 -  Gentoo Linux
 -  Raspbian >= 2017-08-16
+-  OS X 10.11
+-  FreeBSD 11.2
+
 
 Prerequisites
 -------------
@@ -31,48 +34,46 @@
 
 -  GCC >= 5.3, or clang >= 3.6
 -  ``python2`` >= 2.7, or ``python3`` >= 3.4
--  ``libsqlite3``
--  OpenSSL >= 1.0.2
--  ``pkg-config``
 -  Boost libraries >= 1.58
--  OSX Security framework (on OSX/macOS platform only)
+-  ``pkg-config``
+-  SQLite 3.x
+-  OpenSSL >= 1.0.2
+-  Apple Security framework (on macOS only)
 
 Following are the detailed steps for each platform to install the compiler, all necessary
 development tools and libraries, and ndn-cxx prerequisites.
 
--  OS X / macOS
+- macOS
 
-   Install Xcode from AppStore or at least Command Line Tools (``xcode-select --install``)
+    * Install Xcode from the App Store, or at least the Command Line Tools
+      (``xcode-select --install``)
 
-   * When using MacPorts
+    * If using Homebrew (recommended), enter the following in a terminal::
 
-       In a terminal, enter::
+        brew install boost openssl pkg-config
 
-           sudo port install pkgconfig boost sqlite3 openssl
+      .. note::
 
-   * When using Homebrew
+        If a major OS upgrade is performed after installing the dependencies
+        with Homebrew, remember to reinstall all packages.
 
-       In a terminal, enter::
-
-           brew install boost openssl pkg-config
-
-   .. note::
-
-      If a major OS upgrade is performed after installing dependencies with
-      MacPorts or Homebrew, remember to reinstall all packages.
-
--  Ubuntu
+- Ubuntu
 
     In a terminal, enter::
 
-        sudo apt-get install build-essential libsqlite3-dev libboost-all-dev libssl-dev
+        sudo apt install build-essential libsqlite3-dev libboost-all-dev libssl-dev
 
 - Fedora
 
     In a terminal, enter::
 
-        sudo yum install gcc-g++ git
-        sudo yum install sqlite-devel boost-devel openssl-devel
+        sudo yum install gcc-g++ sqlite-devel boost-devel openssl-devel
+
+- FreeBSD
+
+    In a terminal, enter::
+
+        sudo pkg install python pkgconf sqlite3 boost-libs
 
 Optional:
 ~~~~~~~~~
@@ -82,49 +83,48 @@
 
 -  ``doxygen``
 -  ``graphviz``
--  ``python-sphinx`` and sphinx extensions ``sphinxcontrib-doxylink``,
-   ``sphinxcontrib-googleanalytics``
+-  ``python-sphinx``
+-  ``sphinxcontrib-doxylink``
 
 The following lists steps for common platforms to install these prerequisites:
 
--  On OS X / macOS with MacPorts::
+- On macOS with Homebrew and pip::
 
-       sudo port install doxygen graphviz py27-sphinx sphinx_select
-       sudo port select sphinx py27-sphinx
+    brew install doxygen graphviz
+    sudo pip install sphinx sphinxcontrib-doxylink
 
-       # Install sphinx extensions
-       sudo port install py27-pip
-       sudo port select pip pip27
-       sudo pip install sphinxcontrib-doxylink sphinxcontrib-googleanalytics
+- On Ubuntu::
 
--  On Ubuntu::
+    sudo apt install doxygen graphviz python3-pip
+    sudo pip3 install sphinx sphinxcontrib-doxylink
 
-       sudo apt-get install doxygen graphviz python-sphinx python-pip
-       sudo pip install sphinxcontrib-doxylink sphinxcontrib-googleanalytics
+- On Fedora::
 
--  On Fedora::
+    sudo yum install doxygen graphviz python-sphinx
+    sudo pip install sphinxcontrib-doxylink
 
-       sudo yum install doxygen graphviz python-sphinx
-       sudo pip install sphinxcontrib-doxylink sphinxcontrib-googleanalytics
+- On FreeBSD::
+
+    sudo pkg install doxygen graphviz py27-sphinx
+
 
 .. _build:
 
 Build
 -----
 
-(These are instructions to build ndn-cxx. To do development of ndn-cxx
-code and update the build system, see Development.)
+.. note::
+  These are instructions for regular builds of ndn-cxx (release mode).
+  To do development of ndn-cxx code itself, see "Development build" below.
 
-To build in a terminal, change directory to the ndn-cxx root. Enter:
-
-::
+To build in a terminal, change directory to the ndn-cxx root, then enter::
 
     ./waf configure
     ./waf
     sudo ./waf install
 
 By default, only the shared version of ndn-cxx library is built.  To build the static library,
-use ``--enable-static`` option for ``./waf configure`` command.  For example::
+use ``--enable-static`` option for ``./waf configure`` command::
 
     ./waf configure --enable-static
 
@@ -136,83 +136,63 @@
 
     ./waf configure --enable-static --disable-shared
 
+After the shared library is installed, on Linux it is also necessary to run::
 
-After the shared library is built and installed, some systems require additional actions.
+    sudo ldconfig
 
-  - on Linux::
+.. note::
+  When the library is installed in a non-standard path (in general: not in ``/usr/lib``
+  or ``/usr/local/lib``; on some Linux distros including Fedora: not in ``/usr/lib``),
+  additional actions may be necessary.
 
-      sudo ldconfig
+  The installation path should be added to ``/etc/ld.so.conf`` (or in
+  ``/etc/ld.so.conf.d``) **before** running ``sudo ldconfig``. For example::
 
-  - on FreeBSD::
+      echo /usr/local/lib | sudo tee /etc/ld.so.conf.d/ndn-cxx.conf
 
-      sudo ldconfig -m
+  Alternatively, the ``LD_LIBRARY_PATH`` environment variable can be set to point to
+  the installation directory of the shared library::
 
-  .. note::
-     When library is installed in a non-standard path (in general: not in ``/usr/lib`` or
-     ``/usr/local/lib``; on some Linux distros including Fedora: not in ``/usr/lib``),
-     additional actions may be necessary.
+      export LD_LIBRARY_PATH=/usr/local/lib
 
-     The installation path should be added to ``/etc/ld.so.conf`` (or in
-     ``/etc/ld.so.conf.d``) **before** running ``sudo ldconfig``. For example::
+The ``./waf install`` command installs the following files:
 
-         echo /usr/local/lib | sudo tee /etc/ld.so.conf.d/ndn-cxx.conf
-
-     Alternatively, ``LD_LIBRARY_PATH`` environment variable should be set to the location of
-     the library::
-
-         export LD_LIBRARY_PATH=/usr/local/lib
-
-This builds and installs the following items:
-
--  ``<LIBPATH>/libndn-cxx.a``: static NDN C++ library (if enabled)
+-  ``<LIBPATH>/libndn-cxx.a``: static NDN C++ library (if enabled).
 -  ``<LIBPATH>/libndn-cxx.so``, ``<LIBPATH>/libndn-cxx.so.<VERSION>`` (on Linux),
-   ``<LIBPATH>/libndn-cxx.dylib``, ``<LIBPATH>/libndn-cxx.<VERSION>.dylib`` (on OS X):
-   shared NDN C++ library (if enabled)
+   ``<LIBPATH>/libndn-cxx.dylib``, ``<LIBPATH>/libndn-cxx.<VERSION>.dylib`` (on macOS):
+   shared NDN C++ library (if enabled).
 -  ``<LIBPATH>/pkgconfig/libndn-cxx.pc``: pkgconfig file storing all
    neccessary flags to build against the library. For example, if
-   pkgconfig or pkgconf package is installed and ``PKG_CONFIG_PATH`` is
+   pkg-config or pkgconf package is installed and ``PKG_CONFIG_PATH`` is
    configured properly (or ``<LIBPATH>/pkgconfig`` is a default path),
    ``pkgconfig --libs --clflags libndn-cxx`` will return all necessary
    compile and link flags for the library.
--  ``<BINPATH>/ndnsec``: tool to manage NDN keys and certificates
--  ``<BINPATH>/ndnsec-*``: convenience scripts for ``ndnsec`` tools
+-  ``<BINPATH>/ndnsec``: tool to manage NDN keys and certificates.
+-  ``<BINPATH>/ndnsec-*``: convenience aliases for ``ndnsec`` tools.
 
-If configured with tests: ``./waf configure --with-tests``), the above
+If configured with tests (``./waf configure --with-tests``), the above
 commands will also produce:
 
--  ``build/unit-tests``: A unit test binary for the library
+-  ``build/unit-tests``: a unit test binary for the library.
 
 1.5GB available memory per CPU core is necessary for efficient compilation.
 On a multi-core machine with less than 1.5GB available memory per CPU core,
 limit the objects being compiled in parallel with ``./waf -jN`` where N is the amount
 of available memory divided by 1.5GB (eg. ``./waf -j1`` for 1.5GB memory),
-which could usually avoid memory thrashing and result in faster compilation.
+which should usually avoid memory thrashing and result in faster compilation.
 
 Build with examples
 -------------------
 
-By default, examples in ``examples/`` are not build.  To enable them, use
-``--with-examples`` configure option:
-
-::
+By default, examples in ``examples/`` are not built.  To enable them, use the
+``--with-examples`` configure option::
 
     ./waf configure --with-examples
     ./waf
     sudo ./waf install
+    sudo ldconfig # (on Linux only)
 
-:ref:`Additional step <build>`:
-
-  - on Linux::
-
-      sudo ldconfig
-
-  - on FreeBSD::
-
-      sudo ldconfig -m
-
-To run examples:
-
-::
+To run examples::
 
     # trivial producer app
     ./build/examples/producer
@@ -224,16 +204,14 @@
     ./build/examples/consumer-with-timer
 
 If you want to test out a sample application, just create a ``.cpp`` file in ``examples/``
-folder and it will be compiled on the next run on ``./waf``.  For example:
-
-::
+folder and it will be compiled on the next run on ``./waf``.  For example::
 
     cp examples/consumer.cpp examples/my-new-consumer-app.cpp
     ./waf
     sudo ./waf install
+    sudo ldconfig # (on Linux only)
     ./build/examples/my-new-consumer-app
 
-
 Debug symbols
 ~~~~~~~~~~~~~
 
@@ -241,31 +219,18 @@
 flag for ``./waf configure`` and ``-g3`` for ``./waf configure --debug``).  This
 potentially allows more meaningful debugging information if your application crashes.
 
-If it is undesirable, default flags can be easily overridden:
-
-::
+The default build flags can easily be overridden::
 
     CXXFLAGS="-O2" ./waf configure --prefix=/usr --sysconfdir=/etc
     ./waf
     sudo ./waf install
 
-:ref:`Additional step <build>`:
-
-  - on Linux::
-
-      sudo ldconfig
-
-  - on FreeBSD::
-
-      sudo ldconfig -m
 
 Documentation
 -------------
 
 ndn-cxx tutorials and API documentation can be built using the following
-commands:
-
-::
+commands::
 
     # Full set of documentation (tutorials + API) in build/docs
     ./waf docs
@@ -286,44 +251,31 @@
 
 For more details, refer to ``./waf --help``.
 
-Development Build
+
+Development build
 -----------------
 
-The following is the suggested configure commands for development build.
-
-::
+The following is the suggested configure command for development builds::
 
     ./waf configure --debug --with-tests
     ./waf
     sudo ./waf install
+    sudo ldconfig # (on Linux only)
 
-:ref:`Additional step <build>`:
-
-  - on Linux::
-
-      sudo ldconfig
-
-  - on FreeBSD::
-
-      sudo ldconfig -m
-
-In the development build all compiler optimizations are disabled by
-default and all warnings are treated as error. The default behavior can
+In the development build most compiler optimizations are disabled by
+default and all warnings are treated as errors. The default behavior can
 be overridden by setting ``CXXFLAGS`` environment variable before
-running ``./waf configure``:
-
-::
+running ``./waf configure``::
 
     CXXFLAGS="-O1 -g3" ./waf configure --debug --with-tests
     ...
 
-Customize Compiler
-------------------
 
-To choose a custom C++ compiler for building ndn-cxx, set ``CXX`` environment
+Customizing the compiler
+------------------------
+
+To choose a custom C++ compiler for building ndn-cxx, set the ``CXX`` environment
 variable to point to the compiler binary. For example, to build with clang on
-Linux, use the following:
-
-::
+Linux, use the following::
 
     CXX=clang++ ./waf configure
diff --git a/docs/manpages/ndn-client.conf.rst b/docs/manpages/ndn-client.conf.rst
index d267c14..62f42ca 100644
--- a/docs/manpages/ndn-client.conf.rst
+++ b/docs/manpages/ndn-client.conf.rst
@@ -5,8 +5,8 @@
 
 The configuration file ``client.conf`` is looked up in several directories in the following order:
 
-- ``$HOME/.ndn/``: user-specific settings
-- ``@SYSCONFDIR@/ndn/`` (``/usr/local/etc/ndn``, ``/opt/local/etc/ndn``, or other, depending how the
+- ``$HOME/.ndn``: user-specific settings
+- ``@SYSCONFDIR@/ndn`` (``/usr/local/etc/ndn``, ``/opt/local/etc/ndn``, or other, depending how the
   library is configured): system-wide settings
 - ``/etc/ndn``: default system-wide settings
 
@@ -24,9 +24,10 @@
 
   By default, ``unix:///var/run/nfd.sock`` is used.
 
-  ..note::
+  .. note::
     This value can be overridden using the ``NDN_CLIENT_TRANSPORT`` environment variable.
 
+
 Key Management
 --------------
 
@@ -55,10 +56,10 @@
 
       rm -rf ~/.ndn/ndnsec-*
 
-  It's not recommended to share the same directory between machines, e.g. via NFS.
+  It is not recommended to share the same directory between machines, e.g. via NFS.
   Simultaneous access from multiple machines may cause errors.
 
-  ..note::
+  .. note::
     This value can be overridden using the ``NDN_CLIENT_PIB`` environment variable.
 
 tpm
@@ -69,15 +70,15 @@
 
   Possible values for ``[scheme]``:
 
-  * ``tpm-osx-keychain`` (default on OS X platform): secure storage of private keys in OS X
+  * ``tpm-osx-keychain`` (default on macOS): secure storage of private keys in the macOS
     Keychain with OS-provided access restrictions.
 
     ``[location]`` parameter is ignored.
 
-    May not work for daemon applications, as user interaction may be required to access OS X
-    Keychain.
+    May not work for daemon applications, as user interaction may be required to access the
+    macOS Keychain.
 
-  * ``tpm-file`` (default on all other platforms): file-based storage of private keys
+  * ``tpm-file`` (default on all other platforms): file-based storage of private keys.
 
     Possible values for ``[location]``:
 
@@ -90,11 +91,11 @@
 
      tpm=tpm-file
 
-  **Change of ``tpm`` setting is only possible together with ``pib`` setting. Otherwise, an
-  error will be generated during PIB/TPM access**
+  **Changing the ``tpm`` setting is only possible together with ``pib`` setting. Otherwise,
+  an error will be generated during PIB/TPM access.**
 
-  It's not recommended to share the same directory between machines, e.g. via NFS.
+  It is not recommended to share the same directory between machines, e.g. via NFS.
   Simultaneous access from multiple machines may cause errors.
 
-  ..note::
+  .. note::
     This value can be overridden using the ``NDN_CLIENT_TPM`` environment variable.