A staging directory is a place where the author of an HTML document checks the look and feel of the document before it's uploaded to the final location. A staging place doesn't need to be a separate server or a mirror of the "real" tree, or even a tree of symbolic links. A sparse directory tree that holds nothing but the staged files will do.

Apache::Stage implements a staging directory that needs a minimum of space. By default, the path for the per-user staging directory is hardcoded as:

/STAGE/any-user-name

The code respects proper internal and external redirects for any documents that are not in the staging directory tree. This means that all graphics are displayed as they will be when the staged files have been published. The following table provides an example structure:

Location           Redirect-to Comment
------------------ ----------- ---------------------------
/STAGE/u1/         /           Homepage. Internal Redirect.
/STAGE/u2/dir1     /dir1/      Really /dir1/index.html
/STAGE/u3/dir2     /dir2/      Directory has no index.html
                               Options Indexes is off, thus
                               "Forbidden"
/STAGE/u4/dir2/foo /dir2/foo   Internal redirect.
/STAGE/u5/bar      -           Exists really, no redirect
                               necessary
/STAGE/u6          -           Fails unless location exists

The entries described in SYNOPSIS in access.conf or an equivalent place define the name of the staging directory, the name of an internal location that catches the exception when a document is not in the staging directory, and the regular expression that transforms the staging URI into the corresponding public URI.

With this setup only ErrorDocuments 403 and 404 will be served by Apache::Stage. If you need coexistence with different ErrorDocument handlers, you will either have to disable them for /STAGE or integrate the code of Apache::Stage into an if/else branch based on the path.

Available from CPAN. See the module manpage for more information.