X-Git-Url: http://www.dolda2000.com/gitweb/?a=blobdiff_plain;f=doc%2Fdirplex.doc;h=7d1e41fea0a4e1793d6a25f9fd7a724eba62ecb5;hb=aa7e44069384016c57c417904bb45f6fa554981a;hp=cc243e06f43cd0781ac2e1d999411a8a990daf35;hpb=67223ca4e1f84229c542db957fbd04b7acc0220b;p=ashd.git

diff --git a/doc/dirplex.doc b/doc/dirplex.doc
index cc243e0..7d1e41f 100644
--- a/doc/dirplex.doc
+++ b/doc/dirplex.doc
@@ -55,11 +55,10 @@ being examined is considered the result of the mapping. Otherwise, any
 escape sequences in the path element under consideration are unescaped
 before examining it.
 
-Any path element that begins with a dot is considered invalid and
-results in a 404 response to the client. 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).
+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).
 
 If the path element does not name anything in the directory under
 consideration, but contains no dots, then the directory is searched
@@ -75,17 +74,19 @@ index file name contains no dots and there is no exact match, then,
 again, the directory is searched for a file whose name before the
 first dot matches the index file name.
 
+See also 404 RESPONSES below.
+
 CONFIGURATION
 -------------
 
 Configuration in *dirplex* comes from several sources. When *dirplex*
 starts, unless the *-N* option is given, it tries to find a global
 configuration file named `dirplex.rc`. It looks in all directories
-named by the *PATH* environment variable, appended with `../etc`. For
-example, then, if *PATH* is `/usr/local/bin:/bin:/usr/bin`, the
-directories `/usr/local/etc`, `/etc` and `/usr/etc` are searched for
-`dirplex.rc`, in that order. Only the first file found is used, should
-there exist several.
+named by the *PATH* environment variable, appended with
+`../etc/ashd`. For example, then, if *PATH* is
+`/usr/local/bin:/bin:/usr/bin`, the directories `/usr/local/etc/ashd`,
+`/etc/ashd` and `/usr/etc/ashd` are searched for `dirplex.rc`, in that
+order. Only the first file found is used, should there exist several.
 
 If the *-c* option is given to *dirplex*, it too specifies a
 configuration file to load. If the name given contains any slashes, it
@@ -123,6 +124,16 @@ treated as comments and ignored.
 
 The follow configuration directives are recognized:
 
+*include* ['FILENAME'...]::
+
+	Read the the named files and act as if their contents stood in
+	place of the *include* stanza. A 'FILENAME' may be a glob
+	pattern, in which case all matching files are used, sorted by
+	their filenames. If a 'FILENAME' is a relative path, it is
+	treated relative to the directory containing the file from
+	which the *include* stanza was read, even if the inclusion has
+	been nested. Inclusions may be nested to any level.
+
 *index-file* ['FILENAME'...]::
 
 	The given 'FILENAMEs' are used for finding index files (see
@@ -157,9 +168,9 @@ The follow configuration directives are recognized:
 	['ARGS'...], specifying the program to execute and the
 	arguments to pass it. In addition to the specified arguments,
 	the HTTP method, raw URL and the rest string will be appended
-	added as described in *ashd*(7). If given in a `.htrc` file,
-	the program will be started in the same directory as the
-	`.htrc` file itself.
+	as described in *ashd*(7). If given in a `.htrc` file, the
+	program will be started in the same directory as the `.htrc`
+	file itself.
 
 *match* [*directory*]::
 
@@ -219,6 +230,12 @@ The following rules are recognized:
 	Matches if and only if no *match* stanza without a *default*
 	rule has matched.
 
+*local*::
+
+	Valid only in `.htrc` files, *local* matches if and only if
+	the file under consideration resides in the same directory as
+	the containing `.htrc` file.
+
 In addition to the rules, a *match* stanza must contain exactly one
 follow-up line specifying the action to take if it matches. The
 following actions are recognized:
@@ -239,8 +256,29 @@ following actions are recognized:
 	by a *fchild* stanza. This action exists mostly for
 	convenience.
 
-If no *match* stanza matches, a 404 response is returned to the
-client.
+404 RESPONSES
+-------------
+
+Any of the following cases will result in a 404 response being sent to
+the client.
+
+ * Failure of the mapping procedure to find a matching physical file.
+ * Presence of a path element during mapping that begins with a dot.
+ * A path element which, after URL unescaping, contains slashes.
+ * The mapping procedure finding a file which is neither a directory
+   nor a regular file.
+ * Presence of a non-final but empty path element during mapping.
+ * A physical file having been found which is not being matched by any
+   *match* stanza.
+
+*dirplex* will send a built-in 404 response by default, but any
+`.htrc` file or global configuration may define a request handler
+named `.notfound` to customize the behavior. Note that, unlike
+successful requests, such a handler will not be passed the
+`X-Ash-File` header.
+
+The built-in `.notfound` handler can also be used in *match* or
+*capture* stanzas.
 
 EXAMPLES
 --------