[master] b130914 RFC2616_Ttl() in english

[Nils Goroll]

commit b130914d5607cdd118eb298d98e263bacb403d4e
Author: Nils Goroll <nils.goroll at uplex.de>
Date:   Tue Mar 6 17:42:26 2018 +0100

    RFC2616_Ttl() in english
    
    Feel free to improve further!

diff --git a/doc/sphinx/users-guide/vcl-built-in-subs.rst b/doc/sphinx/users-guide/vcl-built-in-subs.rst
index 47b183f..b9951c8 100644
--- a/doc/sphinx/users-guide/vcl-built-in-subs.rst
+++ b/doc/sphinx/users-guide/vcl-built-in-subs.rst
@@ -403,6 +403,52 @@ Note: Backend conditional requests are independent of client
 conditional requests, so clients may receive 304 responses no matter
 if a backend request was conditional.
 
+Before calling `vcl_backend_response`, core code sets ``beresp.ttl``
+based on the response status and the response headers ``Age``,
+``Cache-Control`` or ``Expires`` and ``Date`` as follows:
+
+* If present and valid, the value of the ``Age`` header is effectively
+  deduced from all ttl calculations.
+
+* For status codes 200, 203, 204, 300, 401, 304, 404, 410 and 414:
+
+  * If ``Cache-Control`` contains an ``s-maxage`` or ``max-age`` field
+    (in that order of preference), the ttl is set to the respective
+    non-negative value or 0 if negative.
+
+  * Otherwise, if no ``Expires`` header exists, the default ttl is
+    used.
+
+  * Otherwise, if ``Expires`` contains a time stamp before ``Date``,
+    the ttl is set to 0.
+
+  * Otherwise, if no ``Date`` header is present or the ``Date`` header
+    timestamp differs from the local clock by no more than the
+    `clock_skew` parameter, the ttl is set to
+
+    * 0 if ``Expires`` denotes a past timestamp or
+
+    * the difference between the local clock and the ``Expires``
+      header otherwise.
+
+  * Otherwise, the ttl is set to the difference between ``Expires``
+    and ``Date``
+
+* For status codes 302 and 307, the calculation is identical except
+  that the default ttl is not used and -1 is returned if neither
+  ``Cache-Control`` nor ``Expires`` exists.
+
+* For all other status codes, ttl -1 is returned.
+
+``beresp.grace`` defaults to the `default_grace` parameter.
+
+For a non-negative ttl, if ``Cache-Control`` contains a
+``stale-while-revalidate`` field value, ``beresp.grace`` is
+set to that value if non-negative or 0 otherwise.
+
+``beresp.keep`` defaults to the `default_keep` parameter.
+
+
 The `vcl_backend_response` subroutine may terminate with calling
 ``return()`` with one of the following keywords: