[racket] doc request for serve/servlet

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.

Jay

--
Jay McCarthy <jay at cs.byu.edu>
Assistant Professor / Brigham Young University
http://faculty.cs.byu.edu/~jay

"The glory of God is Intelligence" - D&C 93