From 92f829c8df4de95ed1833ef24f0cb1d9265685c6 Mon Sep 17 00:00:00 2001
From: Luca Toscano <elukey@apache.org>
Date: Sat, 3 Mar 2018 07:53:40 +0000
Subject: [PATCH] Documentation rebuild

git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1825758 13f79535-47bb-0310-9956-ffa450edef68
---
 docs/manual/mod/core.html.en            | 16 ++---
 docs/manual/mod/core.xml.de             |  2 +-
 docs/manual/mod/core.xml.es             |  2 +-
 docs/manual/mod/core.xml.fr             |  2 +-
 docs/manual/mod/core.xml.ja             |  2 +-
 docs/manual/mod/core.xml.meta           |  2 +-
 docs/manual/mod/core.xml.tr             |  2 +-
 docs/manual/mod/mod_proxy_html.html.en  | 81 +++++++++++++++++++++++--
 docs/manual/mod/mod_proxy_html.xml.fr   |  2 +-
 docs/manual/mod/mod_proxy_html.xml.meta |  2 +-
 docs/manual/mod/mod_remoteip.html.en    |  4 +-
 docs/manual/mod/mod_remoteip.xml.fr     |  2 +-
 docs/manual/mod/mod_remoteip.xml.meta   |  2 +-
 13 files changed, 95 insertions(+), 26 deletions(-)

diff --git a/docs/manual/mod/core.html.en b/docs/manual/mod/core.html.en
index 7398f6c590..8aa7c089f2 100644
--- a/docs/manual/mod/core.html.en
+++ b/docs/manual/mod/core.html.en
@@ -4973,27 +4973,27 @@ port</td></tr>
     <p>The ordering of the lookup when the physical port is used is as
     follows:</p>
      <dl>
-     <dt><code>UseCanonicalName On</code></dt>
+     <dt><code>UseCanonicalName Off | DNS</code></dt>
      <dd>
      <ol>
+      <li>Parsed port from <code>Host:</code> header</li>
+      <li>Physical port (only with <code class="directive">UseCanonicalPhysicalPort</code> ON)</li>
       <li>Port provided in <code class="directive"><a href="#servername">Servername</a></code></li>
-      <li>Physical port</li>
       <li>Default port</li>
      </ol>
      </dd>
-     <dt><code>UseCanonicalName Off | DNS</code></dt>
+     <dt><code>UseCanonicalName On</code></dt>
      <dd>
      <ol>
-      <li>Parsed port from <code>Host:</code> header</li>
-      <li>Physical port</li>
       <li>Port provided in <code class="directive"><a href="#servername">Servername</a></code></li>
+      <li>Physical port (only with <code class="directive">UseCanonicalPhysicalPort</code> ON)</li>
       <li>Default port</li>
      </ol>
      </dd>
-     </dl>
+    </dl>
 
-    <p>With <code>UseCanonicalPhysicalPort Off</code>, the
-    physical ports are removed from the ordering.</p>
+    <p>Only with <code>UseCanonicalPhysicalPort On</code>, the
+    physical ports are included in the search.</p>
     </div>
 
 
diff --git a/docs/manual/mod/core.xml.de b/docs/manual/mod/core.xml.de
index 25f7dc9946..41fba54618 100644
--- a/docs/manual/mod/core.xml.de
+++ b/docs/manual/mod/core.xml.de
@@ -1,7 +1,7 @@
 <?xml version="1.0"?>
 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
 <?xml-stylesheet type="text/xsl" href="../style/manual.de.xsl"?>
-<!-- English Revision: 344972:1824076 (outdated) -->
+<!-- English Revision: 344972:1825742 (outdated) -->
 
 <!--
  Licensed to the Apache Software Foundation (ASF) under one or more
diff --git a/docs/manual/mod/core.xml.es b/docs/manual/mod/core.xml.es
index b2fb22c2f8..2f85d52712 100644
--- a/docs/manual/mod/core.xml.es
+++ b/docs/manual/mod/core.xml.es
@@ -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.es.xsl"?>
-<!-- English Revision: 1741251:1824076 (outdated) -->
+<!-- English Revision: 1741251:1825742 (outdated) -->
 <!-- Translated by Luis Gil de Bernabé Pfeiffer lgilbernabe[AT]apache.org -->
 <!-- Reviewed by Sergio Ramos-->
 <!--
diff --git a/docs/manual/mod/core.xml.fr b/docs/manual/mod/core.xml.fr
index 23958c892d..3b35552f3f 100644
--- a/docs/manual/mod/core.xml.fr
+++ b/docs/manual/mod/core.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: 1824076 -->
+<!-- English Revision: 1824076:1825742 (outdated) -->
 <!-- French translation : Lucien GENTIS -->
 <!-- Reviewed by : Vincent Deffontaines -->
 
diff --git a/docs/manual/mod/core.xml.ja b/docs/manual/mod/core.xml.ja
index 6a698ae0cc..6c79159251 100644
--- a/docs/manual/mod/core.xml.ja
+++ b/docs/manual/mod/core.xml.ja
@@ -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.ja.xsl"?>
-<!-- English Revision: 669847:1824076 (outdated) -->
+<!-- English Revision: 669847:1825742 (outdated) -->
 
 <!--
  Licensed to the Apache Software Foundation (ASF) under one or more
diff --git a/docs/manual/mod/core.xml.meta b/docs/manual/mod/core.xml.meta
index e78755527a..b9d96ee4c5 100644
--- a/docs/manual/mod/core.xml.meta
+++ b/docs/manual/mod/core.xml.meta
@@ -10,7 +10,7 @@
     <variant outdated="yes">de</variant>
     <variant>en</variant>
     <variant outdated="yes">es</variant>
-    <variant>fr</variant>
+    <variant outdated="yes">fr</variant>
     <variant outdated="yes">ja</variant>
     <variant outdated="yes">tr</variant>
   </variants>
diff --git a/docs/manual/mod/core.xml.tr b/docs/manual/mod/core.xml.tr
index daa3424ee3..e6dae665fe 100644
--- a/docs/manual/mod/core.xml.tr
+++ b/docs/manual/mod/core.xml.tr
@@ -1,7 +1,7 @@
 <?xml version="1.0"?>
 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
 <?xml-stylesheet type="text/xsl" href="../style/manual.tr.xsl"?>
-<!-- English Revision: 1302855:1824076 (outdated) -->
+<!-- English Revision: 1302855:1825742 (outdated) -->
 <!-- =====================================================
  Translated by: Nilgün Belma Bugüner <nilgun belgeler.org>
    Reviewed by: Orhan Berent <berent belgeler.org>
diff --git a/docs/manual/mod/mod_proxy_html.html.en b/docs/manual/mod/mod_proxy_html.html.en
index 815c4234a0..be4efaa967 100644
--- a/docs/manual/mod/mod_proxy_html.html.en
+++ b/docs/manual/mod/mod_proxy_html.html.en
@@ -53,11 +53,13 @@ rewritten to work through the gateway. mod_proxy_html serves to rewrite
 <code>&lt;a href="http://appserver.example.com/foo/bar.html"&gt;foobar&lt;/a&gt;</code> to
 <code>&lt;a href="http://www.example.com/appserver/foo/bar.html"&gt;foobar&lt;/a&gt;</code>
 making it accessible from outside.</p>
-
-<p>mod_proxy_html was originally developed at WebÞing, whose
-extensive <a href="http://apache.webthing.com/mod_proxy_html/">documentation</a> may be useful to users.</p>
 </div>
-<div id="quickview"><h3 class="directives">Directives</h3>
+<div id="quickview"><h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#intro">Introduction</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#custom">Customised HTML Parsing</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#i18n">Internationalisation</a></li>
+</ul><h3 class="directives">Directives</h3>
 <ul id="toc">
 <li><img alt="" src="../images/down.gif" /> <a href="#proxyhtmlbufsize">ProxyHTMLBufSize</a></li>
 <li><img alt="" src="../images/down.gif" /> <a href="#proxyhtmlcharsetout">ProxyHTMLCharsetOut</a></li>
@@ -75,7 +77,71 @@ extensive <a href="http://apache.webthing.com/mod_proxy_html/">documentation</a>
 <h3>Bugfix checklist</h3><ul class="seealso"><li><a href="https://www.apache.org/dist/httpd/CHANGES_2.4">httpd changelog</a></li><li><a href="https://bz.apache.org/bugzilla/buglist.cgi?bug_status=__open__&amp;list_id=144532&amp;product=Apache%20httpd-2&amp;query_format=specific&amp;order=changeddate%20DESC%2Cpriority%2Cbug_severity&amp;component=mod_proxy_html">Known issues</a></li><li><a href="https://bz.apache.org/bugzilla/enter_bug.cgi?product=Apache%20httpd-2&amp;component=mod_proxy_html">Report a bug</a></li></ul><h3>See also</h3>
 <ul class="seealso">
 <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">
+<h2><a name="intro" id="intro">Introduction</a></h2>
+<p>mod_proxy_html was originally a third-party module for Apache HTTPD
+2.0.x and later versions.  It was donated to the ASF in 2011 along with
+<code class="module"><a href="../mod/mod_xml2enc.html">mod_xml2enc</a></code> (see <a href="#i18n">Internationalisation</a>)
+and is a standard module in HTTPD 2.4 and development versions.</p>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="custom" id="custom">Customised HTML Parsing</a></h2>
+<p>Internally, mod_proxy_html uses the HTMLParser module from the
+third-party <a href="http://xmlsoft.org/">libxml2</a> library.
+Unlike other libxml2 parsers, HTMLParser deals with HTML without
+requiring it to be well-formed XML. In particular, it understands
+about implied tags - like a closing &lt;/p&gt; - and inserts them
+into the stream of SAX events used by mod_proxy_html.  It also has
+explicit knowledge of W3C standards HTML 4 and XHTML 1, and can
+correct certain errors in them.</p>
+<p>mod_proxy_html offers a range of options to control HTML parsing.
+Error correction can be enabled (to your choice of HTML standard)
+or disabled using <code class="directive">ProxyHTMLDocType</code>.
+And in response to popular demand, it can be configured
+to treat non-standard elements and attributes as links that may
+need rewriting, and to rewrite links in embedded non-HTML contents
+(stylesheets and scripts).  Note that it is not suitable for external
+stylesheets or scripts: for those you should use another parser such as
+<code class="module"><a href="../mod/mod_substitute.html">mod_substitute</a></code> or <code class="module"><a href="../mod/mod_sed.html">mod_sed</a></code>.
+The main customisation directives are <code class="directive">ProxyHTMLLinks</code>
+and <code class="directive">ProxyHTMLEvents</code>.  By default these are set in 
+configuration file <var>proxy-html.conf</var>, which also contains
+comments to help you customise your parser if required.</p>
+<div class="note">For historical reasons, configuring mod_proxy_html to rewrite
+URLs in scripting events does not by default rewrite URLs in stylesheets.
+This can be changed by uncommenting the relevant line in
+<var>proxy-html.conf</var> as documented there.</div>
+
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="i18n" id="i18n">Internationalisation</a></h2>
+<p>Internally, mod_proxy_html uses a smart HTML parser from the
+third-party <a href="http://xmlsoft.org/">libxml2</a> library.
+The parser uses Unicode (utf-8) internally.  This makes it a
+somewhat-complex task to handle other encodings required to process
+many non-English-language websites.  If this is not handled correctly,
+websites that display non-ASCII characters in encodings other than
+utf-8 (Unicode) will display incorrectly.</p>
+<p>From the first release in 2003 to the donation to Apache in 2011,
+internationalisation (i18n) support developed from near nothing to a
+sophisticated framework capable of applying rules from HTTP, HTML and XML
+to detect a document's encoding and handle it correctly.  However,
+this processing was common to mod_proxy_html and other modules using
+libxml2, so it made sense to move it to a separate module rather than
+maintain it in multiple places.  That module is <code class="module"><a href="../mod/mod_xml2enc.html">mod_xml2enc</a></code>,
+and must be loaded for i18n to work.</p>
+<p>The interaction of mod_proxy_html with mod_xml2enc is too complex to
+be configured using regular filter configuration, including
+<code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code> directives.  Thus while mod_proxy_html can
+still be configured using regular filter directives, this will not support
+i18n at all.  Instead, a new directive <code class="directive">ProxyHTMLEnable</code>
+has been introduced to configure both mod_proxy_html's filter and mod_xml2enc.
+It is recommended that you always use ProxyHTMLEnable even where i18n
+support is not required. <strong>Note that this is a change from earlier
+versions where filter directives were used to activate mod_proxy_html.</strong></p>
 
+</div>
 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 <div class="directive-section"><h2><a name="ProxyHTMLBufSize" id="ProxyHTMLBufSize">ProxyHTMLBufSize</a> <a name="proxyhtmlbufsize" id="proxyhtmlbufsize">Directive</a></h2>
 <table class="directive">
@@ -184,7 +250,7 @@ module for earlier 2.x versions.</td></tr>
 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy_html</td></tr>
 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Version 2.4 and later; available as a third-party
-for earlier 2.x versions</td></tr>
+module for earlier 2.x versions</td></tr>
 </table>
 <p>Specifies one or more attributes to treat as scripting events and
 apply <code class="directive"><a href="#proxyhtmlurlmap">ProxyHTMLURLMap</a></code>s to where enabled.
@@ -194,7 +260,10 @@ You can specify any number of attributes in one or more
 one scope so that one overrides the other, you'll need to specify a complete
 set in each of those scopes.</p>
 <p>A default configuration is supplied in <var>proxy-html.conf</var>
-and defines the events in standard HTML 4 and XHTML 1.</p>
+and defines the events in standard HTML 4 and XHTML 1.  This can be
+extended to apply to URLs embedded in CSS stylesheet attributes
+by adding the <var>style</var> attribute to ProxyHTMLEvents, although
+this is not enabled in the shipped default.</p>
 
 </div>
 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
diff --git a/docs/manual/mod/mod_proxy_html.xml.fr b/docs/manual/mod/mod_proxy_html.xml.fr
index 499833b50f..da992af2a2 100644
--- a/docs/manual/mod/mod_proxy_html.xml.fr
+++ b/docs/manual/mod/mod_proxy_html.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: 1813997 -->
+<!-- English Revision: 1813997:1825757 (outdated) -->
 <!-- French translation : Lucien GENTIS -->
 
 <!--
diff --git a/docs/manual/mod/mod_proxy_html.xml.meta b/docs/manual/mod/mod_proxy_html.xml.meta
index cd380113ea..6bfed94b35 100644
--- a/docs/manual/mod/mod_proxy_html.xml.meta
+++ b/docs/manual/mod/mod_proxy_html.xml.meta
@@ -8,6 +8,6 @@
 
   <variants>
     <variant>en</variant>
-    <variant>fr</variant>
+    <variant outdated="yes">fr</variant>
   </variants>
 </metafile>
diff --git a/docs/manual/mod/mod_remoteip.html.en b/docs/manual/mod/mod_remoteip.html.en
index 157d52d2ed..116969f7be 100644
--- a/docs/manual/mod/mod_remoteip.html.en
+++ b/docs/manual/mod/mod_remoteip.html.en
@@ -235,7 +235,7 @@ RemoteIPProxiesHeader X-Forwarded-By</pre>
 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_remoteip</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>RemoteIPProxyProtocol is only available in httpd 2.4.28 and newer</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>RemoteIPProxyProtocol is only available in httpd 2.4.31 and newer</td></tr>
 </table>
     <p>The <code class="directive">RemoteIPProxyProtocol</code> directive enables or 
     disables the reading and handling of the PROXY protocol connection header.
@@ -287,7 +287,7 @@ Listen 8080
 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_remoteip</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>RemoteIPProxyProtocolExceptions is only available in httpd 2.4.28 and newer</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>RemoteIPProxyProtocolExceptions is only available in httpd 2.4.31 and newer</td></tr>
 </table>
     <p>The <code class="directive">RemoteIPProxyProtocol</code> directive enables or
     disables the reading and handling of the PROXY protocol connection header.
diff --git a/docs/manual/mod/mod_remoteip.xml.fr b/docs/manual/mod/mod_remoteip.xml.fr
index aed2357082..53d1c29123 100644
--- a/docs/manual/mod/mod_remoteip.xml.fr
+++ b/docs/manual/mod/mod_remoteip.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: 1806985 -->
+<!-- English Revision: 1806985:1825467 (outdated) -->
 <!-- French translation : Lucien GENTIS -->
 <!-- Reviewed by : Vincent Deffontaines -->
 
diff --git a/docs/manual/mod/mod_remoteip.xml.meta b/docs/manual/mod/mod_remoteip.xml.meta
index 1a7c78a9f1..771852e80c 100644
--- a/docs/manual/mod/mod_remoteip.xml.meta
+++ b/docs/manual/mod/mod_remoteip.xml.meta
@@ -8,6 +8,6 @@
 
   <variants>
     <variant>en</variant>
-    <variant>fr</variant>
+    <variant outdated="yes">fr</variant>
   </variants>
 </metafile>
-- 
2.40.0