From: Yann Ylavic <ylavic@apache.org>
Date: Fri, 8 Sep 2017 14:14:41 +0000 (+0000)
Subject: Merge r1793922, r1793923 from trunk:
X-Git-Tag: 2.4.28~36
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=f524b965cc11c282b765ac461b265a8ee776d87d;p=apache

Merge r1793922, r1793923 from trunk:

Add an Override Class Index

This page pulls in directives that declare an <override> element and
groups them by class. The documentation for each class comes from
overrides.xml. Any undocumented classes are flagged with a boilerplate
fallback text (this situation is only likely to occur with a misspelling
or otherwise invalid <override> somewhere else in the documentation).

override index: clarify this doc's purpose

Based on feedback by elukey.
Submitted by: jchampion
Reviewed by: jchampion, jim, icing


git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/branches/2.4.x@1807765 13f79535-47bb-0310-9956-ffa450edef68
---

diff --git a/STATUS b/STATUS
index bf11b3b84f..7dfedc8a96 100644
--- a/STATUS
+++ b/STATUS
@@ -131,15 +131,6 @@ PATCHES ACCEPTED TO BACKPORT FROM TRUNK:
      2.4.x patch: http://home.apache.org/~jim/patches/httpd-2.4-hcheck-ms.patch
      +1: jim, covener, ylavic
 
-  *) docs: add an auto-generated Overrides class index.
-           (I know this is technically CTR, but the new machinery is a little
-           more complex than just a simple docs change. Make sure to svn-up your
-           docs-build directory.)
-     trunk patch: https://svn.apache.org/r1793922
-                  https://svn.apache.org/r1793923
-     2.4.x patch: svn merge -r1793921:HEAD ^/httpd/httpd/branches/trunk-override-index
-     +1: jchampion, jim, icing
-
   *) mod_proxy: Name the scheme in the error message when the 
      mod_proxy_foo submodule is missing.
      trunk patch: http://svn.apache.org/r1745039 
diff --git a/docs/manual/index.xml b/docs/manual/index.xml
index 3aee82fe08..de1fcbbc12 100644
--- a/docs/manual/index.xml
+++ b/docs/manual/index.xml
@@ -44,6 +44,7 @@ Documentation</title>
     <page href="filter.html">Filters</page>
     <page href="handler.html">Handlers</page>
     <page href="expr.html">Expression parser</page>
+    <page href="mod/overrides.html">Override Class Index for .htaccess</page>
     <page href="programs/">Server and Supporting Programs</page>
     <page href="glossary.html">Glossary</page>
 </category>
diff --git a/docs/manual/mod/core.xml b/docs/manual/mod/core.xml
index b3c1fb3c20..e33b8386fc 100644
--- a/docs/manual/mod/core.xml
+++ b/docs/manual/mod/core.xml
@@ -345,10 +345,12 @@ NoDecode option available in 2.3.12 and later.</compatibility>
     <code>.htaccess</code> files.</p>
 
     <p>The <var>directive-type</var> can be one of the following
-    groupings of directives.</p>
+    groupings of directives. (See the <a href="overrides.html">override class
+    index</a> for an up-to-date listing of which directives are enabled by each
+    <var>directive-type</var>.)</p>
 
     <dl>
-      <dt>AuthConfig</dt>
+      <dt><a href="overrides.html#override-authconfig">AuthConfig</a></dt>
 
       <dd>
 
@@ -361,7 +363,7 @@ NoDecode option available in 2.3.12 and later.</compatibility>
       module="mod_authn_file">AuthUserFile</directive>, <directive
       module="mod_authz_core">Require</directive>, <em>etc.</em>).</dd>
 
-      <dt>FileInfo</dt>
+      <dt><a href="overrides.html#override-fileinfo">FileInfo</a></dt>
 
       <dd>
       Allow use of the directives controlling document types
@@ -398,7 +400,7 @@ NoDecode option available in 2.3.12 and later.</compatibility>
       <module>mod_actions</module>.
       </dd>
 
-      <dt>Indexes</dt>
+      <dt><a href="overrides.html#override-indexes">Indexes</a></dt>
 
       <dd>
       Allow use of the directives controlling directory indexing
@@ -416,7 +418,7 @@ NoDecode option available in 2.3.12 and later.</compatibility>
       module="mod_autoindex">ReadmeName</directive>,
       <em>etc.</em>).</dd>
 
-      <dt>Limit</dt>
+      <dt><a href="overrides.html#override-limit">Limit</a></dt>
 
       <dd>
       Allow use of the directives controlling host access (<directive
@@ -448,7 +450,7 @@ NoDecode option available in 2.3.12 and later.</compatibility>
       </note>
       </dd>
 
-      <dt>Options[=<var>Option</var>,...]</dt>
+      <dt><a href="overrides.html#override-options">Options</a>[=<var>Option</var>,...]</dt>
 
       <dd>
       Allow use of the directives controlling specific directory
@@ -495,6 +497,7 @@ AllowOverride AuthConfig Indexes
 <seealso><directive module="core">AllowOverrideList</directive></seealso>
 <seealso><a href="../configuring.html">Configuration Files</a></seealso>
 <seealso><a href="../howto/htaccess.html">.htaccess Files</a></seealso>
+<seealso><a href="overrides.html">Override Class Index for .htaccess</a></seealso>
 </directivesynopsis>
 
 <directivesynopsis>
diff --git a/docs/manual/mod/overrides.xml b/docs/manual/mod/overrides.xml
new file mode 100644
index 0000000000..a641a98a12
--- /dev/null
+++ b/docs/manual/mod/overrides.xml
@@ -0,0 +1,141 @@
+<?xml version="1.0"?>
+<!DOCTYPE overrideindex SYSTEM "../style/modulesynopsis.dtd">
+<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
+<!-- $LastChangedRevision$ -->
+
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements.  See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License.  You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<overrideindex metafile="overrides.xml.meta">
+  <title>Override Class Index for .htaccess</title>
+  <summary>
+    <p>
+      This is an index of the directives that are allowed in .htaccess files for
+      various <directive module="core">AllowOverride</directive> settings,
+      organized by class. Its intended purpose is to help server administrators
+      verify the privileges they're granting to .htaccess users. For an overview
+      of how .htaccess works, see the
+      <a href="../howto/htaccess.html">.htaccess tutorial</a>.
+    </p>
+
+    <p>
+      To determine the set of directives that your server configuration allows
+      .htaccess users to use:
+    </p>
+
+    <ol>
+      <li>Start with the set of directives in the <code>AllowOverrideList</code>
+      for the directory in question. (By default, this is set to
+      <code>None</code>.)</li>
+      <li>Find the <code>AllowOverride</code> setting for the directory in
+      question. (By default, it is set to <code>None</code>.) There are two
+      special cases:
+        <ol>
+          <li>If your <code>AllowOverride</code> setting is <code>All</code>,
+          add every directive listed on this page to the list.</li>
+          <li>If your <code>AllowOverride</code> setting is <code>None</code>,
+          you're done. Only the directives in the <code>AllowOverrideList</code>
+          (if any) will be allowed.</li>
+        </ol>
+      </li>
+      <li>For each override class listed in <code>AllowOverride</code>, look up
+      the corresponding set of directives below and add them to the list.</li>
+      <li>Finally, add the set of directives that is always allowed in
+      .htaccess (these are listed in the
+      <a href="#override-all">All section</a>, below).</li>
+    </ol>
+
+    <p>
+      Several of the override classes are quite powerful and give .htaccess
+      users a large amount of control over the server. For a stricter approach,
+      set <code>AllowOverride None</code> and use
+      <directive module="core">AllowOverrideList</directive> to specify the
+      exact list of directives that .htaccess users are allowed to use.
+    </p>
+  </summary>
+
+  <!--
+    Provide one overridesummary element for each Override type. The content will
+    be sucked into the relevant section on the override index page.
+  -->
+
+  <overridesummary class="All">
+    <p>
+      The following directives are allowed in any .htaccess file, as long as
+      overrides are enabled in the server configuration.
+    </p>
+  </overridesummary>
+
+  <overridesummary class="AuthConfig">
+    <p>
+      The following directives are allowed in .htaccess files when
+      <code>AllowOverride AuthConfig</code> is in effect. They give .htaccess
+      users control over the authentication and authorization methods that are
+      applied to their directory subtrees, including several related utility
+      directives for session handling and TLS settings.
+    </p>
+  </overridesummary>
+
+  <overridesummary class="FileInfo">
+    <p>
+      The following directives are allowed in .htaccess files when
+      <code>AllowOverride FileInfo</code> is in effect. They give .htaccess
+      users a wide range of control over the responses and metadata given by the
+      server.
+    </p>
+  </overridesummary>
+
+  <overridesummary class="Indexes">
+    <p>
+      The following directives are allowed in .htaccess files when
+      <code>AllowOverride Indexes</code> is in effect. They allow .htaccess
+      users to control aspects of the directory index pages provided by the
+      server, including autoindex generation.
+    </p>
+  </overridesummary>
+
+  <overridesummary class="Limit">
+    <p>
+      The following directives are allowed in .htaccess files when
+      <code>AllowOverride Limit</code> is in effect. This extremely narrow
+      override type mostly allows the use of the legacy authorization directives
+      provided by <module>mod_access_compat</module>.
+    </p>
+  </overridesummary>
+
+  <overridesummary class="Options">
+    <p>
+      The following directives are allowed in .htaccess files when
+      <code>AllowOverride Options</code> is in effect. They give .htaccess
+      users access to <code>Options</code> and similar directives, as well as
+      directives that control the filter chain.
+    </p>
+  </overridesummary>
+
+  <!--
+    This is the error message for when a directive shows up in a section that
+    has no explicit overridesummary above.
+  -->
+  <overridesummary fallback="yes">
+    <p><em>
+    [This section has no description. It's possible that the documentation is
+    incomplete, or that the directives here have an incorrect or misspelled
+    Override type. Please consider reporting this in the
+    <a href="#comments_section">comments section</a>.]
+    </em></p>
+  </overridesummary>
+</overrideindex>
diff --git a/docs/manual/sitemap.xml b/docs/manual/sitemap.xml
index ee2f92e851..46799384fd 100644
--- a/docs/manual/sitemap.xml
+++ b/docs/manual/sitemap.xml
@@ -191,6 +191,7 @@ log_server_status</page>
 <page href="mod/">Module index</page>
 <page href="mod/directives.html">Directive index</page>
 <page href="mod/quickreference.html">Directive Quick-Reference</page>
+<page href="mod/overrides.html">Override class index for .htaccess</page>
 </category>
 
 </sitemap>
diff --git a/docs/manual/style/css/manual.css b/docs/manual/style/css/manual.css
index da86a9a0bb..57b5e7d230 100644
--- a/docs/manual/style/css/manual.css
+++ b/docs/manual/style/css/manual.css
@@ -611,6 +611,12 @@ div#directive-list ul {
     padding: 0;
 }
 
+/* override index */
+/* ============== */
+div#override-list td.module {
+    width: 20%;
+}
+
 /* indextable */
 /* ========== */
 table#indextable td ul {
diff --git a/docs/manual/style/modulesynopsis.dtd b/docs/manual/style/modulesynopsis.dtd
index 4dac5efc41..1ca9b06542 100644
--- a/docs/manual/style/modulesynopsis.dtd
+++ b/docs/manual/style/modulesynopsis.dtd
@@ -75,3 +75,11 @@ usage?, seealso*)>
 <!ATTLIST quickreference metafile CDATA  #REQUIRED>
 
 <!ELEMENT legend (table, table)>
+
+<!-- Used in overrides.xml -->
+<!ELEMENT overrideindex (title | summary | overridesummary)+>
+<!ATTLIST overrideindex metafile CDATA #REQUIRED>
+
+<!ELEMENT overridesummary %Block;>
+<!ATTLIST overridesummary class    CDATA #IMPLIED
+                          fallback CDATA #IMPLIED>
diff --git a/docs/manual/style/xsl/common.xsl b/docs/manual/style/xsl/common.xsl
index e71192801f..e3d8a0f6e4 100644
--- a/docs/manual/style/xsl/common.xsl
+++ b/docs/manual/style/xsl/common.xsl
@@ -64,6 +64,7 @@
 <xsl:include href="indexpage.xsl" />
 <xsl:include href="quickreference.xsl" />
 <xsl:include href="faq.xsl" />
+<xsl:include href="overrideindex.xsl" />
 
 <!-- load utility snippets -->
 <xsl:include href="util/modtrans.xsl" />
diff --git a/docs/manual/style/xsl/overrideindex.xsl b/docs/manual/style/xsl/overrideindex.xsl
new file mode 100644
index 0000000000..e65d28bea3
--- /dev/null
+++ b/docs/manual/style/xsl/overrideindex.xsl
@@ -0,0 +1,249 @@
+<?xml version="1.0"?>
+
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements.  See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License.  You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<!DOCTYPE xsl:stylesheet [
+    <!ENTITY lf SYSTEM "util/lf.xml">
+]>
+
+<xsl:stylesheet version="1.0"
+                xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+                xmlns:exslt="http://exslt.org/common"
+                xmlns:func="http://exslt.org/functions"
+                xmlns:httpd="http://httpd.apache.org/xsl/manual"
+                xmlns:set="http://exslt.org/sets"
+                xmlns:str="http://exslt.org/strings"
+                xmlns="http://www.w3.org/1999/xhtml"
+                exclude-result-prefixes="exslt func httpd set str">
+
+<!-- ======================================================================= -->
+<!-- <overrideindex>                                                         -->
+<!-- Builds the .htaccess overridable directive index                        -->
+<!-- ======================================================================= -->
+<xsl:template match="overrideindex">
+<html xml:lang="{$doclang}" lang="{$doclang}">
+    <xsl:call-template name="head"/>&lf;
+
+    <xsl:variable name="directives"
+                  select="document(
+                            document($allmodules)/modulefilelist/modulefile
+                          )/modulesynopsis[status!='Obsolete']
+                           /directivesynopsis[not(@location)]" />
+
+    <body id="override-index">&lf;
+        <xsl:call-template name="top"/>&lf;&lf;
+
+        <div id="page-content">
+            <xsl:call-template name="retired" />
+
+            <div id="preamble">
+                <h1>
+                    <xsl:value-of select="title" />
+                </h1>&lf;
+
+                <xsl:call-template name="langavail" />&lf;
+
+                <xsl:apply-templates select="summary" />
+            </div>&lf; <!-- /#preamble -->
+
+            <!-- Quickview Sidebar -->
+            <xsl:if test="not($is-chm) or seealso">
+                <div id="quickview">
+                    <xsl:if test="not($is-chm)">
+                        <xsl:if test="overridesummary">
+                            <h3>
+                                <xsl:value-of select="$message[@id='topics']" />
+                            </h3>&lf;
+
+                            <ul id="topics">&lf;
+                            <xsl:apply-templates select="overridesummary"
+                                                 mode="index" />
+                            </ul>
+                        </xsl:if>
+                    </xsl:if> <!-- /!is-chm -->
+
+                    <!-- The seealso section shows links to related documents
+                         explicitly set in .xml docs or simply the comments. -->
+                    <xsl:if test="seealso or not($is-chm or $is-zip)">
+                        <h3>
+                            <xsl:value-of select="$message[@id='seealso']" />
+                        </h3>&lf;
+
+                        <ul class="seealso">&lf;
+                        <xsl:for-each select="seealso">
+                            <li>
+                                <xsl:apply-templates />
+                            </li>&lf;
+                        </xsl:for-each>
+                        <xsl:if test="not($is-chm or $is-zip or $metafile/basename = 'index')">
+                            <li><a href="#comments_section"><xsl:value-of
+                                    select="$message[@id='comments']" /></a>
+                            </li>
+                        </xsl:if>
+                        </ul>
+                    </xsl:if>
+                </div> <!-- /#quickview -->
+            </xsl:if>&lf; <!-- have sidebar -->
+
+            <div id="override-list">
+                <xsl:variable name="root" select="." />
+
+                <xsl:for-each select="httpd:override-classes($directives)">
+                    <xsl:sort select="." />
+
+                    <xsl:call-template name="override-section">
+                        <xsl:with-param name="name" select="." />
+                        <xsl:with-param name="directives" select="$directives" />
+                        <xsl:with-param name="root" select="$root" />
+                    </xsl:call-template>
+
+                </xsl:for-each>
+            </div> <!-- /#override-list -->
+        </div> <!-- /#page-content -->
+
+        <xsl:call-template name="bottom" />&lf;
+    </body>
+</html>
+</xsl:template>
+<!-- /overrideindex -->
+
+<!-- ======================================================================= -->
+<!-- <overridesummary>                                                       -->
+<!-- Pass-through template for the overridesummary contents.                 -->
+<!-- ======================================================================= -->
+<xsl:template match="overridesummary">
+    <xsl:apply-templates />
+</xsl:template>
+
+<!-- Generates an overridesummary index, used in the quickview. -->
+<xsl:template match="overridesummary" mode="index">
+<xsl:if test="@class">
+    <li>
+        <img src="{$path}/images/down.gif" alt="" />
+        <xsl:text> </xsl:text>
+        <a href="#override-{translate(@class, $uppercase, $lowercase)}">
+            <xsl:apply-templates select="@class" mode="print" />
+        </a>
+    </li>&lf;
+</xsl:if>
+</xsl:template>
+
+<!--
+    Generates a section for an Override class, including the section header,
+    the class description, and the table of directives belonging to that class.
+-->
+<xsl:template name="override-section">
+    <xsl:param name="name" />       <!-- the name of the Override class -->
+    <xsl:param name="directives" /> <!-- the directive nodes -->
+    <xsl:param name="root" />       <!-- the root of the overrideindex element -->
+
+    <!-- The "up" arrow link. -->
+    <div class="top">
+        <a href="#page-header">
+            <img alt="top" src="{$path}/images/up.gif" />
+        </a>
+    </div>
+
+    <div class="section">
+        <!-- Section header -->
+        <h2>
+            <a name="override-{translate($name, $uppercase, $lowercase)}">
+                <xsl:value-of select="$name" />
+            </a>
+        </h2>
+
+        <!--
+            Search the input document for the overridesummary element
+            corresponding to this Override class, and put its description into
+            the document here. If there isn't one, use the fallback element
+            (which should alert users/committers to a problem).
+        -->
+        <xsl:apply-templates select="($root//overridesummary[@class=$name]
+                                      | $root//overridesummary[@fallback])[1]" />
+
+        <!-- Directive table -->
+        <table class="qref">
+        <xsl:for-each select="$directives[contains(override, $name)]">
+            <xsl:sort select="name" />
+
+            <!--
+                Partially duplicated from quickreference.xsl. Generate a row
+                containing the directive name, its description, and its parent
+                module. Zebra-stripe every second row.
+            -->
+            <tr>
+                <xsl:if test="position() mod 2 = 0">
+                    <xsl:attribute name="class">odd</xsl:attribute>
+                </xsl:if>
+
+                <td>
+                <a href="{../name}.html#{translate(name, $uppercase, $lowercase)}">
+                    <xsl:if test="@type = 'section'">&lt;</xsl:if>
+                    <xsl:value-of select="name" />
+                    <xsl:if test="@type = 'section'">&gt;</xsl:if>
+                </a>
+                </td>
+
+                <td class="module">
+                <a href="{../name}.html">
+                    <xsl:value-of select="../name" />
+                </a>
+                </td>
+            </tr>&lf;
+
+            <tr>
+                <xsl:if test="position() mod 2 = 0">
+                    <xsl:attribute name="class">odd</xsl:attribute>
+                </xsl:if>
+
+                <td class="descr" colspan="2">
+                    <xsl:choose>
+                    <xsl:when test="string-length(normalize-space(description)) > 0">
+                        <xsl:apply-templates select="description" />
+                    </xsl:when>
+                    <xsl:otherwise>
+                        <xsl:text>-</xsl:text>
+                    </xsl:otherwise>
+                    </xsl:choose>
+                </td>
+            </tr>&lf;
+        </xsl:for-each>
+        </table>
+    </div>
+</xsl:template>
+<!-- /override-section -->
+
+<!--
+    Returns the set of distinct Override classes reported by the passed set of
+    directives.
+-->
+<func:function name="httpd:override-classes">
+    <xsl:param name="directives" />
+
+    <xsl:variable name="overrideValues">
+        <xsl:for-each select="$directives/override">
+            <xsl:for-each select="str:split(., ',')">
+                <value><xsl:value-of select="normalize-space(.)" /></value>
+            </xsl:for-each>
+        </xsl:for-each>
+    </xsl:variable>
+
+    <func:result select="set:distinct(exslt:node-set($overrideValues)/*)" />
+</func:function>
+
+</xsl:stylesheet>