[racket] doc request for serve/servlet

This is slightly off-topic, but:

If you want to launch the web server _just_ to serve static files (as
I wanted to do for a "preview" mode for Frog), then it's simply this:

(serve/servlet (lambda (_) (next-dispatcher))
               #:servlet-path "/"
               #:extra-files-paths (list path/to/files)
               #:port 8080              ;or whatever
               #:launch-browser? #t)    ;if you wish

Although this isn't a very interesting use case, I think it might be a
handy example for the docs.

On Fri, Mar 22, 2013 at 8:06 AM, Jay McCarthy <jay.mccarthy at gmail.com> 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.
>
> It is common to change the servlet-regexp to something like #rx"",
> which causes ALL requests to be handled by the servlet. When you do
> this, the documentation is still correct, but you may not realize the
> consequence of what you've done.
>
> Throughout the Web server infrastructure, and serve/servlet does not
> change this, if you call (next-dispatcher) then the current responder
> FAILS and the next responder gets a chance. In the context of
> serve/servlet, if you call (next-dispatcher) after using #rx"" to take
> over all requests, then for that particular request where
> (next-dispatcher) was dynamically called, the static handlers take
> over.
>
> It so happens that the default "else" clause in web-server/dispatch is
> to call (next-dispatcher). From the documentation: "If else-fun is
> left out, one is provided that calls (next-dispatcher) to signal to
> the Web Server that this dispatcher does not apply."
>
> Thus, if you use the #rx"" regexp AND dispatch-rules, then it is
> likely that the "right" thing will happen without you trying because
> you won't write an else and then if your servlet doesn't handle the
> request, the static handler will be in control.
>
> Overall, I don't know what the documentation should be changed to say.
> All this is in the documentation right now: you just might not realize
> you are telling the servlet to handle everything, but once you realize
> that you just need to know how to turn that off, and that isn't
> specific in any way to serve/servlet, so I don't feel like it is
> appropriate to put it there. (Alternatively, you should just be more
> specific in your servlet-regexp, by using something like
> (re-complement #rx"/static/.+"), and that's reasonable to expect a
> user to realize, IMHO.)
>
> Jay
>
>
> On Thu, Mar 21, 2013 at 10:55 PM, John Clements
> <clements at brinckerhoff.org> wrote:
>> The serve/servlet function has several flags that allude to the ability to serve static files (#:extra-files-paths, etc.). However, nowhere in that documentation does it say under what circumstances the web-server serves content from that pool of files.  After much struggling and cursing, I finally found a post by Matt Jadud.  Even then, it took me quite a while to realize that the 'dispatch-rules' function was the key to actually allowing some requests to reach the static content. Perhaps the serve/servlet documentation should explicitly specify when content is served from static files, or at least provide a pointer to the dispatch-rules documentation.
>>
>> Thoughts?
>>
>> John
>>
>>
>> ____________________
>>   Racket Users list:
>>   http://lists.racket-lang.org/users
>
>
>
> --
> 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
>
> ____________________
>   Racket Users list:
>   http://lists.racket-lang.org/users