From c8c7c80cf773d34b60a0069a0a1bef2169d2e68e Mon Sep 17 00:00:00 2001
From: Matt Klein <mklein@lyft.com>
Date: Mon, 30 Jan 2017 14:34:43 -0800
Subject: [PATCH] docs: misc fixes

fixes https://github.com/lyft/envoy/issues/385
fixes https://github.com/lyft/envoy/issues/310
---
 .../http_conn_man/route_config/route.rst            | 11 ++++++++---
 docs/intro/comparison.rst                           | 13 +++++++++++++
 2 files changed, 21 insertions(+), 3 deletions(-)

diff --git a/docs/configuration/http_conn_man/route_config/route.rst b/docs/configuration/http_conn_man/route_config/route.rst
index 9872b8cfb1fd6..ac79328053edf 100644
--- a/docs/configuration/http_conn_man/route_config/route.rst
+++ b/docs/configuration/http_conn_man/route_config/route.rst
@@ -46,7 +46,7 @@ cluster
 
 :ref:`weighted_clusters <config_http_conn_man_route_table_route_weighted_clusters>`
   *(sometimes required, string)* If the route is not a redirect (*host_redirect* and/or
-  *path_redirect* is not specified), one of *cluster* or *weighted_clusters* must be specified. 
+  *path_redirect* is not specified), one of *cluster* or *weighted_clusters* must be specified.
   With the *weighted_clusters* option, multiple upstream clusters can be specified for a given route.
   The request is forwarded to one of the upstream clusters based on weights assigned
   to each cluster. See :ref:`traffic splitting <config_http_conn_man_route_table_weighted_routing>`
@@ -227,6 +227,11 @@ The router will check the request's headers against all the specified
 headers in the route config. A match will happen if all the headers in the route are present in
 the request with the same values (or based on presence if the ``value`` field is not in the config).
 
+.. attention::
+
+  Internally, Envoy always uses the HTTP/2 *:authority* header to represent the HTTP/1 *Host*
+  header. Thus, if attempting to match on *Host*, match on *:authority* instead.
+
 .. _config_http_conn_man_route_table_route_weighted_clusters:
 
 Weighted Clusters
@@ -245,7 +250,7 @@ The router selects an upstream cluster based on the weights.
    }
 
 clusters
-  *(required, array)* Specifies one or more upstream clusters associated with the route. 
+  *(required, array)* Specifies one or more upstream clusters associated with the route.
 
   .. code-block:: json
 
@@ -266,7 +271,7 @@ clusters
 runtime_key_prefix
   *(optional, string)* Specifies the runtime key prefix that should be used to construct the runtime
   keys associated with each cluster. When the ``runtime_key_prefix`` is specified, the router will
-  look for weights associated with each upstream cluster under the key 
+  look for weights associated with each upstream cluster under the key
   ``runtime_key_prefix + "." + cluster[i].name`` where ``cluster[i]``  denotes an entry in the
   ``clusters`` array field. If the runtime key for the cluster does not exist, the value specified
   in the configuration file will be used as the default weight.
diff --git a/docs/intro/comparison.rst b/docs/intro/comparison.rst
index 139628a6ee7d0..7d98a454b6736 100644
--- a/docs/intro/comparison.rst
+++ b/docs/intro/comparison.rst
@@ -122,3 +122,16 @@ linkerd’s memory and CPU requirements are significantly higher than Envoy’s.
 linkerd provides a minimalist configuration language, and explicitly does not support hot reloads,
 relying instead on dynamic provisioning and service abstractions. linkerd supports HTTP/1.1, Thrift,
 ThriftMux, HTTP/2 (experimental) and gRPC (experimental).
+
+`nghttp2 <https://nghttp2.org/>`_
+---------------------------------
+
+nghttp2 is a project that contains a few different things. Primarily, it contains a library
+(nghttp2) that implements the HTTP/2 protocol. Envoy uses this library (with a very thin wrapper
+on top) for its HTTP/2 support. The project also contains a very useful load testing tool (h2load)
+as well as a reverse proxy (nghttpx). From a comparison perspective, Envoy is most similar to
+nghttpx. nghttpx is a transparent HTTP/1 <-> HTTP/2 reverse proxy, supports TLS termination,
+correctly supports gRPC proxying, among a variety of other features. With that said, we consider
+nghttpx to be an excellent example of a variety of proxy features, rather than a robust production
+ready solution. Envoy's focus is much more targeted towards observability, general operational
+agility, and advanced load balancing features.
