patplex: Search for the configuration file if it contains no slashes.

[ashd.git] / doc / patplex.doc

diff --git a/doc/patplex.doc b/doc/patplex.doc
index 657bd45..dff248b 100644 (file)
--- a/doc/patplex.doc
+++ b/doc/patplex.doc
@@ -37,18 +37,21 @@ In addition to the 'CONFIGFILE' specified on the command-line,
 *patplex* also attempts to find and read a global configuration file
 called `patplex.rc`, unless the *-N* option is given. 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 `patplex.rc`, in that
-order. Only the first file found is used, should there exist several.
+`../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 `patplex.rc`, in that
+order. Only the first file found is used, should there exist
+several. If the given 'CONFIGFILE' contains any slashes, it is opened
+by that exact name. Otherwise, it is searched for in the same manner
+as the global configuration file.
 
 Should the global and the given configuration files conflict, the
 directives from the given file take precedence.
 
 The configuration files follow the same general format as for
-*dirplex*(1), though the recognized stanzas differ. The *child* and
-*fchild* stanzas are also shared with *dirplex*(1), so see its manpage
-for a description thereof.
+*dirplex*(1), though the recognized stanzas differ. The *child*,
+*fchild* and *include* stanzas are also shared with *dirplex*(1), so
+see its manpage for a description thereof.
 
 *patplex* recognizes the *match* stanza, which takes no arguments, but
 must contain at least one follow-up line to specify match rules. All
@@ -93,7 +96,7 @@ rules are recognized:
        rule has matched.
 
 In addition to the rules, a *match* stanza must contain exactly one
-follow-up line specifying the action to take if it mathces. Currently,
+follow-up line specifying the action to take if it matches. Currently,
 only the *handler* action is recognized:
 
 *handler* 'HANDLER'::
@@ -101,14 +104,30 @@ only the *handler* action is recognized:
        'HANDLER' must be a named handler as declared by a *child* or
        *fchild* stanza, to which the request is passed.
 
-Additionally, a *match* stanza may contain a *restpat* line:
+Additionally, a *match* stanza may contain any of the following,
+optional lines:
+
+*set* 'HEADER' 'VALUE'::
+
+       If the *match* stanza as a whole matches, the named HTTP
+       'HEADER' in the request is set to 'VALUE' before passing the
+       request on to the specified handler. A *match* stanza may
+       contain any number of *set* lines.
+
+*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.
 
 *restpat* 'TEMPLATE'::
 
        If the *match* stanza as a whole matches, 'TEMPLATE' is
        expanded and installed as the rest string of the request
        before it is passed to the specified handler. In 'TEMPLATE',
-       the following parameters are recognized and expanded.
+       the following parameters are recognized and expanded. At most
+       one *restpat* line may be given per *match* stanza.
 
 *$0* ... *$9*::
 
@@ -135,6 +154,17 @@ Additionally, a *match* stanza may contain a *restpat* line:
 If no *match* stanza matches, a 404 response is returned to the
 client.
 
+SIGNALS
+-------
+
+SIGHUP::
+
+       Reread the given configuration file (but not the global
+       file). If any named handlers, as specified by *child* stanzas,
+       are currently running and have stanzas with matching names in
+       the new file, they are left running for those stanzas (even if
+       the *exec* line has changed).
+
 EXAMPLES
 --------
 
@@ -145,7 +175,7 @@ them.
 
 --------
 child root
-  exec sudo -u www-data dirplex /srv/www/htdocs
+  exec sudo -u www-data dirplex /srv/www
 child userdir
   exec userplex -g users
 match
@@ -173,7 +203,7 @@ match
 # Use the last level of the domain name to enter a subdirectory.
 match
   header host ^([^.]*)\\.multi\\.org$ is
-  restpat $1$_
+  restpat $1/$_
   handler site-multi
 --------