trafficserver git commit: TS-3831: Documentation update.

[am...@apache.org]

Repository: trafficserver
Updated Branches:
  refs/heads/master cc6233173 -> f65b867bd


TS-3831: Documentation update.


Project: http://git-wip-us.apache.org/repos/asf/trafficserver/repo
Commit: http://git-wip-us.apache.org/repos/asf/trafficserver/commit/f65b867b
Tree: http://git-wip-us.apache.org/repos/asf/trafficserver/tree/f65b867b
Diff: http://git-wip-us.apache.org/repos/asf/trafficserver/diff/f65b867b

Branch: refs/heads/master
Commit: f65b867bd0741ec1d370e429ac774e5930a56dfa
Parents: cc62331
Author: Alan M. Carroll <so...@yahoo-inc.com>
Authored: Tue Aug 11 11:00:16 2015 -0500
Committer: Alan M. Carroll <so...@yahoo-inc.com>
Committed: Tue Aug 11 11:01:58 2015 -0500

----------------------------------------------------------------------
 doc/admin/traffic-server-error-messages.en.rst  | 35 +++++++++++++++-----
 .../configuration/records.config.en.rst         | 13 ++++++--
 2 files changed, 38 insertions(+), 10 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/trafficserver/blob/f65b867b/doc/admin/traffic-server-error-messages.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/traffic-server-error-messages.en.rst b/doc/admin/traffic-server-error-messages.en.rst
index d26b85e..b15a491 100644
--- a/doc/admin/traffic-server-error-messages.en.rst
+++ b/doc/admin/traffic-server-error-messages.en.rst
@@ -136,21 +136,40 @@ Traffic Server Alarm Messages
    addresses. You must ``setuid root`` for the ``vip_config`` file in
    the Traffic Server ``bin`` directory.
 
+.. _body-factory:
+
 HTML Messages Sent to Clients
 =============================
 
-Traffic Server returns detailed error messages to browser clients when
-there are problems with the HTTP transactions requested by the browser.
-These Traffic Server response messages correspond to standard HTTP
-response codes, but provide more information. A list of the more
-frequently encountered HTTP response codes is provided in :ref:`standard-http-response-messages`.
-You can customize the Traffic Server response messages (typically in
-``proxy/config/body_factory/default/``, but set by
-:ts:cv:`proxy.config.body_factory.template_sets_dir`).
+Traffic Server returns detailed error messages to client browsers when there are
+problems with the HTTP transactions requested by the browser. These Traffic
+Server response messages correspond to standard HTTP response codes, but provide
+more information. A list of the more frequently encountered HTTP response codes
+is provided in :ref:`standard-http-response-messages`.
+
+The error messages can be customized. The actual response is generated from a template. These
+templates are stored in files which means the errors responses can be customized by modifying these
+files. The default directory for the template files is ``PREFIX/body_factory/default``
+but this can be changed by the configuration variable
+:ts:cv:`proxy.config.body_factory.template_sets_dir`. All files in this directory are added to a
+lookup table which is consulted when the error message is generated. The name used for lookup is by
+default that listed in the :ref:`following table <body-factory-error-table>`. It can be overridden by
+:ts:cv:`proxy.config.body_factory.template_base` which, if set, is a string that is prepended to the
+search name along with an underscore. For example, if the default lookup name is
+``cache#read_error`` then by default the response will be generated from the template in the file
+named ``cache#read_error``. If the template base name were set to "apache" then the lookup would
+look for a file named ``apache_cache#read_error`` in the template table. This can be used to switch
+out error message sets or, because this variable is overridable, to select an error message set
+based on data in the transaction.
+
+The text for an error message is processed as if it were a :ref:`custom logging format <custom-logging-fields>` which
+enables customization by values present in the transaction for which the error occurred.
 
 The following table lists the hard-coded Traffic Server HTTP messages,
 with corresponding HTTP response codes and customizable files.
 
+.. _body-factory-error-table:
+
 ``Access Denied``
    ``403``
    You are not allowed to access the document at location ``URL``.

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/f65b867b/doc/reference/configuration/records.config.en.rst
----------------------------------------------------------------------
diff --git a/doc/reference/configuration/records.config.en.rst b/doc/reference/configuration/records.config.en.rst
index 257e070..c34a7e8 100644
--- a/doc/reference/configuration/records.config.en.rst
+++ b/doc/reference/configuration/records.config.en.rst
@@ -379,6 +379,7 @@ Unless explicitly specified in `proxy.config.http.server_ports`_ the server port
    :reloadable:
 
    When we trigger a throttling scenario, this how long our accept() are delayed.
+
 Cluster
 =======
 
@@ -1678,7 +1679,7 @@ all the different user-agent versions of documents it encounters.
 
    -  ``0`` = default, disable cache and goto origin server
    -  ``1`` = return a 502 error on a cache miss
-   -  ``2`` = serve stale if object's age is under :ref:`proxy.config.http.cache.max_stale_age`, else, goto origin server
+   -  ``2`` = serve stale if object's age is under :ts:cv:`proxy.config.http.cache.max_stale_age`, else, goto origin server
 
 Customizable User Response Pages
 ================================
@@ -1703,6 +1704,14 @@ Customizable User Response Pages
    relative path, Traffic Server resolves it relative to the
    ``PREFIX`` directory.
 
+.. ts:cv:: CONFIG proxy.config.body_factory.template_base STRING ""
+    :reloadable:
+    :overridable:
+
+    A prefix for the file name to use to find an error template file. If set (not the empty string)
+    this value and an underscore are predended to the file name to find in the template sets
+    directory. See :ref:`body-factory`.
+
 .. ts:cv:: CONFIG proxy.config.body_factory.response_suppression_mode INT 0
 
    Specifies when Traffic Server suppresses generated response pages:
@@ -2062,7 +2071,7 @@ Logging Configuration
     - ``log_name`` STRING [format]
         The filename (ex. :ref:`squid log <log-formats-squid-format>`).
 
-    - ``log_header_ STRING NULL
+    - ``log_header`` STRING NULL
         The file header text (ex. :ref:`squid log <log-formats-squid-format>`).
 
     The format can be either ``squid`` (Squid Format), ``common`` (Netscape Common),  ``extended`` (Netscape Extended),