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/08 22:39:39 UTC
[Bug 70033] New: mod_rewrite reference misqualifies guide as "detailed mod_rewrite documentation”
https://bz.apache.org/bugzilla/show_bug.cgi?id=70033
Bug ID: 70033
Summary: mod_rewrite reference misqualifies guide as "detailed
mod_rewrite documentation”
Product: Apache httpd-2
Version: 2.5-HEAD
Hardware: PC
URL: https://httpd.apache.org/docs/trunk/en/mod/mod_rewrite
.html
Status: NEW
Severity: normal
Priority: P2
Component: Documentation
Assignee: docs@httpd.apache.org
Reporter: chealer@gmail.com
Target Milestone: ---
The Summary in the mod_rewrite reference ends with:
> Further details, discussion, and examples, are provided in the detailed mod_rewrite documentation.
“detailed mod_rewrite documentation” displays as a link to the rewriting guide
at https://httpd.apache.org/docs/trunk/en/rewrite/
Featuring such a link is great, since new users should read the guide before
trying to understand the reference. But the label is misleading, suggesting the
reference provides an introduction to a detailed guide.
I recommend changing to:
> The mod_rewrite guide provides an introduction, examples, applications and details.
…with the link moved to “The mod_rewrite guide”.
However, the summary and that index page are really the same. For example, when
the index says:
> It supports an unlimited number of rules and an unlimited number of attached rule conditions for each rule to provide a really flexible and powerful URL manipulation mechanism.
…the summary reads:
> mod_rewrite provides a flexible and powerful way to manipulate URLs using an unlimited number of rules. Each rule can have an unlimited number of attached rule conditions, to allow you to rewrite URL based on server variables, environment variables, HTTP headers, or time stamps.
It would be best to merge them.
🅭🄍: 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 70033] mod_rewrite reference misqualifies guide as "detailed mod_rewrite documentation”
Posted by bu...@apache.org.
https://bz.apache.org/bugzilla/show_bug.cgi?id=70033
--- Comment #4 from Philippe Cloutier <ch...@gmail.com> ---
Greetings Rich,
(In reply to Rich Bowen from comment #3)
> I remain unclear what change you are suggesting here.
I suggested 3 alternatives:
1. In the Description, the simple fix of relabeling the link (and ideally
rewrite the sentence).
2. In the Description and comment #2), merging the redundant Summary and the
“Guide to Apache mod_rewrite” page so they read the same.
3. In comment #2, merging both the “Guide to Apache mod_rewrite” and “Apache
mod_rewrite Introduction” pages into the reference.
> I will note, however, that the stuff in /howto is intended to be a
> completely different tone than the formal comprehensive module documentation
> in /mod. The latter is a reference manual.
I did not refer to anything in /howto in this ticket (although I guess a couple
pages of the guide can be considered howtos).
--
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 70033] mod_rewrite reference misqualifies guide as "detailed mod_rewrite documentation”
Posted by bu...@apache.org.
https://bz.apache.org/bugzilla/show_bug.cgi?id=70033
--- Comment #3 from Rich Bowen <rb...@apache.org> ---
I remain unclear what change you are suggesting here.
I will note, however, that the stuff in /howto is intended to be a completely
different tone than the formal comprehensive module documentation in /mod. The
latter is a reference manual. The former is tutorial. The distinction is
intentional. Yes, some of the docs blur the line, but for topics where we have
dedicated tutorial-style documentation (authnz, rewrite, ssl, and so on) we try
to have that distinction, and will over time be moving towards making that
distinction crisper, not blurrier.
--
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 70033] mod_rewrite reference misqualifies guide as "detailed mod_rewrite documentation”
Posted by bu...@apache.org.
https://bz.apache.org/bugzilla/show_bug.cgi?id=70033
Rich Bowen <rb...@apache.org> changed:
What |Removed |Added
----------------------------------------------------------------------------
Status|REOPENED |RESOLVED
Resolution|--- |FIXED
--- Comment #10 from Rich Bowen <rb...@apache.org> ---
This ticket has gone way off the rails, and wandered into meta-discussion.
I have resolved, to the best of my ability, the issues called out in this
ticket, and continuing to reopen it with slight variations has, once again,
resulted in a very frustrating interaction.
I *think* that the original statement is objecting to calling
https://httpd.apache.org/docs/trunk/rewrite/ "the detailed mod_rewrite
documentation" - which is what that resource is. Whether we call it a Guide, or
a Howto, or a Tutorial, is largely arbitrary, and was a decision that I made
more than 20 years ago (21 years, 2 months, to be more specific) and just
doesn't seem worth arguing about at this point. Whatever we call it, it is
detailed documentation that supplements the reference manual - which is what it
says in the doc.
I simply cannot fathom why we are arguing about this.
Meanwhile, what I am personally focused on is described in some detail here -
https://httpd.apache.org/docs/trunk/rewrite/TODO.md - and will, I believe,
bring genuine improvement to this set of documentation, whatever we choose to
call it.
I do believe we're done here. I do believe that I have addressed the issue as
described, within the bounds of my writer's prerogative. I hope that this
adequately explains my reasoning, and the fix that I have applied, and removes
the need to continually reopen this ticket.
Can we be done here?
--
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 70033] mod_rewrite reference misqualifies guide as "detailed mod_rewrite documentation”
Posted by bu...@apache.org.
https://bz.apache.org/bugzilla/show_bug.cgi?id=70033
Joe Orton <jo...@redhat.com> changed:
What |Removed |Added
----------------------------------------------------------------------------
Status|REOPENED |RESOLVED
Resolution|--- |FIXED
--- Comment #8 from Joe Orton <jo...@redhat.com> ---
Philippe, you are abusing the goodwill of maintainers here by persisting to
argue in issues with what look frankly like very trivial concerns and
nit-picking.
Please use the mailing list if you want to have open discussion about these
matters, or simply stop arguing for the sake of arguing.
--
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 70033] mod_rewrite reference misqualifies guide as "detailed mod_rewrite documentation”
Posted by bu...@apache.org.
https://bz.apache.org/bugzilla/show_bug.cgi?id=70033
--- Comment #5 from Rich Bowen <rb...@apache.org> ---
All of the stuff in /ssl, /rewrite and /howto are designated "howtos" or
"tutorials", while the stuff in /mod are considered reference manuals. They are
intended to have different styles, with the reference being "just the facts"
with a little commentary about best practice, and the tutorials being more
narrative, conversational, and hand-holding. I know this because I wrote them
with this intent. Before we had those directories, it was just the reference
documentation. Yes, this voice has drifted over the years, and that's fine, but
that is and was the intent.
So perhaps you can see why I remain confused as to what pages exactly you are
talking about. But I *think* you're talking about content in the /rewrite
directory. Yes?
However, I will read all of this carefully and try to figure out what passages
on which pages you're talking about.
--
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 70033] mod_rewrite reference misqualifies guide as "detailed mod_rewrite documentation”
Posted by bu...@apache.org.
https://bz.apache.org/bugzilla/show_bug.cgi?id=70033
Philippe Cloutier <ch...@gmail.com> changed:
What |Removed |Added
----------------------------------------------------------------------------
Status|RESOLVED |REOPENED
Resolution|FIXED |---
--- Comment #9 from Philippe Cloutier <ch...@gmail.com> ---
Greetings Joe,
(In reply to Joe Orton from comment #8)
> Philippe, you are abusing the goodwill of maintainers here by persisting to
> argue in issues with what look frankly like very trivial concerns and
> nit-picking.
Everyone has different quality standards, but one thing we require from
everyone is respect. If you have concerns about a contributor’s general
behavior and think you can communicate them in a respectful manner, please
voice them in an appropriate forum rather than diverting content discussions.
> Please use the mailing list if you want to have open discussion about these
> matters, or simply stop arguing for the sake of arguing.
Please see our conduct guidelines, in particular #2, #3 and #5. If you want an
open discussion about a contributor’s general behavior, thank you for doing
that on a mailing list or some appropriate forum, so existing discussions are
not derailed.
Interventions in httpd or any ASF project are expected to be constructive.
Furthermore, when you mark an issue as fixed, please explain how it was fixed.
--
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 70033] mod_rewrite reference misqualifies guide as "detailed mod_rewrite documentation”
Posted by bu...@apache.org.
https://bz.apache.org/bugzilla/show_bug.cgi?id=70033
--- Comment #2 from Philippe Cloutier <ch...@gmail.com> ---
Greetings Rich,
I guess that last recommendation was not entirely clear.
My biggest recommendation from yesterday was to make the Summary section
(currently, the first 5 paragraphs) of the “Apache Module mod_rewrite” page the
same as the “Guide to Apache mod_rewrite” page at
https://httpd.apache.org/docs/trunk/en/rewrite/
Currently, if one follows the "detailed mod_rewrite documentation” link from
the former to the latter, one ends up reading 2 highly redundant functional
descriptions of mod_rewrite.
The objective of the above recommendations is to achieve goal #3 of
https://bz.apache.org/bugzilla/show_bug.cgi?id=70032#c2
I made more research and would like to propose a more ambitious restructuring:
merging both the “Guide to Apache mod_rewrite” and “Apache mod_rewrite
Introduction” pages into the reference.
There are several precedents for having considerable introductory material in
module reference pages, notably:
https://httpd.apache.org/docs/trunk/en/mod/event.html
https://httpd.apache.org/docs/trunk/en/mod/mod_authn_dbd.html
https://httpd.apache.org/docs/trunk/en/mod/mod_authnz_fcgi.html
https://httpd.apache.org/docs/trunk/en/mod/mod_auth_form.html
The best example I found is mod_authnz_ldap:
https://httpd.apache.org/docs/trunk/en/mod/mod_authnz_ldap.html
Doing that would ensure that when readers land on the RewriteRule directive
specification, start head-banging, think “Wait, I guess I should begin from the
start” and hit Home, they would immediately get to an introduction equipping
them sufficiently to digest the rest, without having to notice the right link.
--
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 70033] mod_rewrite reference misqualifies guide as "detailed mod_rewrite documentation”
Posted by bu...@apache.org.
https://bz.apache.org/bugzilla/show_bug.cgi?id=70033
Rich Bowen <rb...@apache.org> changed:
What |Removed |Added
----------------------------------------------------------------------------
OS| |All
--- Comment #1 from Rich Bowen <rb...@apache.org> ---
I've read this several times and I cannot figure out what your are suggesting
that we merge. Can you say explicitly "merge x and y" here?
--
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 70033] mod_rewrite reference misqualifies guide as "detailed mod_rewrite documentation”
Posted by bu...@apache.org.
https://bz.apache.org/bugzilla/show_bug.cgi?id=70033
Rich Bowen <rb...@apache.org> changed:
What |Removed |Added
----------------------------------------------------------------------------
Resolution|--- |FIXED
Status|NEW |RESOLVED
--- Comment #6 from Rich Bowen <rb...@apache.org> ---
Ok, over coffee this morning, and rereading your various tickets, I think I
have finally understood what you're going for.
I've committed r1934081 which is an updated index file and a TODO of other
changes that seem useful.
The goal is to treat /readme as one cohesive "document" - a multi-chapter book.
I've started by analyzing the overlaps (there are a few) and seeing how we can
improve this with cross-references and updated diagrams.
I am doing this work only in trunk at this time, and I'll move it over to 2.4
when we're happy with it.
Meanwhile, I believe this specific ticket is addressed, albeit perhaps not in
the way that you intended.
--
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 70033] mod_rewrite reference misqualifies guide as "detailed mod_rewrite documentation”
Posted by bu...@apache.org.
https://bz.apache.org/bugzilla/show_bug.cgi?id=70033
Philippe Cloutier <ch...@gmail.com> changed:
What |Removed |Added
----------------------------------------------------------------------------
Resolution|FIXED |---
Status|RESOLVED |REOPENED
--- Comment #7 from Philippe Cloutier <ch...@gmail.com> ---
(In reply to Rich Bowen from comment #5)
> All of the stuff in /ssl, /rewrite and /howto are designated "howtos" or
> "tutorials", while the stuff in /mod are considered reference manuals.
I don't see any such designation. 2 of these pages *are* indeed howto material,
but the collection is designated as a "guide", and most of it is indeed a
topical guide, with 1 reference page and these howto pages.
> So perhaps you can see why I remain confused as to what pages exactly you
> are talking about. But I *think* you're talking about content in the
> /rewrite directory. Yes?
I am not sure what explains the confusion, no. The page with the basic problem
is indicated in the URL field. But the other pages are indeed in that
directory.
To be perfectly clear:
* “The Summary in the mod_rewrite reference” is at
https://httpd.apache.org/docs/trunk/en/mod/mod_rewrite.html.
* The “Guide to Apache mod_rewrite” page, which I also referred to as “that
index page”, is at https://httpd.apache.org/docs/trunk/en/rewrite/.
* The “Apache mod_rewrite Introduction” page is at
https://httpd.apache.org/docs/trunk/en/rewrite/intro.html.
> However, I will read all of this carefully and try to figure out what
> passages on which pages you're talking about.
Thanks, but I don't mind clarifying which pages my reports refer to if that can
be clearer. However, if I may, I *was* disappointed when I read you “remain[ed]
unclear what change [I was] suggesting here.”
It took me many minutes of reflection to guess what could be unclear in my
suggestions, and all of the effort I made appears to have been wrong in the
end. The huge effort you keep doing on documentation―in particular on
rewriting―is highly appreciated, and I know you solved multiple issues before I
even reported them, but it still took multiple person-days to report and follow
up to all these tickets. I know the antiquated ITS engine is not helping, but I
can assure you I take a lot of care to make my reports as clear as possible,
and would appreciate some hints on how to improve if I fail.
(In reply to Rich Bowen from comment #6)
> Ok, over coffee this morning, and rereading your various tickets, I think I
> have finally understood what you're going for.
>
> I've committed r1934081 which is an updated index file and a TODO of other
> changes that seem useful.
>
> The goal is to treat /readme as one cohesive "document" - a multi-chapter
> book. I've started by analyzing the overlaps (there are a few) and seeing
> how we can improve this with cross-references and updated diagrams.
I am not sure what you mean by “/readme”, but thank you very much.
One notable omission in the TODO is overlap between the “Apache HTTP Server
Tutorial: .htaccess files” and “Per-directory Rewrites” (and probably others).
A couple comments on the addition:
> This guide supplements <a href="../mod/mod_rewrite.html">the reference manual</a> with annotated examples, conceptual explanations, and practical advice.
1. I would not call mod_rewrite.html "the reference manual". My understanding
is that the reference manual consists of all reference pages. The sitemap calls
it “mod_rewrite reference documentation”.
2. “This guide supplements” suggests the reference page should be read before
the guide, while in reality, at least the introduction should be read before
the reference.
> Meanwhile, I believe this specific ticket is addressed, albeit perhaps not
> in the way that you intended.
I discussed a couple of related issues in this ticket. Your change fully
addresses the duplication I highlighted. However, the original/core issue is
how the reference qualifies the guide, and that issue remains. The label still
implies that the reference is not part of mod_rewrite documentation, or that it
is less detailed than the guide, which is not the case.
--
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