doc: Typo fixes and other documentation improvements.

[ashd.git] / doc / dirplex.doc

diff --git a/doc/dirplex.doc b/doc/dirplex.doc
index 362a5d7..9d2240d 100644 (file)
--- a/doc/dirplex.doc
+++ b/doc/dirplex.doc
@@ -49,16 +49,20 @@ Mapping URLs into physical files is an iterative procedure, each step
 looking in one single physical directory, starting with 'DIR'. For
 each step, a path element is stripped off the beginning of the rest
 string and examined, the path element being either the leading part of
 looking in one single physical directory, starting with 'DIR'. For
 each step, a path element is stripped off the beginning of the rest
 string and examined, the path element being either the leading part of

-the rest string up until the first slash, or the entire rest string if
-it contains no slashes. If the rest string is empty, the directory
-being examined is considered the result of the mapping. Otherwise, any
-escape sequences in the path element under consideration are unescaped
-before examining it.
+the rest string up until (but not including) the first slash, or the
+entire rest string if it contains no slashes. If the rest string is
+empty, the directory being examined is considered the result of the
+mapping. Otherwise, any escape sequences in the path element under
+consideration are unescaped before examining it.

 
 If the path element names a directory in the current directory, the
 
 If the path element names a directory in the current directory, the

-procedure continues in that directory. If it names a file, that file
-is considered the result of the mapping (even if the rest string has
-not been exhausted yet).
+procedure continues in that directory, unless there is nothing left of
+the rest string, in which case *dirplex* responds with a HTTP 301
+redirect to the same URL, but ending with a slash. Otherwise, the
+remaining rest string begins with a slash, which is stripped off
+before continuing. If the path element names a file, that file is
+considered the result of the mapping (even if the rest string has not
+been exhausted yet).

 
 If the path element does not name anything in the directory under
 consideration, but contains no dots, then the directory is searched
 
 If the path element does not name anything in the directory under
 consideration, but contains no dots, then the directory is searched


@@ -122,7 +126,7 @@ as part of the word. Empty lines are ignored, and lines whose first
 character after leading whitespace is a hash character (`#`) are
 treated as comments and ignored.
 
 character after leading whitespace is a hash character (`#`) are
 treated as comments and ignored.
 

-The follow configuration directives are recognized:
+The following configuration directives are recognized:

 
 *include* ['FILENAME'...]::
 
 
 *include* ['FILENAME'...]::
 


@@ -185,7 +189,7 @@ The follow configuration directives are recognized:
        above is aborted as soon as the directory containing the
        `.htrc` file is encountered. The request is passed, with any
        remaining rest string, to the specified 'HANDLER', which must
        above is aborted as soon as the directory containing the
        `.htrc` file is encountered. The request is passed, with any
        remaining rest string, to the specified 'HANDLER', which must

-       by a named request handler specified either in the same
+       be a named request handler specified either in the same

        `.htrc` file or elsewhere. The *capture* directive accepts no
        follow-up lines. Note that the `X-Ash-File` header is not
        added to requests passed via *capture* directives.
        `.htrc` file or elsewhere. The *capture* directive accepts no
        follow-up lines. Note that the `X-Ash-File` header is not
        added to requests passed via *capture* directives.


@@ -220,11 +224,13 @@ The following rules are recognized:
 
 *pathname* 'PATTERN'...::
 
 
 *pathname* 'PATTERN'...::
 

-       Matches if the entire path (relative as considered from the
-       root directory being served) of the file under consideration
+       Matches if the entire path of the file under consideration

        matches any of the 'PATTERNs'. A 'PATTERN' is an ordinary glob
        pattern, except that slashes are not matched by wildcards. See
        matches any of the 'PATTERNs'. A 'PATTERN' is an ordinary glob
        pattern, except that slashes are not matched by wildcards. See

-       *fnmatch*(3) for more information.
+       *fnmatch*(3) for more information. If a *pathname* rule is
+       specified in a `.htrc` file, the path will be examined as
+       relative to the directory containing the `.htrc` file, rather
+       than to the root directory being served.

 
 *default*::
 
 
 *default*::
 


@@ -257,6 +263,22 @@ following actions are recognized:
        by a *fchild* stanza. This action exists mostly for
        convenience.
 
        by a *fchild* stanza. This action exists mostly for
        convenience.
 

+A *match* stanza may also contain any number of the following,
+optional directives:
+
+*set* 'HEADER' 'VALUE'::
+
+       If the *match* stanza is selected as the match for a file, the
+       named HTTP 'HEADER' in the request is set to 'VALUE' before
+       passing the request on to the specified handler.
+
+*xset* 'HEADER' 'VALUE'::
+
+       *xset* does exactly the same thing as *set*, except that
+         'HEADER' is automatically prepended with the `X-Ash-`
+         prefix. The intention is only to make configuration files
+         look nicer in this very common case.
+

 404 RESPONSES
 -------------
 
 404 RESPONSES
 -------------
 


@@ -266,7 +288,7 @@ A HTTP 404 response is sent to the client if
  * A path element is encountered during mapping which, after URL
    unescaping, either begins with a dot or contains slashes;
  * The mapping procedure finds a file which is neither a directory nor
  * A path element is encountered during mapping which, after URL
    unescaping, either begins with a dot or contains slashes;
  * The mapping procedure finds a file which is neither a directory nor

-   a regular file;
+   a regular file (or a symbolic link to any of the same);

  * An empty, non-final path element is encountered during mapping; or
  * The mapping procedure results in a file which is not matched by any
    *match* stanza.
  * An empty, non-final path element is encountered during mapping; or
  * The mapping procedure results in a file which is not matched by any
    *match* stanza.


@@ -287,9 +309,13 @@ EXAMPLES
 The *sendfile*(1) program can be used to serve HTML files as follows.
 
 --------
 The *sendfile*(1) program can be used to serve HTML files as follows.
 
 --------

+fchild send
+  exec sendfile
+

 match
 match

-  filename *.html
-  fork sendfile -c text/html
+  filename *.html *.htm
+  xset content-type text/html
+  handler send

 --------
 
 Assuming the PHP CGI interpreter is installed on the system, PHP
 --------
 
 Assuming the PHP CGI interpreter is installed on the system, PHP


@@ -324,9 +350,9 @@ match directory
 The following configuration can be placed in a `.htrc` file in order
 to dedicate the directory containing that file to some external SCGI
 script engine. Note that *callscgi*, and therefore the script engine
 The following configuration can be placed in a `.htrc` file in order
 to dedicate the directory containing that file to some external SCGI
 script engine. Note that *callscgi*, and therefore the script engine

-itself, is started in the directory itself, so that arbitrary code
-modules or data files can be put directly in that directory and easily
-found.
+itself, is started in the same directory, so that arbitrary code
+modules or data files can be put directly in that directory and be
+easily found.

 
 --------
 child foo
 
 --------
 child foo