fix docs formatting

3 files changed, 120 insertions, 82 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index bf75b46..1056b47 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -4,7 +4,7 @@ Unreleased
 Features
 ~~~~~~~~
 
-- Waitress has increased it's support of the X-Forwarded-* headers and includes
+- Waitress has increased its support of the X-Forwarded-* headers and includes
   Forwarded (RFC7239) support. This may be used to allow proxy servers to
   influence the WSGI environment. See
   https://github.com/Pylons/waitress/pull/209
diff --git a/docs/arguments.rst b/docs/arguments.rst
index 7c94224..2665087 100644
--- a/docs/arguments.rst
+++ b/docs/arguments.rst
@@ -7,7 +7,7 @@ Here are the arguments you can pass to the `waitress.serve`` function or use
 in :term:`PasteDeploy` configuration (interchangeably):
 
 host
-    hostname or IP address (string) on which to listen, default ``0.0.0.0``,
+    Hostname or IP address (string) on which to listen, default ``0.0.0.0``,
     which means "all IP addresses on this host".
 
     .. warning::
@@ -20,19 +20,20 @@ port
         May not be used with ``listen``
 
 listen
-    .. versionadded:: 1.0
-        Tell waitress to listen on combinations of ``host:port`` arguments.
-        Combinations should be a quoted, space-delimited list, as in the following examples.
+    Tell waitress to listen on combinations of ``host:port`` arguments.
+    Combinations should be a quoted, space-delimited list, as in the following examples.
+
+    .. code-block:: python
 
-        .. code-block:: python
+        listen="127.0.0.1:8080 [::1]:8080"
+        listen="*:8080 *:6543"
 
-            listen="127.0.0.1:8080 [::1]:8080"
-            listen="*:8080 *:6543"
+    A wildcard for the hostname is also supported and will bind to both
+    IPv4/IPv6 depending on whether they are enabled or disabled.
 
-        A wildcard for the hostname is also supported and will bind to both
-        IPv4/IPv6 depending on whether they are enabled or disabled.
+    IPv6 IP addresses are supported by surrounding the IP address with brackets.
 
-        IPv6 IP addresses are supported by surrounding the IP address with brackets.
+    .. versionadded:: 1.0
 
 ipv4
     Enable or disable IPv4 (boolean)
@@ -41,75 +42,83 @@ ipv6
     Enable or disable IPv6 (boolean)
 
 unix_socket
-    Path of Unix socket (string), default is ``None``. If a socket path is
-    specified, a Unix domain socket is made instead of the usual inet domain
-    socket.
+    Path of Unix socket (string). If a socket path is specified, a Unix domain
+    socket is made instead of the usual inet domain socket.
 
     Not available on Windows.
 
+    Default: ``None``
+
 unix_socket_perms
-    Octal permissions to use for the Unix domain socket (string), default is
-    ``600``. Only used if ``unix_socket`` is not ``None``.
+    Octal permissions to use for the Unix domain socket (string).
+    Only used if ``unix_socket`` is not ``None``.
+
+    Default: ``'600'``
 
 sockets
+    A list of sockets. The sockets can be either Internet or UNIX sockets and have
+    to be bound. Internet and UNIX sockets cannot be mixed.
+    If the socket list is not empty, waitress creates one server for each socket.
+
+    Default: ``[]``
+
     .. versionadded:: 1.1.1
-        A list of sockets. The sockets can be either Internet or UNIX sockets and have
-        to be bound. Internet and UNIX sockets cannot be mixed.
-        If the socket list is not empty, waitress creates one server for each socket.
-        Default is ``[]``.
 
-        .. warning::
-            May not be used with ``listen``, ``host``, ``port`` or ``unix_socket``
+    .. warning::
+        May not be used with ``listen``, ``host``, ``port`` or ``unix_socket``
 
 threads
-    number of threads used to process application logic (integer), default
-    ``4``
+    The number of threads used to process application logic (integer).
+
+    Default: ``4``
 
 trusted_proxy
     IP address of a remote peer allowed to override various WSGI environment
     variables using proxy headers.
 
-    For unix sockets, set this value to ``localhost`` instead of an IP address
+    For unix sockets, set this value to ``localhost`` instead of an IP address.
 
-    default ``None``
+    Default: ``None``
 
 trusted_proxy_count
-    How many proxies we trust when chained
-    
-    X-Forwarded-For: 192.0.2.1, "[2001:db8::1]"
-    
+    How many proxies we trust when chained. For example,
+
+    ``X-Forwarded-For: 192.0.2.1, "[2001:db8::1]"``
+
     or
-   
-    Forwarded: for=192.0.2.1, For="[2001:db8::1]"
-    
+
+    ``Forwarded: for=192.0.2.1, For="[2001:db8::1]"``
+
     means there were (potentially), two proxies involved. If we know there is
     only 1 valid proxy, then that initial IP address "192.0.2.1" is not trusted
     and we completely ignore it.
-    
+
     If there are two trusted proxies in the path, this value should be set to
     2. If there are more proxies, this value should be set higher.
 
-    default ``1``
+    Default: ``1``
 
     .. versionadded:: 1.2.0
 
 trusted_proxy_headers
     Which of the proxy headers should we trust, this is a set where you
-    either specify forwarded or one or more of x-forwarded-host, x-forwarded-for,
-    x-forwarded-proto, x-forwarded-port.
+    either specify "forwarded" or one or more of "x-forwarded-host", "x-forwarded-for",
+    "x-forwarded-proto", "x-forwarded-port", "x-forwarded-by".
 
     This list of trusted headers is used when ``trusted_proxy`` is set and will
     allow waitress to modify the WSGI environment using the values provided by
     the proxy.
 
     .. versionadded:: 1.2.0
+
+    .. warning::
        If ``trusted_proxy`` is set, the default is ``x-forwarded-proto`` to
        match older versions of Waitress. Users should explicitly opt-in by
        selecting the headers to be trusted as future versions of waitress will
        use an empty default.
 
     .. warning::
-       It is an error to set this value without setting ``trusted_proxy``
+       It is an error to set this value without setting ``trusted_proxy``.
 
 log_untrusted_proxy_headers
     Should waitress log warning messages about proxy headers that are being
@@ -119,8 +128,8 @@ log_untrusted_proxy_headers
     This may be useful for debugging if you expect your upstream proxy server
     to only send specific headers.
 
-    default ``False``
-   
+    Default: ``False``
+
     .. versionadded:: 1.2.0
 
     .. warning::
@@ -130,11 +139,13 @@ log_untrusted_proxy_headers
 clear_untrusted_proxy_headers
    This tells Waitress to remove any untrusted proxy headers ("Forwarded",
    "X-Forwared-For", "X-Forwarded-By", "X-Forwarded-Host", "X-Forwarded-Port",
-   "X-Forwarded-Proto") not explicitly allowed by ``trusted_proxy_headers``
+   "X-Forwarded-Proto") not explicitly allowed by ``trusted_proxy_headers``.
 
-   default ``False``
+   Default: ``False``
 
-   .. versionadded: 1.2.0
+   .. versionadded:: 1.2.0
+
+   .. warning::
       The default value is set to ``False`` for backwards compatibility. In
       future versions of Waitress this default will be changed to ``True``.
       Warnings will be raised unless the user explicitly provides a value for
@@ -142,50 +153,60 @@ clear_untrusted_proxy_headers
       automatically.
 
    .. warning::
-      It is an error to set this value without setting ``trusted_proxy``
+      It is an error to set this value without setting ``trusted_proxy``.
 
 url_scheme
-    default ``wsgi.url_scheme`` value (string), default ``http``;  can be
+    The value of ``wsgi.url_scheme`` in the environ. This can be
     overridden per-request by the value of the ``X_FORWARDED_PROTO`` header,
     but only if the client address matches ``trusted_proxy``.
 
+    Default: ``http``
+
 ident
-    server identity (string) used in "Server:" header in responses, default
-    ``waitress``
+    Server identity (string) used in "Server:" header in responses.
+
+    Default: ``waitress``
 
 backlog
-    backlog is the value waitress passes to pass to socket.listen()
-    (integer), default ``1024``.  This is the maximum number of incoming TCP
+    The value waitress passes to pass to ``socket.listen()`` (integer).
+    This is the maximum number of incoming TCP
     connections that will wait in an OS queue for an available channel.  From
     listen(1): "If a connection request arrives when the queue is full, the
     client may receive an error with an indication of ECONNREFUSED or, if the
     underlying protocol supports retransmission, the request may be ignored
     so that a later reattempt at connection succeeds."
 
+    Default: ``1024``
+
 recv_bytes
-    recv_bytes is the argument waitress passes to socket.recv() (integer),
-    default ``8192``
+    The argument waitress passes to ``socket.recv()`` (integer).
+
+    Default: ``8192``
 
 send_bytes
-    send_bytes is the number of bytes to send to socket.send() (integer),
-    default ``18000``.  Multiples of 9000 should avoid partly-filled TCP
+    The number of bytes to send to ``socket.send()`` (integer).
+    Multiples of 9000 should avoid partly-filled TCP
     packets, but don't set this larger than the TCP write buffer size.  In
-    Linux, /proc/sys/net/ipv4/tcp_wmem controls the minimum, default, and
+    Linux, ``/proc/sys/net/ipv4/tcp_wmem`` controls the minimum, default, and
     maximum sizes of TCP write buffers.
 
+    Default: ``18000``
+
 outbuf_overflow
     A tempfile should be created if the pending output is larger than
-    outbuf_overflow, which is measured in bytes. The default is 1MB
-    (``1048576``).  This is conservative.
+    outbuf_overflow, which is measured in bytes. The default is conservative.
+
+    Default: ``1048576`` (1MB)
 
 inbuf_overflow
     A tempfile should be created if the pending input is larger than
-    inbuf_overflow, which is measured in bytes. The default is 512K
-    (``524288``).  This is conservative.
+    inbuf_overflow, which is measured in bytes. The default is conservative.
+
+    Default: ``524288`` (512K)
 
 connection_limit
     Stop creating new channels if too many are already active (integer).
-    Default is ``100``.  Each channel consumes at least one file descriptor,
+    Each channel consumes at least one file descriptor,
     and, depending on the input and output body sizes, potentially up to
     three, plus whatever file descriptors your application logic happens to
     open.  The default is conservative, but you may need to increase the
@@ -195,46 +216,62 @@ connection_limit
     connections that can be waiting for processing; the ``backlog`` argument
     controls that.
 
+    Default: ``100``
+
 cleanup_interval
-    Minimum seconds between cleaning up inactive channels (integer), default
-    ``30``.  See "channel_timeout".
+    Minimum seconds between cleaning up inactive channels (integer).
+    See also ``channel_timeout``.
+
+    Default: ``30``
 
 channel_timeout
-    Maximum seconds to leave an inactive connection open (integer), default
-    ``120``.  "Inactive" is defined as "has received no data from a client
+    Maximum seconds to leave an inactive connection open (integer).
+    "Inactive" is defined as "has received no data from a client
     and has sent no data to a client".
 
+    Default: ``120``
+
 log_socket_errors
-    Boolean: turn off to not log premature client disconnect tracebacks.
-    Default: ``True``.
+    Set to ``False`` to not log premature client disconnect tracebacks.
+
+    Default: ``True``
 
 max_request_header_size
-    maximum number of bytes of all request headers combined (integer), 256K
-    (``262144``) default)
+    Maximum number of bytes of all request headers combined (integer).
+
+    Default: ``262144`` (256K)
 
 max_request_body_size
-    maximum number of bytes in request body (integer), 1GB (``1073741824``)
-    default.
+    Maximum number of bytes in request body (integer).
+
+    Default: ``1073741824`` (1GB)
 
 expose_tracebacks
-    Boolean: expose tracebacks of unhandled exceptions to client.  Default:
-    ``False``.
+    Set to ``True`` to expose tracebacks of unhandled exceptions to client.
+
+    Default: ``False``
 
 asyncore_loop_timeout
+    The ``timeout`` value (seconds) passed to ``asyncore.loop`` to run the mainloop.
+
+    Default: ``1``
+
     .. versionadded:: 0.8.3
-        The ``timeout`` value (seconds) passed to ``asyncore.loop`` to run the mainloop.
-        Default: 1.
 
 asyncore_use_poll
+    Set to ``True`` to switch from using ``select()`` to ``poll()`` in ``asyncore.loop``.
+    By default ``asyncore.loop()`` uses ``select()`` which has a limit of 1024 file descriptors.
+    ``select()`` and ``poll()`` provide basically the same functionality, but ``poll()`` doesn't have the file descriptors limit.
+
+    Default: ``False``
+
     .. versionadded:: 0.8.6
-        Boolean: switch from using ``select()`` to ``poll()`` in ``asyncore.loop``.
-        By default ``asyncore.loop()`` uses ``select()`` which has a limit of 1024 file descriptors.
-        ``select()`` and ``poll()`` provide basically the same functionality, but ``poll()`` doesn't have the file descriptors limit.
-        Default: False.
 
 url_prefix
     String: the value used as the WSGI ``SCRIPT_NAME`` value.  Setting this to
     anything except the empty string will cause the WSGI ``SCRIPT_NAME`` value
     to be the value passed minus any trailing slashes you add, and it will
     cause the ``PATH_INFO`` of any request which is prefixed with this value to
-    be stripped of the prefix.  Default: the empty string.
+    be stripped of the prefix.
+
+    Default: ``''``
diff --git a/docs/reverse-proxy.rst b/docs/reverse-proxy.rst
index 42f8352..7081fda 100644
--- a/docs/reverse-proxy.rst
+++ b/docs/reverse-proxy.rst
@@ -77,7 +77,7 @@ when using Apache, ``mod_proxy`` automatically forwards the following headers::
    X-Forwarded-Host
    X-Forwarded-Server
 
-You will also want to add for Apache::
+You will also want to add to Apache::
 
    RequestHeader set X-Forwarded-Proto https
 
@@ -86,7 +86,8 @@ Configure waitress's ``trusted_proxy_headers`` as appropriate::
     trusted_proxy_headers = "x-forwarded-for, x-forwarded-host, x-forwarded-proto, x-forwarded-port"
 
 At this point waitress will set up the WSGI environment using the information
-sent in the proxy headers. This will setup the following variables::
+specified in the trusted proxy headers. This will setup the following
+variables::
 
    HTTP_HOST
    SERVER_NAME
@@ -107,8 +108,8 @@ To configure waitress to use the ``Forwarded`` header, set::
 
 .. note::
 
-   You must also configure the Waitress server's ``trusted_proxy`` and
-   to contain the IP address of the proxy
+   You must also configure the Waitress server's ``trusted_proxy`` to
+   contain the IP address of the proxy.
 
 
 Using ``url_prefix`` to influence ``SCRIPT_NAME`` and ``PATH_INFO``