[racket] doc request for serve/servlet

On Mar 22, 2013, at 2:41 PM, Jay McCarthy wrote:

> On Fri, Mar 22, 2013 at 2:13 PM, John Clements
> <clements at brinckerhoff.org> wrote:
>> 
>> On Mar 22, 2013, at 5:06 AM, Jay McCarthy wrote:
>> 
>>> I'm willing to change the docs, but I'd like to try to explain it in
>>> an email to make sure the explanation is okay.
>>> 
>>> The key sentence of the documentation is: "start is loaded as a
>>> servlet and responds to requests that match servlet-regexp."
>>> 
>>> The default for servlet-regexp is such that the ONLY path that the
>>> servlet responds to is "/servlets/standalone.rkt" and ALL other paths
>>> are handled by the static file handlers.
>> 
>> I think that that fact is not inferrable from the docs. I would change the current text
>> to:
>> 
>> "start is loaded as a
>> servlet and responds to requests that match servlet-regexp. Requests
>> that don't match this regexp will be served from the pool of static files, if
>> a corresponding file exists, or routed to the file-not-found-responder."
>> 
>> Reviewing my thrashing last night, I've come to the conclusion that much of
>> my suffering was caused by browser caching. I think that the text above
>> might have gotten me to that realization, by explicitly static a set of circumstances
>> under which requests go to the pool of static files.
> 
> I don't like this modification because there's lots of other handlers
> that are enabled. Almost every other sentence in the documentation is
> about a different URL that is handled a different way. For example,
> "If quit? is true, then the URL "/quit" ends the server." "File paths,
> in addition to the "htdocs" directory under server-root-path may be
> provided with extra-files-paths. These paths are checked first, in the
> order they appear in the list."  etc
> 
> Each section is about a different class of requests handled a
> different way. One of the most general ones is the file one, but it's
> definitely not the "catch all" or anything.

Yikes! In that case, I *really* didn't understand the architecture. Would it make sense to add at least a sentence that alludes to (and ideally points to) documentation on the request handler model? A two-minute scan through the web-server docs doesn't turn up any information on a chain of handlers.

John