better wording

3 files changed, 33 insertions, 34 deletions

diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst
index c40f1181a..b43ebb93e 100644
--- a/docs/narr/viewconfig.rst
+++ b/docs/narr/viewconfig.rst
@@ -391,7 +391,7 @@ configured view.
   the ``REQUEST_METHOD`` of the :term:`WSGI` environment.
 
 ``request_param``
-  This value can be any string or a sequence of strings.  A view declaration
+  This argument can be any string or a sequence of strings.  A view declaration
   with this argument ensures that the view will only be called when the
   :term:`request` has a key in the ``request.params`` dictionary (an HTTP
   ``GET`` or ``POST`` variable) that has a name which matches the supplied
@@ -406,7 +406,7 @@ configured view.
   consideration of keys and values in the ``request.params`` dictionary.
 
 ``match_param``
-  This param may be either a single string of the format "key=value" or a tuple
+  This argument may be either a single string of the format "key=value" or a tuple
   containing one or more of these strings.
 
   This argument ensures that the view will only be called when the
@@ -448,24 +448,23 @@ configured view.
   associated view callable.
 
 ``header``
-  This value matches one or more HTTP header names or header name/value pairs.
-
-  If ``header`` is specified, it must be a string or a sequence of strings,
-  each being a header name or a ``headername:headervalue`` pair.
-
-  If ``header`` is specified without a value (a bare header name only, e.g.,
-  ``If-Modified-Since``), the view will only be invoked if the HTTP header
-  exists with any value in the request.
-
-  If ``header`` is specified, and possesses a name/value pair (e.g.,
-  ``User-Agent:Mozilla/.*``), the view will only be invoked if the HTTP header
-  exists *and* the HTTP header matches the value requested.  When the
-  ``headervalue`` contains a ``:`` (colon), it will be considered a name/value
-  pair (e.g., ``User-Agent:Mozilla/.*`` or ``Host:localhost``).  The value
-  portion should be a regular expression.
-
-  Whether or not the value represents a header name or a header name/value
-  pair, the case of the header name is not significant.
+  This param matches one or more HTTP header names or header name/value pairs.
+  If specified, this param must be a string or a sequence of strings,
+  each string being a header name or a ``headername:headervalue`` pair.
+
+  - Each string specified as a bare header name without a value (for example
+    ``If-Modified-Since``) will match a request if it contains an HTTP header
+    with that same name.  The case of the name is not significant, and the
+    header may have any value in the request.
+
+  - Each string specified as a name/value pair (that is, if it contains a ``:``
+    (colon), like ``User-Agent:Mozilla/.*``) will match a request only if it
+    contains an HTTP header with the requested name (ignoring case, so
+    ``User-Agent`` or ``user-agent`` would both match), *and* the value of the
+    HTTP header matches the value requested (``Mozilla/.*`` in our example).
+    The value portion is interpreted as a regular expression.
+
+  The view will only be invoked if all strings are matching.
 
   If ``header`` is not specified, the composition, presence, or absence of HTTP
   headers is not taken into consideration when deciding whether or not to
diff --git a/src/pyramid/config/routes.py b/src/pyramid/config/routes.py
index 4896ce0ea..a12e18fa8 100644
--- a/src/pyramid/config/routes.py
+++ b/src/pyramid/config/routes.py
@@ -211,29 +211,29 @@ class RoutesConfiguratorMixin:
           dictionary (an HTTP ``GET`` or ``POST`` variable) that has a
           name which matches the supplied value.  If the value
           supplied as the argument has a ``=`` sign in it,
-          e.g. ``request_param="foo=123"``, then the key
-          (``foo``) must both exist in the ``request.params`` dictionary, and
+          e.g. ``request_param="foo=123"``, then both the key
+          (``foo``) must exist in the ``request.params`` dictionary, and
           the value must match the right hand side of the expression (``123``)
           for the route to "match" the current request.  If this predicate
           returns ``False``, route matching continues.
 
         header
 
-          This value can be a string or an iterable of strings for HTTP
-          header names.  The header names are determined as follow:
+          This argument can be a string or an iterable of strings for HTTP
+          headers.  The matching is determined as follow:
 
           - If a string does not contain a ``:`` (colon), it will be
-            considered to be the header name (e.g.  ``If-Modified-Since``).
+            considered to be the header name (example ``If-Modified-Since``).
             In this case, the header specified by the name must be present
             in the request for this string to match.  Case is not significant.
 
           - If a string contains a colon, it will be considered a
-            name/value pair (e.g. ``User-Agent:Mozilla/.*`` or
+            name/value pair (for example ``User-Agent:Mozilla/.*`` or
             ``Host:localhost``), where the value part is a regular
             expression.  The header specified by the name must be present
             in the request *and* the regular expression specified as the
-            value must match the header value.  Case is not significant for
-            the header name, but it is for the value.
+            value part must match the value of the request header.  Case is
+            not significant for the header name, but it is for the value.
 
           All strings must be matched for this predicate to return ``True``.
           If this predicate returns ``False``, route matching continues.
diff --git a/src/pyramid/config/views.py b/src/pyramid/config/views.py
index 170f8a028..a064ebd05 100644
--- a/src/pyramid/config/views.py
+++ b/src/pyramid/config/views.py
@@ -670,21 +670,21 @@ class ViewsConfiguratorMixin:
 
         header
 
-          This value can be a string or an iterable of strings for HTTP
-          header names.  The header names are determined as follow:
+          This argument can be a string or an iterable of strings for HTTP
+          headers.  The matching is determined as follow:
 
           - If a string does not contain a ``:`` (colon), it will be
-            considered to be the header name (e.g.  ``If-Modified-Since``).
+            considered to be a header name (example ``If-Modified-Since``).
             In this case, the header specified by the name must be present
             in the request for this string to match.  Case is not significant.
 
           - If a string contains a colon, it will be considered a
-            name/value pair (e.g. ``User-Agent:Mozilla/.*`` or
+            name/value pair (for example ``User-Agent:Mozilla/.*`` or
             ``Host:localhost``), where the value part is a regular
             expression.  The header specified by the name must be present
             in the request *and* the regular expression specified as the
-            value must match the header value.  Case is not significant for
-            the header name, but it is for the value.
+            value part must match the value of the request header.  Case is
+            not significant for the header name, but it is for the value.
 
           All strings must be matched for this predicate to return ``True``.
           If this predicate returns ``False``, view matching continues.