From 5e976e45e1bbbbbbe2d287bc06e60957f9c2dd4e Mon Sep 17 00:00:00 2001
From: Rich Bowen <rbowen@apache.org>
Date: Thu, 7 May 2026 20:27:14 +0000
Subject: [PATCH] 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)

git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1933919 13f79535-47bb-0310-9956-ffa450edef68
---
 docs/manual/mod/core.xml | 45 +++++++++++++++++++++++++---------------
 1 file changed, 28 insertions(+), 17 deletions(-)

diff --git a/docs/manual/mod/core.xml b/docs/manual/mod/core.xml
index 90d5b62802..72586e1661 100644
--- a/docs/manual/mod/core.xml
+++ b/docs/manual/mod/core.xml
@@ -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 later.</compatibility>
 <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
-- 
2.47.3