Incorporating Noels comments

svn: r6552

collects/web-server/docs/reference/configuration.scrbl

@@ -6,7 +6,7 @@
        #:style 'toc]{Configuration}
 
 There are a number of libraries and utilities useful for
-configuring the @file{web-server}.
+configuring the @web-server .
 
 @local-table-of-contents[]
 
@@ -14,7 +14,7 @@ configuring the @file{web-server}.
 @section[#:tag "configuration-table-structs.ss"]{Configuration Table Structure}
 
 @file{configuration/configuration-table-structs.ss} provides the following structures that
-represent a standard configuration (see @secref["web-server-unit.ss"]) of the @file{web-server}.
+represent a standard configuration (see @secref["web-server-unit.ss"]) of the @web-server .
 The contracts on this structure influence the valid types of values in
 the configuration table S-expression file format described in 
 @secref["configuration-table.ss"].
@@ -176,11 +176,11 @@ Example:
 @subsection{Why this is useful}
 
 A different namespace is needed for each servlet, so that if servlet A and servlet B both use
-a stateful module C, they will be isolated from one another. We see the @file{web-server} as
+a stateful module C, they will be isolated from one another. We see the @web-server as
 an operating system for servlets, so we inherit the isolation requirement on operating systems.
 
 However, there are some modules which must be shared. If they were not, then structures cannot
-be passed from the @file{web-server} to the servlets, due to a subtlety in the way MzScheme
+be passed from the @web-server to the servlets, due to a subtlety in the way MzScheme
 implements structures.
 
 Since, on occasion, a user will actually wanted servlets A and B to interact through module C.

collects/web-server/docs/reference/dispatchers.scrbl

@@ -4,11 +4,11 @@
 @title[#:tag "dispatchers"
        #:style 'toc]{Dispatchers}
 
-The @file{web-server} is really just a peculiar configuration of a
+The @web-server is really just a particular configuration of a
 dispatching server. There are a number of dispatchers that are defined
-to support the @file{web-server}. Other dispatching servers, or variants
+to support the @web-server . Other dispatching servers, or variants
-of the @file{web-server}, may find these useful. In particular, if you want
+of the @web-server , may find these useful. In particular, if you want
-a peculiar processing pipeline for your @file{web-server} installation, this
+a peculiar processing pipeline for your @web-server installation, this
 documentation will be useful.
 
 @local-table-of-contents[]
@@ -44,6 +44,19 @@ different. For example, it may apply some test to the request object, perhaps
 checking for a valid source IP address, and error if the test is not passed, and call @scheme[next-dispatcher]
 otherwise.
 
+Consider the following example dispatcher, that captures the essence of URL rewriting:
+@schemeblock[
+ (code:comment "(url? -> url?) dispatcher? -> dispatcher?")
+ (lambda (rule inner)
+   (lambda (conn req)
+     (code:comment "Call the inner dispatcher...")
+     (inner conn
+            (code:comment "with a new request object...")
+            (copy-struct request req
+                         (code:comment "with a new URL!")
+                         [request-uri (rule (request-uri req))]))))
+] 
+
 @; ------------------------------------------------------------
 @section[#:tag "filesystem-map.ss"]{Mapping URLs to Paths}
 
@@ -126,7 +139,7 @@ URL path.
  and if so, calls @scheme[proc] for a response.
 }
                      
-This is used in the standard @file{web-server} pipeline to provide
+This is used in the standard @web-server pipeline to provide
 a URL that refreshes the password file, servlet cache, etc.
                      
 @; ------------------------------------------------------------

collects/web-server/docs/reference/lang.scrbl

@@ -4,7 +4,7 @@
 @title[#:tag "lang"
        #:style 'toc]{Web Language Servlets}
 
-The @file{web-server} allows servlets to be written in a special Web
+The @web-server allows servlets to be written in a special Web
 language that is nearly identical to Scheme. Herein we discuss how it
 is different and what API is provided.
 

collects/web-server/docs/reference/managers.scrbl

@@ -107,7 +107,7 @@ Web Language. (See @secref["lang"].)
 }
 
 This manager has been found to be... problematic... in large-scale
-deployments of the @file{web-server}.
+deployments of the @web-server .
                   
 @; ------------------------------------------------------------
 @section[#:tag "lru.ss"]{LRU}

collects/web-server/docs/reference/private.scrbl

@@ -4,7 +4,7 @@
 @title[#:tag "private"
        #:style 'toc]{Internal}
 
-The @file{web-server} is a complicated piece of software and as a result,
+The @web-server is a complicated piece of software and as a result,
 defines a number of interesting and independently useful sub-components.
 Some of these are documented here.
 
@@ -106,7 +106,7 @@ for doing this.
 @; ------------------------------------------------------------
 @section[#:tag "dispatch-server-unit.ss"]{Dispatching Server}
 
-The @file{web-server} is just a configuration of a dispatching server.
+The @web-server is just a configuration of a dispatching server.
 This dispatching server component is useful on its own.
 
 @file{private/dispatch-server-sig.ss} defines the following signatures:
@@ -253,7 +253,7 @@ values. @file{private/mod-map.ss} compresses the serialized representation.
 @; ------------------------------------------------------------
 @section[#:tag "url-param.ss"]{URL Param}
 
-The @file{web-server} needs to encode information in URLs. If this data
+The @web-server needs to encode information in URLs. If this data
 is stored in the query string, than it will be overridden by browsers that
 make GET requests to those URLs with more query data. So, it must be encoded
 in URL params. @file{private/url-param.ss} provides functions for helping
@@ -277,7 +277,7 @@ with this process.
 @; ------------------------------------------------------------
 @section[#:tag "util.ss"]{Miscellaneous Utilities}
 
-There are a number of other miscellaneous utilities the @file{web-server}
+There are a number of other miscellaneous utilities the @web-server
 needs. They are provided by @file{private/util.ss}.
 
 @subsection{Lists}

collects/web-server/docs/reference/reference.scrbl

@@ -4,7 +4,7 @@
 @title[#:tag "web-server-ref"]{Web Server Reference Manual}
 @author{Jay McCarthy (jay\@plt-scheme.org)}
 
-The @file{web-server} collection provides libraries that can be used to
+The @web-server collection provides libraries that can be used to
 develop Web applications in Scheme.
 
 @table-of-contents[]
@@ -29,7 +29,7 @@ develop Web applications in Scheme.
 @section[#:tag "ack"]{Acknowledgements}
 
 We thank Matthew Flatt for his superlative work on MzScheme.
-We thank the previous maintainers of the PLT Web Server: Paul T. Graunke, Mike Burns, and Greg Pettyjohn
+We thank the previous maintainers of the @web-server : Paul T. Graunke, Mike Burns, and Greg Pettyjohn
 Numerous people have 
 provided invaluable feedback on the server, including Eli Barzilay, Ryan Culpepper, Robby 
 Findler, Dan Licata, Matt Jadud, Jacob Matthews, Matthias Radestock, Andrey Skylar, 

collects/web-server/docs/reference/running.scrbl

@@ -12,13 +12,13 @@ are through a command-line tool or through a function call.
 @; ------------------------------------------------------------
 @section[#:tag "command-line-tools"]{Command-line Tools}
 
-Two command-line utilities are provided with the @file{web-server}:
+Two command-line utilities are provided with the @web-server :
 
 @exec{plt-web-server-text [-f <file-name> -p <port> -a <ip-address>]}
 
 @exec{plt-web-server [-f <file-name> -p <port> -a <ip-address>]}
 
-The first runs the @file{web-server} with MzScheme, while the second runs
+The first runs the @web-server with MzScheme, while the second runs
 the server with MrEd, providing a graphical UI. The optional file-name 
 argument specifies the path to a @scheme[configuration-table] S-expression
 (see @secref["configuration-table.ss"].) If this is not provided, the default
@@ -34,7 +34,7 @@ the server runs until the process is killed.
 @section[#:tag "web-server.ss"]{Functional}
 
 @file{web-server.ss} provides a number of functions for easing embedding
-of the @file{web-server} in other applications, or loading a custom
+of the @web-server in other applications, or loading a custom
 dispatcher. See @file{run.ss} for an example of such a script.
 
 @defproc[(serve [#:dispatch dispatch dispatcher?]
@@ -70,6 +70,6 @@ dispatcher. See @file{run.ss} for an example of such a script.
 }                   
                    
 @defproc[(do-not-return) void]{
- This function does not return. If you are writing a script to load the @file{web-server}
+ This function does not return. If you are writing a script to load the @web-server
  you are likely to want to call this functions at the end of your script.
 }

collects/web-server/docs/reference/servlet-env.scrbl

@@ -2,9 +2,9 @@
 @require["../web-server.ss"]
 
 @title[#:tag "servlet-env.ss"
-       #:style 'toc]{Servlet Environment}
+       #:style 'toc]{Scheme Servlet Environment}
 
-The @file{web-server} provides a means of running Scheme servlets
+The @web-server provides a means of running Scheme servlets
 from within DrScheme, or any other REPL.
 
 @file{servlet-env.ss} provides the servlet API from @file{servlet.ss}
@@ -14,8 +14,9 @@ as well as the following special forms:
 
 @defform[(on-web port servlet-expr)]{
  This constructs a small servlet, where the body of the @scheme[start] procedure is
- @scheme[servlet-expr], runs the @file{web-server} on port @scheme[port], and opens
+ @scheme[servlet-expr], runs the @web-server on port @scheme[port], and opens
  a browser to a URL accessing the constructed servlet. The call blocks until the
  servlet finishes its computation, i.e. @scheme[servlet-expr] is evaluated, and
- returns its result.
+ returns its result. @scheme[servlet-expr] may use the entire Scheme servlet API.
+ (See @secref["servlet"].)
 }

collects/web-server/docs/reference/servlet.scrbl

@@ -4,7 +4,7 @@
 @title[#:tag "servlet"
        #:style 'toc]{Scheme Servlets}
 
-The @file{web-server} allows servlets to be written in Scheme. It
+The @web-server allows servlets to be written in Scheme. It
 provides the supporting API, described below, for the construction
 of these servlets. This API is provided by @file{servlet.ss}.
 
@@ -15,7 +15,7 @@ of these servlets. This API is provided by @file{servlet.ss}.
 
 A @defterm{servlet} is a module that provides the following:
 
-@defthing[interface-version symbol?]{
+@defthing[interface-version (or/c 'v1 'v2)]{
  A symbol indicating the servlet interface the servlet conforms
  to. This influences the other provided identifiers.
 }
@@ -57,15 +57,14 @@ for use in servlets.
 @defthing[servlet-response? contract?]{Equivalent to @scheme[any/c].}
 
 @; XXX Remove callbacks
-@defproc[(xexpr/callback? [v any/c])
+@defthing[xexpr/callback? contract?]{
-         boolean?]{
+ Checks if the value matches @scheme[xexpr?], except that embedded
- Checks if @scheme[v] matches @scheme[xexpr?], except that embedded
  procedures are allowed.
 }
                   
-@defthing[response-generator? contract?]{Equivalent to @scheme[(k-url? . -> . servlet-response?)].}
+@defthing[k-url? contract?]{Equivalent to @scheme[string?].}
 
-@defthing[k-url? (any/c . -> . boolean?)]{Equivalent to @scheme[string?].}
+@defthing[response-generator? contract?]{Equivalent to @scheme[(k-url? . -> . servlet-response?)].}
 
 @defthing[url-transform? contract?]{Equivalent to @scheme[(k-url? . -> . k-url?)].}
 
@@ -142,7 +141,7 @@ for accessing request bindings.
                                  [binds (listof (cons/c symbol? string?))])
          string?]{
  Returns the single binding associated with @scheme[id] in the a-list @scheme[binds]
- if there is exactly one binding. Otherwise errors.
+ if there is exactly one binding. Otherwise raises @scheme[exn:fail].
 }
                  
 @defproc[(extract-bindings [id symbol?]
@@ -379,8 +378,8 @@ you lose the filename.
 @; ------------------------------------------------------------
 @section[#:tag "servlet-url.ss"]{Servlet URLs}
 
-@file{servlet/servlet-url.ss} provides a function that might be useful to you.
+@file{servlet/servlet-url.ss} provides functions that might be useful to you.
-This will be collapsed somewhere else eventually.
+They may eventually provided by another module.
 
 @defproc[(request->servlet-url (req request?))
          servlet-url?]{Generates a value to be passed to the next function.}

collects/web-server/docs/reference/web-config-unit.scrbl

@@ -4,7 +4,7 @@
 @title[#:tag "web-config-unit.ss"
        #:style 'toc]{Web Config Unit}
 
-The @file{web-server} offers a unit-based approach to configuring the server.
+The @web-server offers a unit-based approach to configuring the server.
 
 @file{web-config-sig.ss} provides the signature
 @defthing[web-config^ signature?] signature, which contains the following

collects/web-server/docs/reference/web-server-unit.scrbl

@@ -4,7 +4,7 @@
 @title[#:tag "web-server-unit.ss"
        #:style 'toc]{Web Server Unit}
 
-The @file{web-server} offers a unit-based approach to running the server.
+The @web-server offers a unit-based approach to running the server.
 
 @file{web-server-sig.ss} provides the @defthing[web-server^ signature?] signature
 with two elements:

collects/web-server/docs/web-server.ss

@@ -11,6 +11,11 @@
   ; XXX @require
   ; XXX editting mode drscheme or emacs
   
+  ; XXX @scheme in code:comment
+  
+  (define web-server "Web Server")
+  (define webserver "Web Server")
+  
   ; XXX Make look good
   (define (author x) 
     (elem (hspace 4)
@@ -18,4 +23,5 @@
 
   (provide (all-from (lib "manual.ss" "scribble"))
            (all-from (lib "eval.ss" "scribble"))
+           web-server
            author))