doc: Made mention of the include directive.

[ashd.git] / doc / dirplex.doc

diff --git a/doc/dirplex.doc b/doc/dirplex.doc
index cc243e0..7d1e41f 100644 (file)
--- 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.
 
 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
 
 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.
 
 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
 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
 
 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:
 
 
 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
 *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
        ['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*]::
 
 
 *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.
 
        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:
 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.
 
        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
 --------
 
 EXAMPLES
 --------