documentation of the Action directive

[Mark Brown <mb...@OpenMarket.com>]

Recently I've been trying to understand handlers and the Action directive,
in order to help a user of mod_fastcgi debug his config.

The documentation of the Action directive, comments in the body
of mod_actions.c, and the help text associated with the Action directive
all say that the first argument to Action is a MIME-type, and the
second argument is a CGI script.

My reading of the code is that the first argument to Action is either a media
type or a handler name, and the second argument is the absolute
path portion of a URL, not restricted to CGI.  The second
argument will *typically* be a script name, but might be CGI or
FastCGI.

Here's how I think the mechanism works:

 If action_handler is selected to handle the request,
  and the current request has no handler,
  and an Action directive naming the request's content type applies to
   the request,
 then the server performs an internal redirect to the target of the Action.

 If action_handler is selected to handle the request,
  and the current request has a handler,
  and an Action directive naming the request's handler applies to
   the request,
 then the server performs an internal redirect to the target of the Action.

I probably don't understand all of the ways that earlier stages of
request processing set the handler.  What I do understand is
that during the type-checking stage, the handler can be set based
on filenamen extension (AddHandler), and then overridden based on directory
(SetHandler).

My guess is that action_handler is selected for all requests,
but I'm not sure about that.

1) I'd appreciate it if somebody who understands how this stuff
really works would beef up the documentation.

2) What follows is a suggested patch to mod_actions.c that tries to improve
the comments and command help text.  I think it would be much better
to eliminate the directive-related comments in mod_actions.c (and other
modules) and make the documentation the truth,
but as long as we've got the comments they need to agree with the code.

Thanks,

    --mark

* * * * *

% diff mod_actions.c.orig mod_actions.c
63c63
<  * Action mime/type /cgi-bin/script
---
>  * Action handler-name-or-media-type URL-absolute-path
65,67c65,69
<  * will activate /cgi-bin/script when a file of content type mime/type. It
<  * sends the URL and file path of the requested document using the standard
<  * CGI PATH_INFO and PATH_TRANSLATED environment variables.
---
>  * will internally redirect to URL-absolute-path (typically a script) when
>  * a request is made for a file with the given handler or media type.
>  * The new request will have CGI PATH_INFO and PATH_TRANSLATED environment
>  * variables set to the URL and file path of the requested document,
>  * respectively.
147c149,150
<     "a media type followed by a script name" },
---
>     "a handler name or media type, "
>     "followed by the absolute path portion of a URL" },
149c152
<     "a method followed by a script name" },
---
>     "an HTTP method followed by the absolute path portion of a URL" },

* * * * *