[Bug 70020] New: RewriteRule documentation does not fully specify how substitution paths are interpreted

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

            Bug ID: 70020
           Summary: RewriteRule documentation does not fully specify how
                    substitution paths are interpreted
           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: enhancement
          Priority: P2
         Component: Documentation
          Assignee: [email protected]
          Reporter: [email protected]
  Target Milestone: ---

The documentation of the RewriteRule directive indicates that the substitution
can take 4 forms. The first 2 of the list (file-system path and URL-path) are
confusing, since they are both in the form of paths.

At least 2, and in some case 3 factors influence whether a path is considered a
file-system path or a URL-path:
1. Whether it starts with a slash
2. Whether it is defined in per-directory context
3. Sometimes, whether the first component exists in the filesystem

Current documentation specifies how the combination Yes-Yes is interpreted (as
a URL-path). However, it is not specified how No-* combinations are
interpreted.

I would recommend the following:
1. Change the current "list" of forms to an unordered list. The list is
currently 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. Group file-system path and URL-path in a single "path" bullet, each current
item as a sub-item of that merged bullet.
3. Move the part of the current "definitions" which specify which type of path
a substitution is interpreted as (such as "A substitution beginning with / is
treated as a file-system path only in server or virtual host context, and only
when the first component of the path exists in the file-system.") to the end of
that merged bullet.
4. Probably add a table at the end of that bullet to convey mod_rewrite's
algorithm in a form graspable by mere mortals. I guess using factors 1 and 2 as
columns/rows in a 2x2 table would also make it easy to ensure that all cases
are covered.

Finally, it would surely help to replace the 2 columns currently in each of the
2 tables at the end with the following columns:
  1. Substitution (for example, otherpath$1)
  2. Substitution form (for example, URL-path)
  3. Flags (for example, [R])
  4. Effect

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

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