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/09 10:48:44 UTC
[Bug 70036] New: Terms Used to Describe Directives: URL-path definition unclear/misleading
https://bz.apache.org/bugzilla/show_bug.cgi?id=70036
Bug ID: 70036
Summary: Terms Used to Describe Directives: URL-path definition
unclear/misleading
Product: Apache httpd-2
Version: 2.5-HEAD
Hardware: All
URL: https://httpd.apache.org/docs/trunk/en/mod/directive-d
ict.html#Syntax
OS: All
Status: NEW
Severity: normal
Priority: P2
Component: Documentation
Assignee: docs@httpd.apache.org
Reporter: chealer@gmail.com
Target Milestone: ---
The Syntax section of the Terms Used to Describe Directives page defines a
URL-path as follows:
> The part of a url which follows the scheme and hostname as in /path/to/file.html. The url-path represents a web-view of a resource, as opposed to a file-system view.
A few things are unclear or misleading there:
1. Both occurrences of “url” are lowercase.
2. The URL-path does not include the port, yet depending on how one interprets
the definition, the URL-path of http://www.example.com:80/path/to/file.html
would be « 80 » or « :80/path/to/file.html ».
3. "a web-view of a resource" is not particularly clear.
4. Depending on how one interprets the definition, it may include the query
string, but it actually does not. This could be disambiguated with “immediately
follows”, and by adding a query string to the example. This could also be
disambiguated by changing "part" to "component". RFC 3986 defines "component",
however the URL Standard appears to have dropped that terminology.
The hostname and port form the *authority*.
The URL Standard at https://url.spec.whatwg.org/#url-path has a definition of
“URL path”, but I don't find it so clear at this time.
🅭🄍: 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 70036] URL-path definition unclear/misleading (Terms Used to Describe Directives, Mapping URLs to Filesystem Locations)
Posted by bu...@apache.org.
https://bz.apache.org/bugzilla/show_bug.cgi?id=70036
Rich Bowen <rb...@apache.org> changed:
What |Removed |Added
----------------------------------------------------------------------------
Status|REOPENED |RESOLVED
Resolution|--- |WONTFIX
--- Comment #5 from Rich Bowen <rb...@apache.org> ---
What you're linking to there is not from a user support forum. That's my To Do
list, for the refresh of the mod_rewrite guide. That's the list I've been
working from for the past month.
I've re-read this ticket several times this morning. I think you're saying that
the text on
https://httpd.apache.org/docs/trunk/en/mod/directive-dict.html#Syntax suggests
that URL-path might include the port number?
But then the suggested patch in "Comment 2" is to urlmapping.xml and *removes*
the clarifying text that would make it clear that it *doesn't* contain the
port. And then you link to *my* todo list (which is not linked to from
anywhere, and has only been in the repository for less than 2 weeks) as
evidence that it's confusing.
Philippe, your attention to detail has led to some good clarifications, but in
this case, it does not.
I'm closing this ticket again. The patch does not clarify, as I said in my
earlier comment. It *removes* the clarification.
--
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 70036] URL-path definition unclear/misleading (Terms Used to Describe Directives, Mapping URLs to Filesystem Locations)
Posted by bu...@apache.org.
https://bz.apache.org/bugzilla/show_bug.cgi?id=70036
Rich Bowen <rb...@apache.org> changed:
What |Removed |Added
----------------------------------------------------------------------------
Status|NEEDINFO |RESOLVED
Resolution|--- |FIXED
--- Comment #10 from Rich Bowen <rb...@apache.org> ---
Resolving. All issues addressed.
--
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 70036] URL-path definition unclear/misleading (Terms Used to Describe Directives, Mapping URLs to Filesystem Locations)
Posted by bu...@apache.org.
https://bz.apache.org/bugzilla/show_bug.cgi?id=70036
Philippe Cloutier <ch...@gmail.com> changed:
What |Removed |Added
----------------------------------------------------------------------------
Status|RESOLVED |REOPENED
Resolution|WONTFIX |---
--- Comment #6 from Philippe Cloutier <ch...@gmail.com> ---
The fourth paragraph of the mod_rewrite reference documentation’s Summary also
causes confusion between paths and query strings. It contains:
> The path generated by a rewrite rule can include a query string, or can lead to internal sub-processing, external request redirection, or internal proxy throughput.
>
A path can hardly contain a query string; what this means is the *substitution*
can include one, but that is already mentioned in the third paragraph, so I
suggest simply:
> A rewrite rule can lead to internal sub-processing, external request redirection, or internal proxy throughput.
(In reply to Rich Bowen from comment #5)
> What you're linking to there is not from a user support forum. That's my To
> Do list, for the refresh of the mod_rewrite guide. That's the list I've been
> working from for the past month.
The link is to the To Do list for mod_rewrite documentation. The last item in
the “HIGH — Widely asked, not covered” section mentions that users frequently
misunderstand what a rewrite rule’s pattern matches. That is presumably often
because URL-paths are misdefined. According to that To Do document, these pain
points were identified based on questions on a user support/discussion forum.
> I've re-read this ticket several times this morning.
Thank you for your attention
> I think you're saying that the text on
> https://httpd.apache.org/docs/trunk/en/mod/directive-dict.html#Syntax
> suggests that URL-path might include the port number?
That is point #2, which is indeed a problem, but given that ports are usually
not specified, I consider #4 more problematic.
> But then the suggested patch in "Comment 2" is to urlmapping.xml and
The patch I suggested in comment 2 fixes the case I reported in that comment.
It does not fix the initial case (from Description).
> And then you link to *my* todo list (which is not linked
> to from anywhere, and has only been in the repository for less than 2 weeks)
> as evidence that it's confusing.
It is not the TODO document itself which is evidence that it's confusing. It's
the questions which were compiled to fill that document.
> Philippe, your attention to detail has led to some good clarifications, but
> in this case, it does not.
I fail to see how details matter here; whether a URL’s path includes its port
and query string is *not* a detail.
> I'm closing this ticket again. The patch does not clarify, as I said in my
> earlier comment. It *removes* the clarification.
Please refrain from marking issues as resolved until they are. One’s
approval/disapproval or understanding of any unapplied patch does not determine
whether an issue is resolved. I appreciate the work you did, but until the
definition itself is fixed, I’m afraid adding a link there only reinforces the
misunderstanding.
--
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 70036] URL-path definition unclear/misleading (Terms Used to Describe Directives)
Posted by bu...@apache.org.
https://bz.apache.org/bugzilla/show_bug.cgi?id=70036
Philippe Cloutier <ch...@gmail.com> changed:
What |Removed |Added
----------------------------------------------------------------------------
Summary|URL-path definition |URL-path definition
|unclear/misleading (Terms |unclear/misleading (Terms
|Used to Describe |Used to Describe
|Directives, Mapping URLs to |Directives)
|Filesystem Locations) |
Status|RESOLVED |VERIFIED
--- Comment #11 from Philippe Cloutier <ch...@gmail.com> ---
The third points remains, but thank you very much Rich, that solves #1, #2 and
#4, which are the most important.
(In reply to Rich Bowen from comment #7)
> Right. That "High" ranking was assigned by an AI agent, not by me.
Well, the agent may have suggested it, but I hope the agent did not commit that
alone.
(In reply to Philippe Cloutier from comment #6)
> The fourth paragraph of the mod_rewrite reference documentation’s Summary
> also causes confusion between paths and query strings. It contains:
> > The path generated by a rewrite rule can include a query string, or can lead to internal sub-processing, external request redirection, or internal proxy throughput.
> >
This is fixed by r1934447.
Ticket #70088 follows up on the case reported in comment #2.
--
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 70036] URL-path definition unclear/misleading (Terms Used to Describe Directives, Mapping URLs to Filesystem Locations)
Posted by bu...@apache.org.
https://bz.apache.org/bugzilla/show_bug.cgi?id=70036
--- Comment #7 from Rich Bowen <rb...@apache.org> ---
Right. That "High" ranking was assigned by an AI agent, not by me. I'm not even
entirely sure what that particular line item means. Happy to delete it.
--
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 70036] URL-path definition unclear/misleading (Terms Used to Describe Directives, Mapping URLs to Filesystem Locations)
Posted by bu...@apache.org.
https://bz.apache.org/bugzilla/show_bug.cgi?id=70036
Rich Bowen <rb...@apache.org> changed:
What |Removed |Added
----------------------------------------------------------------------------
Status|REOPENED |NEEDINFO
--- Comment #9 from Rich Bowen <rb...@apache.org> ---
As with many of your tickets, I believe that this has been resolved but suspect
that you will feel differently
--
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 70036] Terms Used to Describe Directives: URL-path definition unclear/misleading
Posted by bu...@apache.org.
https://bz.apache.org/bugzilla/show_bug.cgi?id=70036
--- Comment #2 from Philippe Cloutier <ch...@gmail.com> ---
The main issue also affects Mapping URLs to Filesystem Locations, whose
DocumentRoot section contains:
> In deciding what file to serve for a given request, httpd's default behavior is to take the URL-Path for the request (the part of the URL following the hostname and port) and add it to the end of the DocumentRoot specified in your configuration files.
I recommend:
diff --git a/docs/manual/urlmapping.xml b/docs/manual/urlmapping.xml
--- docs/manual/urlmapping.xml
+++ docs/manual/urlmapping.xml
@@ -71,11 +71,10 @@
<section id="documentroot"><title>DocumentRoot</title>
<p>In deciding what file to serve for a given request, httpd's
- default behavior is to take the URL-Path for the request (the part
- of the URL following the hostname and port) and add it to the end
- of the <directive module="core">DocumentRoot</directive> specified
+ default behavior is to take the request’s <a
href="directive-dict.html#Syntax">URL-path</a>
+ and add it to the end of the <directive
module="core">DocumentRoot</directive> specified
in your configuration files. Therefore, the files and directories
underneath the <directive module="core">DocumentRoot</directive>
make up the basic document tree which will be visible from the
web.</p>
(In reply to Eric Covener from comment #1)
> not worth the churn
Please clarify what you mean
--
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 70036] Terms Used to Describe Directives: URL-path definition unclear/misleading
Posted by bu...@apache.org.
https://bz.apache.org/bugzilla/show_bug.cgi?id=70036
Eric Covener <co...@gmail.com> changed:
What |Removed |Added
----------------------------------------------------------------------------
Status|NEW |RESOLVED
Resolution|--- |WORKSFORME
--- Comment #1 from Eric Covener <co...@gmail.com> ---
not worth the churn
--
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 70036] URL-path definition unclear/misleading (Terms Used to Describe Directives, Mapping URLs to Filesystem Locations)
Posted by bu...@apache.org.
https://bz.apache.org/bugzilla/show_bug.cgi?id=70036
Philippe Cloutier <ch...@gmail.com> changed:
What |Removed |Added
----------------------------------------------------------------------------
Resolution|FIXED |---
Status|RESOLVED |REOPENED
--- Comment #4 from Philippe Cloutier <ch...@gmail.com> ---
(In reply to Rich Bowen from comment #3)
> I don't mind adding the link to directive-dict.html#Syntax (applied
> r1934093, 1934094)
Thank you Rich, but that leaves the definition (reported in the Description).
> Removing the parenthetical explainer is a step away from clarity. Not a fan
> of that.
I have nothing against explaining, but this depends on the explainer. The
current one is ambiguous, and this ambiguity is most likely to cause confusion.
According to AI, questions on an httpd support forum show some users putting
`?query` in their pattern:
https://github.com/apache/httpd/blob/968c776e122075b515e36b6d44278cad995d28ed/docs/manual/rewrite/TODO.md?plain=1#L84-L85
This must notably result from that parenthesis and/or issue #4.
--
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 70036] URL-path definition unclear/misleading (Terms Used to Describe Directives, Mapping URLs to Filesystem Locations)
Posted by bu...@apache.org.
https://bz.apache.org/bugzilla/show_bug.cgi?id=70036
--- Comment #8 from Rich Bowen <rb...@apache.org> ---
Oh, I see now. Yeah, that makes sense.
--
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 70036] URL-path definition unclear/misleading (Terms Used to Describe Directives, Mapping URLs to Filesystem Locations)
Posted by bu...@apache.org.
https://bz.apache.org/bugzilla/show_bug.cgi?id=70036
Philippe Cloutier <ch...@gmail.com> changed:
What |Removed |Added
----------------------------------------------------------------------------
Resolution|WORKSFORME |---
Summary|Terms Used to Describe |URL-path definition
|Directives: URL-path |unclear/misleading (Terms
|definition |Used to Describe
|unclear/misleading |Directives, Mapping URLs to
| |Filesystem Locations)
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 70036] URL-path definition unclear/misleading (Terms Used to Describe Directives, Mapping URLs to Filesystem Locations)
Posted by bu...@apache.org.
https://bz.apache.org/bugzilla/show_bug.cgi?id=70036
Rich Bowen <rb...@apache.org> changed:
What |Removed |Added
----------------------------------------------------------------------------
Resolution|--- |FIXED
Status|REOPENED |RESOLVED
--- Comment #3 from Rich Bowen <rb...@apache.org> ---
I don't mind adding the link to directive-dict.html#Syntax (applied r1934093,
1934094)
Removing the parenthetical explainer is a step away from clarity. Not a fan of
that.
--
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