You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs@httpd.apache.org by bu...@apache.org on 2026/05/06 10:16:36 UTC
[Bug 70024] New: RewriteRule documentation incoherent about matched string (“original URL-path”)
https://bz.apache.org/bugzilla/show_bug.cgi?id=70024
Bug ID: 70024
Summary: RewriteRule documentation incoherent about matched
string (“original 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: P3
Component: Documentation
Assignee: docs@httpd.apache.org
Reporter: chealer@gmail.com
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.
But according to the “What is matched?” section above:
> In per-directory context (Directory and .htaccess), the Pattern is matched against only a partial path, for example a request of "/app1/index.html" may result in comparison against "app1/index.html" or "index.html" depending on the directory-path for which the RewriteRule applies.
I find “What is matched?” unclear (in particular “the currently mapped
filesystem path“) and am not sure it is correct, but I am confident that “the
original URL-path” is not accurate (only correct some of the time).
I suggest to give the subject of “What is matched?” a name (something like “the
input path”) and just reuse that name in the first sentence this quotes, rather
than try to redefine it.
🅭🄍: https://www.philippecloutier.com/Common+infrastructure+licensing#its
--
You are receiving this mail because:
You are the assignee for the bug.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
[Bug 70024] RewriteRule: clarify what Pattern matches and what Substitution replaces across contexts
Posted by bu...@apache.org.
https://bz.apache.org/bugzilla/show_bug.cgi?id=70024
--- Comment #10 from Rich Bowen <rb...@apache.org> ---
Thanks for this patch. The intent — clarifying what Pattern matches and what
Substitution replaces — is worthwhile.
However, I'd like to suggest a different approach before committing this as-is:
1. Split into smaller patches
This bundles at least 4 independent changes. Reviewing and committing
separately would be much easier:
- (A) Add [!] to the syntax line — trivial, can commit immediately
- (B) Consolidate the Negation note — low-risk reformatting
- (C) Rewrite "What is matched?" section
- (D) Restructure Substitution section from <dl> to nested <ul>
2. Guide vs. reference doc placement
The expanded Rewrite Guide (docs/manual/rewrite/) has recently been
substantially rewritten. Much of what this patch adds to the directive synopsis
is already covered:
- VirtualHost vs. per-directory matching → rewrite/htaccess.xml §"What URL does
the rule see?"
- Directory-path stripping → rewrite/htaccess.xml §"path-stripping"
- Sequential rule application → rewrite/tech.xml §"API Phases"
The httpd docs deliberately separate terse reference (mod/*.xml) from
explanatory guide content (rewrite/*.xml). I'd prefer to keep the directive
synopsis concise and cross-reference the guide rather than duplicating
tutorial-level explanations inline.
3. On "subject-path" terminology
I'd rather not introduce new terminology here. The relevant concepts already
have well-defined names in RFC 7230/9110 (request-target, path) and in httpd's
own vocabulary (URL-path, filesystem path). Coining "subject-path" doesn't
clarify — it adds a term readers then have to map back to the standard ones.
The current approach of explaining contextually what the pattern is matched
against is sufficient.
4. Technical concerns
- "The subject-path and directives such as DocumentRoot and Alias determine the
currently mapped filesystem path" — this inverts the causality.
DocumentRoot/Alias determine the mapped path; the prefix is stripped from that
to produce what the pattern sees.
- "satisfied if and only if the pattern has at least 1 match" — a regex either
matches a string or it doesn't. This phrasing implies multiple matches are
possible against a single string.
Suggested path forward:
- Commit patches A and B directly
- For C and D: consider whether the content you want to add is already in the
Rewrite Guide docs. If it's not there, that's where it should go — with a
cross-reference from the directive synopsis.
Happy to discuss further.
--
You are receiving this mail because:
You are the assignee for the bug.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
[Bug 70024] RewriteRule docs: "original URL-path" is misleading — matched string varies by context
Posted by bu...@apache.org.
https://bz.apache.org/bugzilla/show_bug.cgi?id=70024
--- Comment #9 from Rich Bowen <rb...@apache.org> ---
I believe the updated title more accurately reflects what this ticket is about
- that what is matched varies by context. While I do think the prose explains
this, there's always room for clarification.
However, the attached patch addresses a bunch of other things, and will need to
be considered very carefully. I don't believe we can apply it as is, but I'll
figure out what we can and cannot apply. (Likely after next week, as I'll be
traveling.)
--
You are receiving this mail because:
You are the assignee for the bug.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
[Bug 70024] RewriteRule documentation incoherent about matched string (“original URL-path”)
Posted by bu...@apache.org.
https://bz.apache.org/bugzilla/show_bug.cgi?id=70024
--- Comment #7 from Rich Bowen <rb...@apache.org> ---
Ok, I'll have to look at the patch tomorrow. I cannot tell, from this ticket
what it's about any more.
--
You are receiving this mail because:
You are the assignee for the bug.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
[Bug 70024] RewriteRule documentation incoherent about matched string (“original URL-path”)
Posted by bu...@apache.org.
https://bz.apache.org/bugzilla/show_bug.cgi?id=70024
Rich Bowen <rb...@apache.org> changed:
What |Removed |Added
----------------------------------------------------------------------------
Resolution|--- |WONTFIX
Status|NEEDINFO |RESOLVED
--- Comment #3 from Rich Bowen <rb...@apache.org> ---
On further review, the documentation is correct here. It's not an
inconsistency, rather, it's describing the fact that mod_rewrite behaves
differently in different contexts.
I gave some thought to calling this "The input path" or similar. The
difficulty, as described by the flowchart diagram in the
https://httpd.apache.org/docs/current/rewrite/tech.html document, is that there
is not one "input path". Rather, there is a string that can be updated multiple
times (or once, or not at all) as it passes through multiple rewriting phases,
or multiple rules. There's just whatever state it's in at any given moment. I
worry that calling it "input path" suggests that it's a single value, rather
than one point in a process.
The original URL-path becomes a modified URL path (or, sometimes it doesn't) as
it flows through the process. See
https://httpd.apache.org/docs/current/rewrite/tech.html#InternalRuleset for the
diagram referenced. The only fixed point is "The Request" (ie, the original
URL-path) and after that it's all in flux.
I am inclined to close this as WONTFIX because the doc is correct. Willing to
reconsider if someone has specific rephrasings.
Meanwhile, I'm conintuing to go through the entire /rewrite section of the doc
looking for possible improvements.
--
You are receiving this mail because:
You are the assignee for the bug.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
[Bug 70024] RewriteRule: clarify what Pattern matches and what Substitution replaces across contexts
Posted by bu...@apache.org.
https://bz.apache.org/bugzilla/show_bug.cgi?id=70024
--- Comment #13 from Rich Bowen <rb...@apache.org> ---
`!` is a standard part of regular expression matching, which is done in the
library that we use in this module. Implications to the contrary (in this doc
and elsewhere) are confusing, and should be clarified.
--
You are receiving this mail because:
You are the assignee for the bug.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
[Bug 70024] RewriteRule documentation incoherent about matched string (“original URL-path”)
Posted by bu...@apache.org.
https://bz.apache.org/bugzilla/show_bug.cgi?id=70024
Rich Bowen <rb...@apache.org> changed:
What |Removed |Added
----------------------------------------------------------------------------
Status|NEW |NEEDINFO
--- Comment #1 from Rich Bowen <rb...@apache.org> ---
Yes, those are both correct. The first is in global context, and the second is
in per-directory context (<Directory> and .htaccess), as it says.
I see some value in giving that a name, but it is true that it changes due to
context, as that prose attempts to explain. It handles whatever the status of
the "requested URL at this particular moment", which changes throughout the
request lifecycle.
That said, I'm definitely willing to make updates, but I'm not clear here what
specific change you're requesting. Would you be willing to draft a replacement
text for us to consider?
--
You are receiving this mail because:
You are the assignee for the bug.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
[Bug 70024] RewriteRule documentation incoherent about matched string (“original URL-path”)
Posted by bu...@apache.org.
https://bz.apache.org/bugzilla/show_bug.cgi?id=70024
--- Comment #2 from Joe Orton <jo...@redhat.com> ---
This kind of report could be a mailing list discussion on docs@httpd, I think
we should reserve Bugzilla for actual bugs.
https://httpd.apache.org/lists.html#http-docs
--
You are receiving this mail because:
You are the assignee for the bug.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
[Bug 70024] RewriteRule documentation incoherent about matched string (“original URL-path”)
Posted by bu...@apache.org.
https://bz.apache.org/bugzilla/show_bug.cgi?id=70024
Philippe Cloutier <ch...@gmail.com> changed:
What |Removed |Added
----------------------------------------------------------------------------
Status|RESOLVED |REOPENED
Resolution|WONTFIX |---
--- Comment #4 from Philippe Cloutier <ch...@gmail.com> ---
(In reply to Joe Orton from comment #2)
> This kind of report could be a mailing list discussion on docs@httpd, I
> think we should reserve Bugzilla for actual bugs.
Despite its name and terminology, Bugzilla is not just designed for bugs. This
reports one, however.
(In reply to Rich Bowen from comment #3)
> On further review, the documentation is correct here. It's not an
> inconsistency, rather, it's describing the fact that mod_rewrite behaves
> differently in different contexts.
Describing several behaviors is not an inconsistency. But the first sentence
quoted in the Description is nevertheless incoherent; it assumes a context,
whereas, “What is matched?” explains the behavior in the various contexts.
By the way, even if the reader could guess it is only talking about the
(basically) first non-per-directory rule, it is also misleading to call
Substitution a replacement of the original URL-path in that case, since
Substitution is not always a path.
> I gave some thought to calling this "The input path" or similar. The
> difficulty, as described by the flowchart diagram in the
> https://httpd.apache.org/docs/current/rewrite/tech.html document, is that
> there is not one "input path". Rather, there is a string that can be updated
> multiple times (or once, or not at all) as it passes through multiple
> rewriting phases, or multiple rules. There's just whatever state it's in at
> any given moment. I worry that calling it "input path" suggests that it's a
> single value, rather than one point in a process.
"input path" was just a quick suggestion. It has the advantage of not being
incorrect, but I agree it can be misleading. I guess calling it “subject-path”,
with a link to a definition of that, would avoid that, although the meaning may
not be as intuitively clear.
> The original URL-path becomes a modified URL path (or, sometimes it doesn't)
> as it flows through the process. See
> https://httpd.apache.org/docs/current/rewrite/tech.html#InternalRuleset for
> the diagram referenced. The only fixed point is "The Request" (ie, the
> original URL-path) and after that it's all in flux.
Right, that's why it should not be qualified as “original”.
> I am inclined to close this as WONTFIX because the doc is correct. Willing
> to reconsider if someone has specific rephrasings.
In the worst case (if consensus on a name is unachievable), this could simply
be fixed with:
> The Substitution of a rewrite rule is the string that replaces the path that was matched by Pattern.
> Meanwhile, I'm conintuing to go through the entire /rewrite section of the
> doc looking for possible improvements.
Thanks again Rich
--
You are receiving this mail because:
You are the assignee for the bug.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
[Bug 70024] RewriteRule: clarify what Pattern matches and what Substitution replaces across contexts
Posted by bu...@apache.org.
https://bz.apache.org/bugzilla/show_bug.cgi?id=70024
--- Comment #11 from Rich Bowen <rb...@apache.org> ---
Y'know, the more I look at this, the more I think this is wrong. This patch
implies that '!' is separate from "the pattern" - ie, the regular expression -
and it is not. the '!' is part of the regex.
Meanwhile, the part of the doc that starts with "the NOT character", also seems
to suggest that ! is somehow part of mod_rewrite's logic, when, in fact, it's
just a usual part of the pcre engine.
I think a better approach here is to link to the Regular Expression overview in
https://httpd.apache.org/docs/current/rewrite/intro.html#regex rather than
duplicating the explanation here.
I really think that what we need to do here, therefore, is remove this block
(the bit that starts with "the NOT character" and link over to the "Regex
vocabulary" section in /rewrite/intro.html
I'm also considering splitting off that section into a separate regex.xml doc
in that directory, but that's a larger project and beyond the scope of this
ticket.
--
You are receiving this mail because:
You are the assignee for the bug.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
[Bug 70024] RewriteRule documentation incoherent about matched string (“original URL-path”)
Posted by bu...@apache.org.
https://bz.apache.org/bugzilla/show_bug.cgi?id=70024
Philippe Cloutier <ch...@gmail.com> changed:
What |Removed |Added
----------------------------------------------------------------------------
Resolution|FIXED |---
Status|RESOLVED |REOPENED
--
You are receiving this mail because:
You are the assignee for the bug.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
[Bug 70024] RewriteRule docs: "original URL-path" is misleading — matched string varies by context
Posted by bu...@apache.org.
https://bz.apache.org/bugzilla/show_bug.cgi?id=70024
Rich Bowen <rb...@apache.org> changed:
What |Removed |Added
----------------------------------------------------------------------------
Summary|RewriteRule documentation |RewriteRule docs: "original
|incoherent about matched |URL-path" is misleading —
|string (“original |matched string varies by
|URL-path”) |context
--
You are receiving this mail because:
You are the assignee for the bug.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
[Bug 70024] RewriteRule documentation incoherent about matched string (“original URL-path”)
Posted by bu...@apache.org.
https://bz.apache.org/bugzilla/show_bug.cgi?id=70024
--- Comment #8 from Rich Bowen <rb...@apache.org> ---
I think this patch is intended to clarify what inputs a RewriteRule has, but it
also overhauls some of the regular expression matching section, based on Claude
confirming your statement that it's misleading.
I will attempt to review the patch at some point, but unlikely to get to it
today. I'm going to attempt to retitle this ticket to reflect what it's
actually about, but I'm still kind of unsure what it's actually intended to
address. "Incoherent" does not communicate to me what you're actually objecting
to.
--
You are receiving this mail because:
You are the assignee for the bug.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
[Bug 70024] RewriteRule: clarify what Pattern matches and what Substitution replaces across contexts
Posted by bu...@apache.org.
https://bz.apache.org/bugzilla/show_bug.cgi?id=70024
Rich Bowen <rb...@apache.org> changed:
What |Removed |Added
----------------------------------------------------------------------------
Resolution|--- |FIXED
Status|REOPENED |RESOLVED
--- Comment #14 from Rich Bowen <rb...@apache.org> ---
r1934224 consolidates the regular expression advice (in particular, the
discussion of negation with !) to the rewrite/intro.xml doc, rather than
duplicating it here.
Declines the inaccurate portions of the offered patch.
Discussion of how RewriteRule matches requests, and the portions of the HTTP
request that are (or can be) considered, is covered in detail in
rewrite/intro.html and rewrite/htaccess.html, and so is not duplicated here.
Ideally, we'll reduce that duplication even further in the coming days --
mod/mod_rewrite.html is intended to be the "just the facts" reference manual,
and rewrite/* is intended to be the in-depth hand-holding tutorial.
Closing FIXED, but will follow up with moving more of this "what is matched"
content into the Rewrite Guide folder, and leave references to that content in
the reference manual.
--
You are receiving this mail because:
You are the assignee for the bug.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
[Bug 70024] RewriteRule: clarify what Pattern matches and what Substitution replaces across contexts
Posted by bu...@apache.org.
https://bz.apache.org/bugzilla/show_bug.cgi?id=70024
--- Comment #12 from Eric Covener <co...@gmail.com> ---
(In reply to Rich Bowen from comment #11)
> Y'know, the more I look at this, the more I think this is wrong. This patch
> implies that '!' is separate from "the pattern" - ie, the regular expression
> - and it is not. the '!' is part of the regex.
>
> Meanwhile, the part of the doc that starts with "the NOT character", also
> seems to suggest that ! is somehow part of mod_rewrite's logic, when, in
> fact, it's just a usual part of the pcre engine.
I didn't read the entire bug for obvious reasons but I think you've got it
wrong, the negation is in mod_rewrite rather than the regex.
--
You are receiving this mail because:
You are the assignee for the bug.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
[Bug 70024] RewriteRule documentation incoherent about matched string (“original URL-path”)
Posted by bu...@apache.org.
https://bz.apache.org/bugzilla/show_bug.cgi?id=70024
--- Comment #6 from Philippe Cloutier <ch...@gmail.com> ---
Created attachment 40176
--> https://bz.apache.org/bugzilla/attachment.cgi?id=40176&action=edit
Patch (untested)
Thanks Rich, but that depends on how one defines “correctness”. I checked again
and what is clear is that the section is misleading. I am sure that the section
is incoherent, and very confident that what the most problematic sentence
implies is incorrect.
Confirming with Sonnet 4.6 found several issues:
https://claude.ai/share/71b40b99-a667-4d66-b8c4-7e9a39c15c2e
#1 and #2 are those which this tracks. #3 is what I added in comment #4. #4 is
broken, but Claude has a point, which I had not noticed since the other issues
basically hide it.
Point #4 is also interesting in its usage of both “input path” and “subject
string”. In the following, I settled on “subject-path”, but better suggestions
are welcome.
Attempting to solve all that is unrealistic without restructuring, so I bit the
bullet. The attached patch also makes the "list" semantically valid,
implementing the first 3 recommendations from ticket #70020 and cleans up a few
more things, but does *not* constitute a full review of even that list. In
particular, the URL treatment still claims the externality test is merely based
on the host, even though it is surely based on the whole authority (port
included).
Note that the changes are poorly displayed on my local VS Code (they seem more
extensive than they are). Strangely, github.dev understands them considerably
better.
--
You are receiving this mail because:
You are the assignee for the bug.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
[Bug 70024] RewriteRule: clarify what Pattern matches and what Substitution replaces across contexts
Posted by bu...@apache.org.
https://bz.apache.org/bugzilla/show_bug.cgi?id=70024
Rich Bowen <rb...@apache.org> changed:
What |Removed |Added
----------------------------------------------------------------------------
Summary|RewriteRule docs: "original |RewriteRule: clarify what
|URL-path" is misleading — |Pattern matches and what
|matched string varies by |Substitution replaces
|context |across contexts
--
You are receiving this mail because:
You are the assignee for the bug.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
[Bug 70024] RewriteRule documentation incoherent about matched string (“original URL-path”)
Posted by bu...@apache.org.
https://bz.apache.org/bugzilla/show_bug.cgi?id=70024
Rich Bowen <rb...@apache.org> changed:
What |Removed |Added
----------------------------------------------------------------------------
Status|REOPENED |RESOLVED
Resolution|--- |FIXED
--- Comment #5 from Rich Bowen <rb...@apache.org> ---
Upon further review, I am confident that the docs are correct and clear on this
point. Closing. Thanks for your input.
--
You are receiving this mail because:
You are the assignee for the bug.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
[Bug 70024] RewriteRule: misleading about the Pattern’s subject string and what Substitution replaces (not always “original URL-path”)
Posted by bu...@apache.org.
https://bz.apache.org/bugzilla/show_bug.cgi?id=70024
Rich Bowen <rb...@apache.org> changed:
What |Removed |Added
----------------------------------------------------------------------------
Status|REOPENED |RESOLVED
Resolution|--- |WONTFIX
--- Comment #16 from Rich Bowen <rb...@apache.org> ---
I can no longer discern what this ticket is about. Continuing to reopen it with
yet more commentary only serves to further confuse me as to what it is that you
are trying to address in this ticket. The title seems to bear very little
resemblance to what is discussed here, and comment 15 seems to add yet more
topics to the growing list.
*Please* stop reopening it and adding more things. *Please* open individual
tickets for the various things that you're discussing here.
I'm closing this WONTFIX, not because what is listed here is unfixable, or that
I refuse to fix them, but because this ticket is no longer about any one issue.
I count at least 8 different things, some of which have been addressed, and
some of which I believe have been fixed and apparently you believe have not.
But it's no longer possible to figure out what it's actually about.
*PLEASE* open individual tickets about individual topics. If there are issues
in this ticket that you believe are not yet addressed, open a ticket for each.
No "By the way" and no "and another thing."
--
You are receiving this mail because:
You are the assignee for the bug.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
[Bug 70024] RewriteRule: misleading about the Pattern’s subject string and what Substitution replaces (not always “original URL-path”)
Posted by bu...@apache.org.
https://bz.apache.org/bugzilla/show_bug.cgi?id=70024
Philippe Cloutier <ch...@gmail.com> changed:
What |Removed |Added
----------------------------------------------------------------------------
Summary|RewriteRule: clarify what |RewriteRule: misleading
|Pattern matches and what |about the Pattern’s subject
|Substitution replaces |string and what
|across contexts |Substitution replaces (not
| |always “original URL-path”)
Resolution|FIXED |---
Status|RESOLVED |REOPENED
--- Comment #15 from Philippe Cloutier <ch...@gmail.com> ---
(In reply to Rich Bowen from comment #7)
> Ok, I'll have to look at the patch tomorrow.
(In reply to Rich Bowen from comment #8)
> I will attempt to review the patch at some point, but unlikely to get to it
> today.
Thanks. Note that this reports a defect of normal importance which has been
present for over 19 years:
https://github.com/apache/httpd/commit/fc5122253ab7368941ab610077bc5948911b9117
There is no urgency to fix, and I would much prefer to be told about a complete
fix without regressions in 1 month than about a rushed fix this week which
turns out to be partial.
> I'm going to attempt to retitle this ticket to reflect what it's
> actually about, but I'm still kind of unsure what it's actually intended to
> address. "Incoherent" does not communicate to me what you're actually
> objecting to.
OK, I replaced with a title pointing more precisely to where I am confident the
error is.
(In reply to Rich Bowen from comment #10)
> 1. Split into smaller patches
>
> This bundles at least 4 independent changes. Reviewing and committing
> separately would be much easier:
>
> - (A) Add [!] to the syntax line — trivial, can commit immediately
> - (B) Consolidate the Negation note — low-risk reformatting
> - (C) Rewrite "What is matched?" section
> - (D) Restructure Substitution section from <dl> to nested <ul>
I am an advocate of commit atomicity; this section’s slow evolution is not the
only reason why I tied several changes together. The changes are not
independent. For example, defining when a rule triggers depends on fixing the
description for no match rules (A). But well, feel free to commit as you wish
if you think it's realistic.
> 2. Guide vs. reference doc placement
>
> The expanded Rewrite Guide (docs/manual/rewrite/) has recently been
> substantially rewritten. Much of what this patch adds to the directive
> synopsis is already covered:
>
> - VirtualHost vs. per-directory matching → rewrite/htaccess.xml §"What URL
> does the rule see?"
> - Directory-path stripping → rewrite/htaccess.xml §"path-stripping"
> - Sequential rule application → rewrite/tech.xml §"API Phases"
>
> The httpd docs deliberately separate terse reference (mod/*.xml) from
> explanatory guide content (rewrite/*.xml). I'd prefer to keep the directive
> synopsis concise and cross-reference the guide rather than duplicating
> tutorial-level explanations inline.
I fail to see your point here. The patch’s goal is to fix the reference. If you
see “tutorial-level explanations” that appear added, they must simply have been
moved.
> 3. On "subject-path" terminology
>
> I'd rather not introduce new terminology here. The relevant concepts already
> have well-defined names in RFC 7230/9110 (request-target, path) and in
> httpd's own vocabulary (URL-path, filesystem path). Coining "subject-path"
> doesn't clarify — it adds a term readers then have to map back to the
> standard ones.
httpd introduces terms like "directory-path" and "file-path" even if these
could be replaced using standard terms like "pathname". Any term does require
readers to learn and remember, although tooltips (a la
https://www.glossaryplugin.com/demo/) would help.
> The current approach of explaining contextually what the
> pattern is matched against is sufficient.
If the current approach was sufficient, we would not see “the original
URL-path” or that kind of shortcut spread through the documentation. Expanding
a proper definition each time requires effort from writers, and lengthens what
readers go through.
> 4. Technical concerns
>
> - "The subject-path and directives such as DocumentRoot and Alias determine
> the currently mapped filesystem path" — this inverts the causality.
> DocumentRoot/Alias determine the mapped path; the prefix is stripped from
> that to produce what the pattern sees.
As the “What is matched?” section explains, the currently mapped filesystem
path is not only determined by DocumentRoot/Alias:
https://httpd.apache.org/docs/2.4/en/mod/mod_rewrite.html#rewriterule
> - "satisfied if and only if the pattern has at least 1 match" — a regex
> either matches a string or it doesn't.
Not really. Without going into details, if you test a regex against "subject
string", you are testing tens of substrings. If the pattern is "s", there is 1
match for [0,1] and another for [8,9]. See pcre2demo(3) and its "-g" switch.
However, mod_rewrite does not find all of these; a rule triggers as soon as the
subject-path has at least 1 matching substring.
That being said, your comment is valuable, highlighting that mod_rewrite
assumes no more than 1 match. The documentation needs to explain which match is
considered for back-references.
> Suggested path forward:
>
> - […]
> - For C and D: consider whether the content you want to add is already in
> the Rewrite Guide docs. If it's not there, that's where it should go — with
> a cross-reference from the directive synopsis.
The little content this adds only makes up for {under,mis}-specified parts. It
first belongs in specification, although nothing prevents adding it or adapting
it for the guide.
(In reply to Rich Bowen from comment #11)
> Y'know, the more I look at this, the more I think this is wrong. This patch
> implies that '!' is separate from "the pattern" - ie, the regular expression
> - and it is not. the '!' is part of the regex.
>
> Meanwhile, the part of the doc that starts with "the NOT character", also
> seems to suggest that ! is somehow part of mod_rewrite's logic, when, in
> fact, it's just a usual part of the pcre engine.
(In reply to Rich Bowen from comment #13)
> `!` is a standard part of regular expression matching, which is done in the
> library that we use in this module.
You are not entirely wrong, but mod_rewrite is !simple. PCRE supports “^” and
“!” for negation, but these are only supported in specific contexts. When the
first argument starts with an exclamation mark, there would be no such context
if the mark was integrated in the pattern, so it would be literal was it not
for special treatment: https://regexr.com/8n498
To avoid further complicating this already non-trivial ticket, this is now
tracked in #70061.
(In reply to Rich Bowen from comment #14)
> Declines the inaccurate portions of the offered patch.
If you see any new inaccuracy which the patch adds, please indicate it.
> r1934224 consolidates the regular expression advice (in particular, the
> discussion of negation with !) to the rewrite/intro.xml doc, rather than
> duplicating it here.
> […]
> Discussion of how RewriteRule matches requests, and the portions of the HTTP
> request that are (or can be) considered, is covered in detail in
> rewrite/intro.html and rewrite/htaccess.html, and so is not duplicated here.
>
> Ideally, we'll reduce that duplication even further in the coming days --
> mod/mod_rewrite.html is intended to be the "just the facts" reference
> manual, and rewrite/* is intended to be the in-depth hand-holding tutorial.
Specifying how RewriteRule matches is not (just) hand-holding material. This is
core behavior for the reference manual, not just for a guide which
“supplements” it.
I agree the task is already large enough to avoid duplication, but I am
skeptical that linking to the RewriteRule Basics section, which is inaccurate
and largely redundant with RewriteRule Directive, is desirable.
> Closing FIXED, but will follow up with moving more of this "what is matched"
> content into the Rewrite Guide folder, and leave references to that content
> in the reference manual.
There is some improvement in your changes (in particular, I appreciate that
this better sticks to a specification, moving advice elsewhere), but the issue
this tracks (the 3 or 4 issues Claude described) unfortunately persists.
--
You are receiving this mail because:
You are the assignee for the bug.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org