svn commit: r1933919 - httpd/httpd/trunk/docs/manual/mod

[rb...@apache.org]

Author: rbowen
Date: Thu May  7 20:27:14 2026
New Revision: 1933919

Log:
docs: Rewrite AccessFileName and AllowOverride opening paragraphs for clarity. We should not be giving examples of configuration that is objectively a terrible idea -- removed that example. (Bug 70025)

Modified:
   httpd/httpd/trunk/docs/manual/mod/core.xml

Modified: httpd/httpd/trunk/docs/manual/mod/core.xml
==============================================================================
--- httpd/httpd/trunk/docs/manual/mod/core.xml	Thu May  7 20:10:04 2026	(r1933918)
+++ httpd/httpd/trunk/docs/manual/mod/core.xml	Thu May  7 20:27:14 2026	(r1933919)
@@ -200,27 +200,38 @@ AcceptFilter https connect
 </contextlist>
 
 <usage>
-    <p>While processing a request, the server looks for
-    the first existing configuration file from this list of names in
-    every directory of the path to the document, if distributed
+    <p>The AccessFileName directive allows you to change the name of the file
+    that will be considered for per-directory configuration overrides, in the
+    event that <directive module="core">AllowOverride</directive> is enabled
+    for that directory.</p>
+
+    <note type="warning">We do not recommend that you change this value, and
+    especially that you do not list multiple possible file names, as it makes
+    troubleshooting more difficult for anyone not familiar with your local
+    settings.</note>
+
+    <p>While processing a request, the server looks for files with the name
+    (or names) defined in <code>AccessFileName</code>
+    in every directory of the path to the document, if distributed
     configuration files are <a href="#allowoverride">enabled for that
-    directory</a>. For example:</p>
-
-    <highlight language="config">
-AccessFileName .acl
-    </highlight>
-
-    <p>Before returning the document
+    directory</a>. For example Before returning the document
     <code>/usr/local/web/index.html</code>, the server will read
-    <code>/.acl</code>, <code>/usr/.acl</code>,
-    <code>/usr/local/.acl</code> and <code>/usr/local/web/.acl</code>
-    for directives unless they have been disabled with:</p>
+    <code>/.htaccess</code>, <code>/usr/.htaccess</code>,
+    <code>/usr/local/.htaccess</code> and <code>/usr/local/web/.htaccess</code>
+    for directives.</p>
+
+    <p>For this reason, the default configuration file contains the following stanza:</p>
 
     <highlight language="config">
 &lt;Directory "/"&gt;
     AllowOverride None
 &lt;/Directory&gt;
     </highlight>
+
+    <p>This configuration block helps prevent unnecessary file accesses in directories
+    outside of your <directive module="core">DocumentRoot</directive>. See also the note
+    about this in the <code>AllowOverride</code> directive documentation.</p>
+
 </usage>
 <seealso><directive module="core">AllowOverride</directive></seealso>
 <seealso><a href="../configuring.html">Configuration Files</a></seealso>
@@ -319,10 +330,10 @@ NoDecode option available in 2.3.12 and
 <contextlist><context>directory</context></contextlist>
 
 <usage>
-    <p>When the server finds an <code>.htaccess</code> file (as
-    specified by <directive module="core">AccessFileName</directive>),
-    it needs to know which directives declared in that file can override
-    earlier configuration directives.</p>
+    <p>When the server finds a distributed configuration file (Usually called
+    <code>.htaccess</code> - configurable by the <directive 
+    module="core">AccessFileName</directive>), it needs to know which directives
+    declared in that file can override earlier configuration directives.</p>
 
     <note><title>Only available in &lt;Directory&gt; sections</title>
     <directive>AllowOverride</directive> is valid only in