Improve documentation for directive "RewriteRule"

[Markus Elfring <Ma...@web.de>]

Hallo,

I suggest to enhance the documentation for the directive "RewriteRule".

1. http://www.apacheref.com/ref/mod_rewrite/RewriteRule.html
Each parameter should be described in a separate section to improve the readability.

1.1 url-new
Please add a link for the complete explanation to the url-pattern.
- How big can the numbers for back-references be?
- List of server variables

1.2 flags
The flag arguments are described in a single paragraph. I would prefer an ordered list or table.


2. use cases
2.1 redirections to scripts
Please show examples how additional values can be passed to the url-new argument.
A link to a description for the settings (e. g. rights, properties, programming language) to execute scripts would help.

2.2 content regeneration mechanism
I am very interested in the feature "On-the-fly Content-Regeneration" that is described shortly in the document "http://httpd.apache.org/docs-2.1/misc/rewriteguide.html.
(The feature "Document With Autorefresh" has got a Perl code example. A similar one might help for the other use case.)

2.2.1 parameter passing
I'm not sure if one of the following rules would be the solution.
RewriteCond %{REQUEST_FILENAME}   !-s
RewriteRule ^.+          restore.cgi?file=%{REQUEST_FILENAME}   [T=application/x-httpd-cgi,L]
RewriteRule ^.+          restore.php   [T=application/php,env=file=%{REQUEST_FILENAME},L]
RewriteRule ^.+          restore.php   [T=application/php,qsappend=name=%{REQUEST_FILENAME},L]

2.2.2 script execution
Does the apache webserver care about how often this CGI script may
be called for the missing file at the same time?
If it does not prevent that the script is called for the same file in parallel, this check must be performed by the script as an server application. Each regeneration request must be put into a waiting queue until the missing file will be created.

2.2.3 output
Why must there be output "additionally to its STDOUT"?
Is it not enough to create a new file with valid content?

Would you like to look at the forum "http://www.apacheadmin.com/talk/index.cgi?action=Article&article=105", too?
 
Sincerely,
Markus Elfring

Re: Improve mod_rewrite documentation

[Markus Elfring <Ma...@web.de>]

Thanks.

1. The description "http://httpd.apache.org/docs-2.1/mod/mod_rewrite.html" is better formatted than "apacheref.com".

2. Has anybody requested a syntax that shows the ruleset processing directly?
I see that it would be easier to understand to specify RewriteConds after the pattern of RewriteRules.

3. I assume that the quoting of special characters is done with a backslash character. I do not know a "slosh".

4. I would like to see a section "related or recommended reading" at the bottom.
- URL Rewriting Guide
- more practical solutions, use cases
- books
- partner sites
- mailing list, forum, news

5. I am missing explanations about concurrent and parallel execution of RewriteRules between web server requests.
5.1 How much has a called script got to do with mutual exclusion or synchronization of the processing?
5.2 Is there a program available that provides a safe environment (e. g. waiting queues, mutexes)?
5.3 Can a script achieve to perform a function only once even if several request want it to be done simultanously because the result will be the same for all requests in a time period?

6. Would you like to show relations to design patterns?
6.1 Reactor
6.2 Dispatcher
6.3 Notifier
6.4 Acceptor-Connector
6.5 Command-Processor
6.6 Service Handler



----- Original Message ----- 
From: "André Malo" <nd...@perlig.de>
To: <do...@httpd.apache.org>
Sent: Friday, August 01, 2003 6:23 PM
Subject: Re: Improve documentation for directive "RewriteRule"


> > I suggest to enhance the documentation for the directive "RewriteRule".
> > 
> > 1. http://www.apacheref.com/ref/mod_rewrite/RewriteRule.html
> 
> The httpd-docs project has no relation to the page you mentioned. The official
> documentation can be found at
> <http://httpd.apache.org/docs-2.0/mod/mod_rewrite.html> or
> <http://httpd.apache.org/docs/mod/mod_rewrite.html>
> 
> However, a mod_rewrite-docs-improvement is planned and we'll take care of your
> comments.

Re: Improve documentation for directive "RewriteRule"

[André Malo <nd...@perlig.de>]

* Markus Elfring wrote:

> I suggest to enhance the documentation for the directive "RewriteRule".
> 
> 1. http://www.apacheref.com/ref/mod_rewrite/RewriteRule.html

The httpd-docs project has no relation to the page you mentioned. The official
documentation can be found at
<http://httpd.apache.org/docs-2.0/mod/mod_rewrite.html> or
<http://httpd.apache.org/docs/mod/mod_rewrite.html>

However, a mod_rewrite-docs-improvement is planned and we'll take care of your
comments.

Thanks.

nd

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org