[Bug 70019] New: RewriteRule documentation unclear/incoherent about substitution interpretation (file-system path vs URL-path)

https://bz.apache.org/bugzilla/show_bug.cgi?id=70019

            Bug ID: 70019
           Summary: RewriteRule documentation unclear/incoherent about
                    substitution interpretation (file-system path vs
                    URL-path)
           Product: Apache httpd-2
           Version: 2.5-HEAD
          Hardware: All
               URL: https://httpd.apache.org/docs/trunk/en/mod/mod_rewrite
                    .html#rewriterule
                OS: All
            Status: NEW
          Severity: normal
          Priority: P2
         Component: Documentation
          Assignee: [email protected]
          Reporter: [email protected]
  Target Milestone: ---

The documentation of the RewriteRule directive contains:
> The Substitution of a rewrite rule is the string that replaces the original URL-path that was matched by Pattern. The Substitution may be a:

> file-system path
>    Designates the location on the file-system of the resource to be delivered to the client. Substitutions are only treated as a file-system path when the rule is configured in server (virtualhost) context and the first component of the path in the substitution exists in the file-system

> URL-path
>    A DocumentRoot-relative path to the resource to be served. Note that mod_rewrite tries to guess whether you have specified a file-system path or a URL-path by checking to see if the first segment of the path exists at the root of the file-system. For example, if you specify a Substitution string of /www/file.html, then this will be treated as a URL-path unless a directory named www exists at the root of your file-system (or, in the case of per-directory rewrites, relative to your document root), in which case it will be treated as a file-system path. If you wish other URL-mapping directives (such as Alias) to be applied to the resulting URL-path, use the [PT] flag as described below.

If my understanding is correct, most of the "definitions" deal with the
ambiguity created by the lack of syntax to differ these 2 forms, and how httpd
guesses which is meant.

For file-system paths, this reads:
> Substitutions are only treated as a file-system path when the rule is configured in server (virtualhost) context and the first component of the path in the substitution exists in the file-system

For URL-paths, this reads:
> Note that mod_rewrite tries to guess whether you have specified a file-system path or a URL-path by checking to see if the first segment of the path exists at the root of the file-system. For example, if you specify a Substitution string of /www/file.html, then this will be treated as a URL-path unless a directory named www exists at the root of your file-system (or, in the case of per-directory rewrites, relative to your document root), in which case it will be treated as a file-system path.

Therefore, the above 2 subparagraphs look redundant, yet incoherent. According
to the first, a file-system path may only occur in server context, but that is
not what the second says.

I believe the URL-path version is the least incorrect one. The file-system path
version, which I believe was added to address issue #52000, also seems to
confuse "server" and virtual host contexts. Since that part is crucial, instead
of duplicating "Note that […]" in both bullets, I would recommend to make a
warning box right after that list, possibly titled "Ambiguity between
file-system paths and URL-paths".

Unfortunately, I think the URL-path paragraph is incorrect, by assuming that
there is no base URL (RewriteBase).

I will take the liberty to highlight a couple more distinct problems as they
overlap this one (but I can file different tickets if these remain):
1. The "list" is implemented as a definition list. This is semantically
incorrect, since the "definitions" do not *define* the terms, which are rather
names. Definition lists are designed for pages like Terms Used to Describe
Directives.
2. The term "file-system path" is not defined in Terms Used to Describe
Directives nor in the glossary. The term "file-path" is, although I am not sure
from the documentation that the meaning is the same. 

🅭🄍: https://www.philippecloutier.com/Common+infrastructure+licensing#its

-- 
You are receiving this mail because:
You are the assignee for the bug.