From: André Malo Date: Sat, 12 Dec 2009 20:28:44 +0000 (+0000) Subject: revert r832627, because it uses invalid xml structure X-Git-Tag: 2.3.5~90 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=991dd648f9dc69dc69629ac2bdae1bdc6de39bd4;p=thirdparty%2Fapache%2Fhttpd.git revert r832627, because it uses invalid xml structure git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@889973 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/mod/mod_rewrite.html.en b/docs/manual/mod/mod_rewrite.html.en index 741c45720ff..1bf19c5cffc 100644 --- a/docs/manual/mod/mod_rewrite.html.en +++ b/docs/manual/mod/mod_rewrite.html.en @@ -94,11 +94,10 @@ URLs on the fly .htaccess file where you want to use RewriteRule directives.

The example below demonstrates how to map - http://example.com/myapp/index.html to - /home/www/example/newsite.html, in a .htaccess - file. This assumes that the content available at - http://example.com/ is on disk at - /home/www/example/.

+ http://example.com/myapp/index.html to + /home/www/example/newsite.html, in a .htaccess file. This + assumes that the content available at + http://example.com/ is on disk at /home/www/example/

 RewriteEngine On
 # The URL-path used to get to this context, not the filesystem path
@@ -120,45 +119,47 @@ RewriteRule ^index\.html$  newsite.html
 Status:Extension
 Module:mod_rewrite
 
-      
The RewriteCond 
-      directive defines a rule condition. One or more RewriteCond
-      conditions can precede a RewriteRule directive. The following rewrite rule is then 
-      used only if these conditions are met, and if the URI matches the pattern
-      specified in the rule.

-
-      
top

-

-
TestString

-      
-      
TestString can contain plain text, any of the 
-      following expanded constructs, or both.

+      
The RewriteCond directive defines a
+      rule condition. One or more RewriteCond
+      can precede a RewriteRule
+      directive. The following rule is then only used if both
+      the current state of the URI matches its pattern, and if these conditions are met.

+
+      
TestString is a string which can contain the
+      following expanded constructs in addition to plain text:

+
       
    
         
  • 
           RewriteRule backreferences: These are
           backreferences of the form $N
-          (1 <= N <= 9). They provide access to the grouped
-          parts of the current RewriteRule pattern. The grouped
-	  parts of the pattern are those in parentheses.
    • 
+          (0 <= N <= 9), which provide access to the grouped
+          parts (in parentheses) of the pattern, from the
+          RewriteRule which is subject to the current
+          set of RewriteCond conditions.
+        
         
  • 
           RewriteCond backreferences: These are
           backreferences of the form %N
-          (1 <= N <= 9). They provide access to the grouped
-	  parts of the last-matched RewriteCond pattern. The
-	  grouped parts of the pattern are those in parentheses.
    • 
+          (1 <= N <= 9), which provide access to the grouped
+          parts (again, in parentheses) of the pattern, from the last matched
+          RewriteCond in the current set
+          of conditions.
+        
         
  • 
           RewriteMap expansions: These are
           expansions of the form ${mapname:key|default}.
-          See the RewriteMap documentation 
-	  for more details.
+          See the documentation for
+          RewriteMap for more details.
         
    • 
         
  • 
-          Server variables: These are variables of
+          Server-Variables: These are variables of
           the form
-            %{ NAME_OF_VARIABLE },
-          where NAME_OF_VARIABLE is one of the server variables from
-	  the table below:
-	  
-	  
+            %{ NAME_OF_VARIABLE
+            }
+          where NAME_OF_VARIABLE can be a string taken
+          from the following list:
+
+          
    
           
             
    
               HTTP headers: connection & request: 
@@ -227,23 +228,34 @@ RewriteRule ^index\.html$  newsite.html
               
             
    
           
    
-	  

-	  
The following variables are specific to 
-	  mod_rewrite:

+
+                
These variables all
+                correspond to the similarly named HTTP
+                MIME-headers, C variables of the Apache server or
+                struct tm fields of the Unix system.
+                Most are documented elsewhere in the Manual or in
+                the CGI specification. Those that are special to
+                mod_rewrite include those below.

+        

                 

                   
IS_SUBREQ

 
-                  
Contains the text "true" if the request
-                  currently being processed is a sub-request, or
+                  
Will contain the text "true" if the request
+                  currently being processed is a sub-request,
                   "false" otherwise. Sub-requests may be generated
                   by modules that need to resolve additional files
                   or URIs in order to complete their tasks.

 
                   
API_VERSION

 
-                  
The version of the Apache module API contained in the
-                  current httpd build, as defined in
-		  include/ap_mmn.h.

+                  
This is the version of the Apache module API
+                  (the internal interface between server and
+                  module) in the current httpd build, as defined in
+                  include/ap_mmn.h. The module API version
+                  corresponds to the version of Apache in use (in
+                  the release version of Apache 1.3.14, for
+                  instance, it is 19990320:10), but is mainly of
+                  interest to module authors.

 
                   
THE_REQUEST

 
@@ -256,79 +268,108 @@ RewriteRule ^index\.html$  newsite.html
                   
REQUEST_URI

 
                   
The resource requested in the HTTP request
-                  line.

+                  line. (In the example above, this would be
+                  "/index.html".)
 
                   
REQUEST_FILENAME

 
-                  
The full local filesystem path of the file or
+                  
The full local filesystem path to the file or
                   script matching the request.

 
                   
HTTPS

 
-                  
Contains the text "on" if the connection is
-                  using SSL/TLS, or "off" otherwise. This variable
-                  does not depend on mod_ssl being loaded.

+                  
Will contain the text "on" if the connection is
+                  using SSL/TLS, or "off" otherwise.  (This variable
+                  can be safely used regardless of whether or not
+                  mod_ssl is loaded).

 
                 

 

+        
+      
 
-      
Note that the SCRIPT_FILENAME and 
-	      REQUEST_FILENAME
-        variables both contain the value of the
+      
Other things you should be aware of:

+
+      
    
+        
  1. 
+        
    The variables SCRIPT_FILENAME and REQUEST_FILENAME
+        contain the same value - the value of the
         filename field of the internal
-        request_rec structure.
-	If a substitution occurs and rewriting continues,
-        the value of both variables will be updated accordingly.
-	In a per-server context, before the
-        request is mapped to the filesystem, these variables contain the value
-	of REQUEST_URI, because the full filesystem path is not
-	yet known. To obtain the full filesystem
-        path of a request in a per-server context, use a URL-based
+        request_rec structure of the Apache server.
+        The first name is the commonly known CGI variable name
+        while the second is the appropriate counterpart of
+        REQUEST_URI (which contains the value of the
+        uri field of request_rec).
    
+        
    If a substitution occurred and the rewriting continues,
+        the value of both variables will be updated accordingly.
    
+        
    If used in per-server context (i.e., before the
+        request is mapped to the filesystem) SCRIPT_FILENAME and
+        REQUEST_FILENAME cannot contain the full local filesystem
+        path since the path is unknown at this stage of processing.
+        Both variables will initially contain the value of REQUEST_URI
+        in that case. In order to obtain the full local filesystem
+        path of the request in per-server context, use an URL-based
         look-ahead %{LA-U:REQUEST_FILENAME} to determine
-	the final value of REQUEST_FILENAME.
    
+        the final value of REQUEST_FILENAME.
    2. 
 
-	
    Other available variables include the following:
    
-	
    • 
-	%{ENV:variable}, where variable can be
-	any environment variable.
      • 
+        
    • 
+        %{ENV:variable}, where variable can be
+        any environment variable, is also available.
+        This is looked-up via internal
+        Apache structures and (if not found there) via
+        getenv() from the Apache server process.
      • 
 
         
    • 
-	%{SSL:variable}, where variable is the
+        %{SSL:variable}, where variable is the
         name of an SSL environment
-	variable. If mod_ssl is not loaded, this
-	will always expand to the empty string.
      • 
+        variable, can be used whether or not
+        mod_ssl is loaded, but will always expand to
+        the empty string if it is not.  Example:
+        %{SSL:SSL_CIPHER_USEKEYSIZE} may expand to
+        128.
+
         
    • 
-	%{HTTP:header}, where header can be
-	any HTTP MIME-header name. For example, 
-	%{HTTP:Proxy-Connection} is the value of the HTTP header
-        ``Proxy-Connection:''. If a HTTP header is used in a 
-	condition, and the condition evaluates to true, then that 
-	header is added to the Vary header of the response. This is used to 
-	ensure proper caching. 
-	If a previous condition has evaluated to true and the 
-	'ornext|OR' flag is in use, later
-	conditions are not evaluated, and therefore headers are not added to the
-	Vary header.
      • 
+        %{HTTP:header}, where header can be
+        any HTTP MIME-header name, can always be used to obtain the
+        value of a header sent in the HTTP request.
+        Example: %{HTTP:Proxy-Connection} is
+        the value of the HTTP header
+        ``Proxy-Connection:''.
+        
      If a HTTP header is used in a condition this header is added to
+        the Vary header of the response in case the condition evaluates to
+        to true for the request. It is not added if the
+        condition evaluates to false for the request. Adding the HTTP header
+        to the Vary header of the response is needed for proper caching.
      
+        
      It has to be kept in mind that conditions follow a short circuit
+        logic in the case of the 'ornext|OR' flag
+        so that certain conditions might not be evaluated at all.
      
+
         
    • 
-	%{LA-U:variable}, which is used to perform 
-        an internal URL-based sub-request, to determine the final
-        value of variable. This can be used to access the value of
-	a variable which is to be set in a later phase. For example, the
-	REMOTE_USER variable is set in the authorization phase of
-	processing. This comes after the URL translation phase, where rewrite
-	rules in httpd.conf are applied, but before the fixup
-	phase, where rewrite rules in a .htaccess file are applied.
-	Therefore, to obtain the value of the REMOTE_USER variable 
-	within httpd.conf, you must use %{LA-U:REMOTE_USER}. To obtain the value of the
-	REMOTE_USER variable within a .htaccess file,
-	simply use %{REMOTE_USER}
      • 
-      
    
-      

+        %{LA-U:variable} can be used for look-aheads which perform
+        an internal (URL-based) sub-request to determine the final
+        value of variable. This can be used to access
+        variable for rewriting which is not available at the current
+        stage, but will be set in a later phase.
+        
For instance, to rewrite according to the
+        REMOTE_USER variable from within the
+        per-server context (httpd.conf file) you must
+        use %{LA-U:REMOTE_USER} - this
+        variable is set by the authorization phases, which come
+        after the URL translation phase (during which mod_rewrite
+        operates).

+        
On the other hand, because mod_rewrite implements
+        its per-directory context (.htaccess file) via
+        the Fixup phase of the API and because the authorization
+        phases come before this phase, you just can use
+        %{REMOTE_USER} in that context.

+
+        
  • 
+        %{LA-F:variable} can be used to perform an internal
+        (filename-based) sub-request, to determine the final value
+        of variable. Most of the time, this is the same as
+        LA-U above.
    • 
+      
 
-      
    top
    
-
    
-
    CondPattern
    
-      
       
    CondPattern is the condition pattern,
        a regular expression which is applied to the
       current instance of the TestString.
@@ -500,7 +541,6 @@ RewriteRule  ^/$                 /homepage.std.html  [L]
         or your browser identifies itself as something non-standard), you get
         the std (standard) homepage.
    
 
-
    
 
 
    
 
    top
    
diff --git a/docs/manual/mod/mod_rewrite.xml b/docs/manual/mod/mod_rewrite.xml
index 9151086b976..4e75300c1c8 100644
--- a/docs/manual/mod/mod_rewrite.xml
+++ b/docs/manual/mod/mod_rewrite.xml
@@ -500,11 +500,10 @@ once!
       module="mod_rewrite">RewriteRule directives.
    
 
       
    The example below demonstrates how to map 
-      http://example.com/myapp/index.html to 
-      /home/www/example/newsite.html, in a .htaccess 
-      file. This assumes that the content available at
-      http://example.com/ is on disk at 
-      /home/www/example/.
    
+      http://example.com/myapp/index.html to 
+      /home/www/example/newsite.html, in a .htaccess file. This 
+      assumes that the content available at
+      http://example.com/ is on disk at /home/www/example/
    
 
 
     RewriteEngine On
@@ -529,46 +528,49 @@ RewriteRule ^index\.html$  newsite.html
 FileInfo
 
 
-      
    The RewriteCond 
-      directive defines a rule condition. One or more RewriteCond
-      conditions can precede a RewriteRule directive. The following rewrite rule is then 
-      used only if these conditions are met, and if the URI matches the pattern
-      specified in the rule.
    
-
-      
    
-      TestString
-      
    TestString can contain plain text, any of the 
-      following expanded constructs, or both.
    
+      
    The RewriteCond directive defines a
+      rule condition. One or more RewriteCond
+      can precede a RewriteRule
+      directive. The following rule is then only used if both
+      the current state of the URI matches its pattern, and if these conditions are met.
    
+
+      
    TestString is a string which can contain the
+      following expanded constructs in addition to plain text:
    
+
       
      
         
    • 
           RewriteRule backreferences: These are
           backreferences of the form $N
-          (1 <= N <= 9). They provide access to the grouped
-          parts of the current RewriteRule pattern. The grouped
-	  parts of the pattern are those in parentheses.
      • 
+          (0 <= N <= 9), which provide access to the grouped
+          parts (in parentheses) of the pattern, from the
+          RewriteRule which is subject to the current
+          set of RewriteCond conditions.
+        
         
    • 
           RewriteCond backreferences: These are
           backreferences of the form %N
-          (1 <= N <= 9). They provide access to the grouped
-	  parts of the last-matched RewriteCond pattern. The
-	  grouped parts of the pattern are those in parentheses.
      • 
+          (1 <= N <= 9), which provide access to the grouped
+          parts (again, in parentheses) of the pattern, from the last matched
+          RewriteCond in the current set
+          of conditions.
+        
         
    • 
           RewriteMap expansions: These are
           expansions of the form ${mapname:key|default}.
-          See the RewriteMap documentation 
-	  for more details.
+          See the documentation for
+          RewriteMap for more details.
         
      • 
         
    • 
-          Server variables: These are variables of
+          Server-Variables: These are variables of
           the form
-            %{ NAME_OF_VARIABLE },
-          where NAME_OF_VARIABLE is one of the server variables from
-	  the table below:
-	  
-	  
+            %{ NAME_OF_VARIABLE
+            }
+          where NAME_OF_VARIABLE can be a string taken
+          from the following list:
+
+          
      
            
@@ -638,23 +640,34 @@ RewriteRule ^index\.html$  newsite.html
               
      
           
             
      
             
      
           
      
-	  
    
-	  
    The following variables are specific to 
-	  mod_rewrite:
    
+
+                
    These variables all
+                correspond to the similarly named HTTP
+                MIME-headers, C variables of the Apache server or
+                struct tm fields of the Unix system.
+                Most are documented elsewhere in the Manual or in
+                the CGI specification. Those that are special to
+                mod_rewrite include those below.
    
+        
                 
    
                   
    IS_SUBREQ
    
 
-                  
    Contains the text "true" if the request
-                  currently being processed is a sub-request, or
+                  
    Will contain the text "true" if the request
+                  currently being processed is a sub-request,
                   "false" otherwise. Sub-requests may be generated
                   by modules that need to resolve additional files
                   or URIs in order to complete their tasks.
    
 
                   
    API_VERSION
    
 
-                  
    The version of the Apache module API contained in the
-                  current httpd build, as defined in
-		  include/ap_mmn.h.
    
+                  
    This is the version of the Apache module API
+                  (the internal interface between server and
+                  module) in the current httpd build, as defined in
+                  include/ap_mmn.h. The module API version
+                  corresponds to the version of Apache in use (in
+                  the release version of Apache 1.3.14, for
+                  instance, it is 19990320:10), but is mainly of
+                  interest to module authors.
    
 
                   
    THE_REQUEST
    
 
@@ -667,78 +680,108 @@ RewriteRule ^index\.html$  newsite.html
                   
    REQUEST_URI
    
 
                   
    The resource requested in the HTTP request
-                  line.
    
+                  line. (In the example above, this would be
+                  "/index.html".)
 
                   
    REQUEST_FILENAME
    
 
-                  
    The full local filesystem path of the file or
+                  
    The full local filesystem path to the file or
                   script matching the request.
    
 
                   
    HTTPS
    
 
-                  
    Contains the text "on" if the connection is
-                  using SSL/TLS, or "off" otherwise. This variable
-                  does not depend on mod_ssl being loaded.
    
+                  
    Will contain the text "on" if the connection is
+                  using SSL/TLS, or "off" otherwise.  (This variable
+                  can be safely used regardless of whether or not
+                  mod_ssl is loaded).
    
 
                 
    
     
+        
+      
+
+      
    Other things you should be aware of:
    
 
-      
    Note that the SCRIPT_FILENAME and 
-	      REQUEST_FILENAME
-        variables both contain the value of the
+      
      
+        
    1. 
+        
      The variables SCRIPT_FILENAME and REQUEST_FILENAME
+        contain the same value - the value of the
         filename field of the internal
-        request_rec structure.
-	If a substitution occurs and rewriting continues,
-        the value of both variables will be updated accordingly.
-	In a per-server context, before the
-        request is mapped to the filesystem, these variables contain the value
-	of REQUEST_URI, because the full filesystem path is not
-	yet known. To obtain the full filesystem
-        path of a request in a per-server context, use a URL-based
+        request_rec structure of the Apache server.
+        The first name is the commonly known CGI variable name
+        while the second is the appropriate counterpart of
+        REQUEST_URI (which contains the value of the
+        uri field of request_rec).
      
+        
      If a substitution occurred and the rewriting continues,
+        the value of both variables will be updated accordingly.
      
+        
      If used in per-server context (i.e., before the
+        request is mapped to the filesystem) SCRIPT_FILENAME and
+        REQUEST_FILENAME cannot contain the full local filesystem
+        path since the path is unknown at this stage of processing.
+        Both variables will initially contain the value of REQUEST_URI
+        in that case. In order to obtain the full local filesystem
+        path of the request in per-server context, use an URL-based
         look-ahead %{LA-U:REQUEST_FILENAME} to determine
-	the final value of REQUEST_FILENAME.
      
+        the final value of REQUEST_FILENAME.
      2. 
 
-	
      Other available variables include the following:
      
-	
      • 
-	%{ENV:variable}, where variable can be
-	any environment variable.
        • 
+        
      • 
+        %{ENV:variable}, where variable can be
+        any environment variable, is also available.
+        This is looked-up via internal
+        Apache structures and (if not found there) via
+        getenv() from the Apache server process.
        • 
 
         
      • 
-	%{SSL:variable}, where variable is the
+        %{SSL:variable}, where variable is the
         name of an SSL environment
-	variable. If mod_ssl is not loaded, this
-	will always expand to the empty string.
        • 
+        variable, can be used whether or not
+        mod_ssl is loaded, but will always expand to
+        the empty string if it is not.  Example:
+        %{SSL:SSL_CIPHER_USEKEYSIZE} may expand to
+        128.
+
         
      • 
-	%{HTTP:header}, where header can be
-	any HTTP MIME-header name. For example, 
-	%{HTTP:Proxy-Connection} is the value of the HTTP header
-        ``Proxy-Connection:''. If a HTTP header is used in a 
-	condition, and the condition evaluates to true, then that 
-	header is added to the Vary header of the response. This is used to 
-	ensure proper caching. 
-	If a previous condition has evaluated to true and the 
-	'ornext|OR' flag is in use, later
-	conditions are not evaluated, and therefore headers are not added to the
-	Vary header.
        • 
+        %{HTTP:header}, where header can be
+        any HTTP MIME-header name, can always be used to obtain the
+        value of a header sent in the HTTP request.
+        Example: %{HTTP:Proxy-Connection} is
+        the value of the HTTP header
+        ``Proxy-Connection:''.
+        
        If a HTTP header is used in a condition this header is added to
+        the Vary header of the response in case the condition evaluates to
+        to true for the request. It is not added if the
+        condition evaluates to false for the request. Adding the HTTP header
+        to the Vary header of the response is needed for proper caching.
        
+        
        It has to be kept in mind that conditions follow a short circuit
+        logic in the case of the 'ornext|OR' flag
+        so that certain conditions might not be evaluated at all.
        
+
         
      • 
-	%{LA-U:variable}, which is used to perform 
-        an internal URL-based sub-request, to determine the final
-        value of variable. This can be used to access the value of
-	a variable which is to be set in a later phase. For example, the
-	REMOTE_USER variable is set in the authorization phase of
-	processing. This comes after the URL translation phase, where rewrite
-	rules in httpd.conf are applied, but before the fixup
-	phase, where rewrite rules in a .htaccess file are applied.
-	Therefore, to obtain the value of the REMOTE_USER variable 
-	within httpd.conf, you must use %{LA-U:REMOTE_USER}. To obtain the value of the
-	REMOTE_USER variable within a .htaccess file,
-	simply use %{REMOTE_USER}
        • 
-      
      
-      
    
+        %{LA-U:variable} can be used for look-aheads which perform
+        an internal (URL-based) sub-request to determine the final
+        value of variable. This can be used to access
+        variable for rewriting which is not available at the current
+        stage, but will be set in a later phase.
+        
    For instance, to rewrite according to the
+        REMOTE_USER variable from within the
+        per-server context (httpd.conf file) you must
+        use %{LA-U:REMOTE_USER} - this
+        variable is set by the authorization phases, which come
+        after the URL translation phase (during which mod_rewrite
+        operates).
    
+        
    On the other hand, because mod_rewrite implements
+        its per-directory context (.htaccess file) via
+        the Fixup phase of the API and because the authorization
+        phases come before this phase, you just can use
+        %{REMOTE_USER} in that context.
    
+
+        
  • 
+        %{LA-F:variable} can be used to perform an internal
+        (filename-based) sub-request, to determine the final value
+        of variable. Most of the time, this is the same as
+        LA-U above.
    • 
+      
 
-      
    
-      CondPattern
       
    CondPattern is the condition pattern,
        a regular expression which is applied to the
       current instance of the TestString.
@@ -914,7 +957,6 @@ RewriteRule  ^/$                 /homepage.std.html  [L]
         or your browser identifies itself as something non-standard), you get
         the std (standard) homepage.
    
 
-