Improve the docs accuracy and language

diff --git a/README.rst b/README.rst
index 37bcefaf97b0df88dcf5e11e9206ee0367ed626c..28890ebd384aaa1920eae8717e1a7a6dd02e1eca 100644 (file)
--- a/README.rst
+++ b/README.rst
@@ -1,4 +1,4 @@
-.. Copyright (C) 2018 The Meme Factory, Inc.  http://www.meme.com/
+.. Copyright (C) 2018, 2019 The Meme Factory, Inc.  http://www.karlpinc.com/
 
 
    This file is part of PGWUI_Server.
@@ -17,7 +17,7 @@
    License along with this program.  If not, see
    <http://www.gnu.org/licenses/>.
 
-   Karl O. Pinc <kop@meme.com>
+   Karl O. Pinc <kop@karlpinc.com>
 
 .. #End Of Copyright Marker#
 
@@ -27,21 +27,28 @@ PGWUI_Server
 Short Documentation
 -------------------
 
-PGWUI_Server contains what's needed to put the PGWUI components on the
+PGWUI_Server contains what's needed to put PGWUI components on the
 web.  It should be installed by most PGWUI users.  The alternative to
 installing PGWUI_Server is writing your own `Pyramid`_ application.
 
 PGWUI_Server stands for `PostgreSQL`_ Web User Interface, Server support.
 
-PGWUI_Server contains a basic webserver for those who want something
-simple and stand-alone.  More advanced users may use PGWUI_Server's
-WSGI interface to connect to a more full-featured webserver such as
-Apache or Nginx.
+PGWUI web pages can be safely accessed by a browser running on the
+local machine by installing *waitress*, a simple `WSGI`_ webserver,
+alongside PGWUI_Server.  PGWUI_Server provides the `WSGI`_ interface
+which connects PGWUI's Python packages to any `WSGI`_ capable
+webserver.
 
-PGWUI_Server does not support HTTPS out-of-the-box.  It is designed to
-stand behind a reverse web proxy or an advanced WSGI web server which
-is expected to supply this functionality.  Nginx, Apache, and many
-other full-featured web servers are all suitable.
+Waitress is for those who want something simple and stand-alone.  More
+advanced users may take advantage of a more full-featured webserver
+such as Apache or Nginx.  Connections to PGWUI_Server can be direct,
+via WSGI, or via reverse proxy to waitress or similar.
+
+PGWUI_Server does not support HTTPS out-of-the-box.  HTTPS is often
+essential for security.  PGWUI_Server is designed to stand behind a
+reverse web proxy or an advanced WSGI web server which does support
+HTTPS.  Nginx, Apache, and many other full-featured web servers are
+all suitable HTTPS providers.
 
 PGWUI_Server supports configuration using a traditional *.ini* file.
 
@@ -77,20 +84,32 @@ Install into a Python 3 virtual environment with commands like::
 Startup and Usage
 -----------------
 
-Start the stand-alone webserver with::
+PGWUI_Server comes with an example configuration which connects it to
+the *waitress* `WSGI`_ webserver and configures waitress.  The
+simplest approach is to install and use waitress as the application's
+WSGI server.
+
+Waitress is not a requirement and is not automatically installed.  To
+use another WSGI capable webserver modify the appropriate sections of
+the supplied configuration file using the comments written into the
+file as a guide.
 
-  pgwui_venv/bin/pserve pgwui.ini
+Use *pserve* to start PGWUI and the stand-alone WSGI webserver you
+installed::
 
-PGWUI_Server comes with *waitress* configured as the webserver started
-by pserve, and a default waitress configuration.  The simplest approach
-is to install and use waitress as the applications WSGI server.
+  pgwui_venv/bin/pserve /etc/pgwui.ini
 
 The installation can then be accessed via URLs similar to::
 
   http://localhost:6543/logout
 
+Automating startup at boot time is OS dependent.
+
+Troubleshooting
+^^^^^^^^^^^^^^^
+
 Minimal error reporting is done on stderr to help diagnose startup
-failure.  Full error reporting is done via logging so when there are
+failure.  Full error reporting is done via logging.  When there are
 problems it is important to check the log and the logging
 configuration.
 
@@ -145,12 +164,12 @@ Replace the ``location / { ... }`` section appearing in the default
 `Nginx`_ documentation.
 
 It is beyond the scope of this document to describe how to use
-PGWUI_Server's WSGI support, or the nuances of reverse-proxy
+PGWUI_Server's WSGI support or the the nuances of reverse-proxy
 configuration.  Any WSGI web server can be used with PGWUI_Server, as
 can any reverse web-proxy.
 
 Again, ``pserve`` with ``waitress`` does not support HTTPS.  Consult your
-webserver's documentation for HTTPS support.
+webserver's HTTPS documentation.
 
 
 Configuration
@@ -324,3 +343,4 @@ provided by `The Dian Fossey Gorilla Fund
 .. _Nginx: https://www.nginx.org/
 .. _PostgreSQL: https://www.postgresql.org/
 .. _Pyramid: https://trypyramid.com/
+.. _WSGI: https://en.wikipedia.org/wiki/Web_Server_Gateway_Interface