Adding doc-installer and dispatcher documentation

svn: r6464

collects/web-server/dispatchers/filesystem-map.ss

@@ -7,8 +7,9 @@
     ((url?) . ->* . (path? list?)))
   
   (provide/contract
+   [url-path? contract?]
    [make-url->path (path? . -> . url-path?)]
-   [make-url->path/optimism (url-path? . -> . url-path?)])  
+   [make-url->path/optimism (url-path? . -> . url-path?)])
   
   (define (build-path* . l)
     (if (empty? l)

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

@@ -0,0 +1,20 @@
+(module doc-installer mzscheme
+  (require (lib "dirs.ss" "setup")
+           (lib "to-html.ss" "scribblings")
+           (prefix ref: "reference/reference.scrbl")
+           (prefix guide: "guide/guide.scrbl"))
+  
+  (provide post-installer)
+  
+  (define post-installer
+    (lambda (path)
+      (let ([doc (find-doc-dir)])
+        (when doc
+          (build)))))
+  
+  (define (build)
+    (to-html #t #t 
+             (list ref:doc 
+                   guide:doc)
+             (list "web-server-reference"
+                   "web-server-guide"))))

collects/web-server/docs/docs.ss

@@ -1,14 +0,0 @@
-(module docs mzscheme
-  (require (lib "to-html.ss" "scribblings")
-           (prefix ref: "reference/reference.scrbl")
-           (prefix guide: "guide/guide.scrbl"))
-  (provide build)
-  
-  (define (build)
-    (to-html #t #t 
-             (list ref:doc 
-                   guide:doc)
-             (list "web-server-reference"
-                   "web-server-guide")))
-  
-  (build))

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

@@ -265,4 +265,29 @@ that runs servlets written in Scheme.
 @; ------------------------------------------------------------
 @section[#:tag "filesystem-map"]{Mapping URLs to Paths}
 
-XXX
+@file{dispatchers/filesystem-map.ss} provides a means of mapping
+URLs to paths on the filesystem.
+
+@; XXX Change to listof path?
+@defthing[url-path? contract?]{
+ This contract is equivalent to @scheme[((url?) . ->* . (path? list?))].
+ The returned @scheme[path?] is the path on disk. The list is the list of
+ path elements that correspond to the path of the URL.}
+
+@defproc[(make-url->path (base path?))
+         url-path?]{
+ The @scheme[url-path?] returned by this procedure considers the root
+ URL to be @scheme[base]. It ensures that @scheme[".."]s in the URL
+ do not escape the @scheme[base].}                             
+
+@; XXX Rename to /valid                   
+@defproc[(make-url-path/optimism (url->path url->path?))
+         url->path?]{
+ Runs the underlying @scheme[url->path], but only returns if the path
+ refers to a file that actually exists. If it is does not, then the suffix
+ elements of the URL are removed until a file is found. If this never occurs,
+ then an error is thrown.
+ 
+ This is primarily useful for dispatchers that allow path information after
+ the name of a service to be used for data, but where the service is represented
+ by a file. The most prominent example is obviously servlets.}

collects/web-server/info.ss

@@ -1,5 +1,6 @@
 (module info (lib "infotab.ss" "setup")
   (define name "Web Server")  
+  (define post-install-collection "docs/doc-installer.ss")
   
   (define mzscheme-launcher-libraries
     (list "private/launch-text.ss" "private/setup-launch.ss" ))