documentation rebuild

git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1830489 13f79535-47bb-0310-9956-ffa450edef68

docs/manual/howto/http2.html.en

@@ -41,6 +41,7 @@
 <li><img alt="" src="../images/down.gif" /> <a href="#clients">Clients</a></li>
 <li><img alt="" src="../images/down.gif" /> <a href="#tools">Useful tools to debug HTTP/2</a></li>
 <li><img alt="" src="../images/down.gif" /> <a href="#push">Server Push</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#earlyhints">Early Hints</a></li>
 </ul><h3>See also</h3><ul class="seealso"><li><a href="../mod/mod_http2.html">mod_http2</a></li><li><a href="#comments_section">Comments</a></li></ul></div>
 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 <div class="section">
@@ -261,6 +262,48 @@
     is the <a href="https://tools.ietf.org/html/draft-ruellan-http-accept-push-policy-00">
     Accept-Push-Policy Header Field</a> where a client can, for each request, define
     what kind of PUSHes it accepts.</p>
+    <p>
+    PUSH might not always trigger the request/response/performance that one expects or 
+    hopes for. There are various studies on this topic to be found on the web that explain
+    benefits and weaknesses and how different features of client and network influence
+    the outcome. For example: just because the server PUSHes a resource does not mean
+    a browser will actually use the data.</p>
+    <p>The major thing that influences the response being PUSHed is the request that was
+    simulated. The request URL for a PUSH is given by the application, but where do the
+    request headers come from? For example, will the PUSH request a <code>accept-language</code>
+    header and if yes with what value?</p>
+    <p>Apache will look at the original request (the one that triggered the PUSH) and copy the 
+    following headers over to PUSH requests: <code>user-agent</code>, <code>accept</code>, 
+    <code>accept-encoding</code>, <code>accept-language</code>, <code>cache-control</code>.</p>
+    <p>All other headers are ignored. Cookies will also not be copied over. PUSHing resources
+    that require a cookie to be present will not work. This can be a matter of debate. But 
+    unless this is more clearly discussed with browser, let's err on the side of caution and
+    not expose cookie where they might oridinarily not be visible.</p>
+  </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="earlyhints" id="earlyhints">Early Hints</a><a title="Permanent link" href="#earlyhints" class="permalink">&para;</a></h2>
+    
+    <p>An alternative to PUSHing resources is to send <code>Link</code> headers to the
+    client before the response is even ready. This uses the HTTP feature called "Early Hints" and
+    is described in <a href="https://tools.ietf.org/html/rfc8297">RFC 8297</a>.</p>
+    <p>In order to use this, you need to explicitly enable it on the server via</p>
+    <pre class="prettyprint lang-config">H2EarlyHints on</pre>
+
+    <p>(It is not enabled by default since some older browser tripped on such responses.)</p>
+    <p>If this feature is on, you can the directive <code>H2PushResource</code> to 
+    trigger early hints and resource PUSHes:</p>
+    <pre class="prettyprint lang-config">&lt;Location /xxx.html&gt;
+    H2PushResource /xxx.css
+    H2PushResource /xxx.js
+&lt;/Location&gt;</pre>
+
+    <p>This will send out a <code>"103 Early Hints"</code> response to a client as soon
+    as the server <em>starts</em> processing the request. This may be much early than
+    the time the first response headers have been determined, depending on your web
+    application.</p>
+    <p>If <code>H2Push</code> is enabled, this will also start the PUSH right after the
+    103 response. If <code>H2Push</code> is disabled however, the 103 response will be send
+    nevertheless to the client.</p>
   </div></div>
 <div class="bottomlang">
 <p><span>Available Languages: </span><a href="../en/howto/http2.html" title="English">&nbsp;en&nbsp;</a> |

docs/manual/howto/http2.xml.es

@@ -1,7 +1,7 @@
 <?xml version='1.0' encoding='UTF-8' ?>
 <!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
 <?xml-stylesheet type="text/xsl" href="../style/manual.es.xsl"?>
-<!-- English Revision: 1779744 -->
+<!-- English Revision: 1779744:1830439 (outdated) -->
 <!-- Spanish translation : Daniel Ferradal -->
 <!-- Reviewed & updated by Luis Gil de Bernabé Pfeiffer lgilbernabe[AT]apache.org -->
 

docs/manual/howto/http2.xml.fr

@@ -1,7 +1,7 @@
 <?xml version='1.0' encoding='UTF-8' ?>
 <!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
 <?xml-stylesheet type="text/xsl" href="../style/manual.fr.xsl"?>
-<!-- English Revision: 1779744 -->
+<!-- English Revision: 1779744:1830439 (outdated) -->
 <!-- French translation : Lucien GENTIS -->
 <!-- Reviewed by : Vincent Deffontaines -->
 

docs/manual/howto/http2.xml.meta

@@ -8,7 +8,7 @@
 
   <variants>
     <variant>en</variant>
-    <variant>es</variant>
+    <variant outdated="yes">es</variant>
-    <variant>fr</variant>
+    <variant outdated="yes">fr</variant>
   </variants>
 </metafile>

docs/manual/mod/mod_proxy_http2.html.en

@@ -51,7 +51,7 @@
     to the same backend are sent over a single TCP connection
     whenever possible (namely when the connection can be re-used).</p>
 
-    <p>Caveat: there will be no attemp to consolidate multiple HTTP/1.1 
+    <p>Caveat: there will be no attempt to consolidate multiple HTTP/1.1 
     frontend requests (configured to be proxied to the same backend)
     into HTTP/2 streams belonging to the same HTTP/2 request.
     Each HTTP/1.1 frontend request will be proxied to the backend using
@@ -78,6 +78,7 @@
 <ul id="topics">
 <li><img alt="" src="../images/down.gif" /> <a href="#examples">Basic Examples</a></li>
 <li><img alt="" src="../images/down.gif" /> <a href="#notes">Request notes</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#h2push">HTTP/2 PUSH</a></li>
 </ul><h3 class="directives">Directives</h3>
 <p>This module provides no
             directives.</p>
@@ -123,6 +124,19 @@ ProxyPassReverse "/app" "http://app.example.com"</pre>
         <dt>proxy-status</dt>
         <dd>The HTTP/2 status received from the backend server.</dd>
     </dl>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="h2push" id="h2push">HTTP/2 PUSH</a><a title="Permanent link" href="#h2push" class="permalink">&para;</a></h2>
+    <p>The module does not support the HTTP/2 feature PUSH. Backend servers
+    that would like to advertise preload resources should send the appropriate 
+    <code>Link</code> headers.</p>
+    <p>If available, they may do so using the <code>"103 Early Hints"</code> 
+    intermediate responses as specified in 
+    <a href="https://tools.ietf.org/html/rfc8297">RFC 8297</a>. This will give
+    the best performance. If the client is talking HTTP/2 as well, this may
+    then result in a PUSH from Apache to the client or just in forwarding
+    the 103 response.</p>
+    
 </div>
 </div>
 <div class="bottomlang">

docs/manual/mod/mod_proxy_http2.xml.fr

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
 <?xml-stylesheet type="text/xsl" href="../style/manual.fr.xsl"?>
-<!-- English Revision : 1783722 -->
+<!-- English Revision: 1783722:1830443 (outdated) -->
 <!-- French translation : Lucien GENTIS -->
 <!-- $LastChangedRevision: 2017022501 $ -->
 

docs/manual/mod/mod_proxy_http2.xml.meta

@@ -8,6 +8,6 @@
 
   <variants>
     <variant>en</variant>
-    <variant>fr</variant>
+    <variant outdated="yes">fr</variant>
   </variants>
 </metafile>