Documentation stubs and configuration documentation

svn: r6460

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

@@ -1,13 +1,180 @@
 #reader(lib "docreader.ss" "scribble")
 @require["../web-server.ss"]
+@; XXX require mzscheme, url.ss, and contract.ss
 
 @title[#:style 'toc]{Configuration}
 
-XXX
-
 @local-table-of-contents[]
 
 @; ------------------------------------------------------------
-@section[#:tag "example"]{Example}
+@section[#:tag "configuration-table-structs"]{Configuration Table Structure}
+
+@file{configuration/configuration-table-structs.ss} provides the following structures that
+represent a standard configuration (see @secref["XXX"]) of the @file{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"].
+
+@defstruct[configuration-table
+           ([port (between/c 1 65535)]
+            [max-waiting natural-number/c]
+            [initial-connection-timeout natural-number/c]
+            [default-host host-table?]
+            [virtual-hosts (listof (cons/c string? host-table?))])]
+
+@defstruct[host-table 
+           ([indices (listof string?)]
+            [log-format symbol?]
+            [messages messages?]
+            [timeouts timeouts?]
+            [paths paths?])]
+
+@defstruct[host 
+           ([indices (listof string?)]
+            [log-format symbol?]
+            [log-path (or/c false/c path-string?)]
+            [passwords (or/c false/c path-string?)]
+            [responders responders?]
+            [timeouts timeouts?]
+            [paths paths?])]
+
+@defstruct[responders
+           ([servlet (url? any/c . -> . response?)]
+            [servlet-loading (url? any/c . -> . response?)]
+            [authentication (url? (cons/c symbol? string?) . -> . response?)]
+            [servlets-refreshed (-> response?)]
+            [passwords-refreshed (-> response?)]
+            [file-not-found (request? . -> . response?)]
+            [protocol (url? . -> . response?)]
+            [collect-garbage (-> response?)])]
+
+@defstruct[messages
+           ([servlet string?]
+            [authentication string?]
+            [servlets-refreshed string?]
+            [passwords-refreshed string?]
+            [file-not-found string?]
+            [protocol string?]
+            [collect-garbage string?])]
+
+@defstruct[timeouts 
+           ([default-servlet number?]
+            [password number?]
+            [servlet-connection number?]
+            [file-per-byte number?]
+            [file-base number?])]
+
+@defstruct[paths 
+           ([conf (or/c false/c path-string?)]
+            [host-base (or/c false/c path-string?)]
+            [log (or/c false/c path-string?)]
+            [htdocs (or/c false/c path-string?)]
+            [servlet (or/c false/c path-string?)]
+            [mime-types (or/c false/c path-string?)]
+            [passwords (or/c false/c path-string?)])]
+
+@; ------------------------------------------------------------
+@section[#:tag "configuration-table"]{Configuration Table}
+
+@file{configuration/configuration-table.ss} provides functions for 
+reading, writing, parsing, and printing @scheme[configuration-table] 
+structures.
+
+@defproc[(sexpr->configuration-table (sexpr list?))
+         configuration-table?]
+
+@defproc[(configuration-table->sexpr (ctable configuration-table?))
+         list?]
+
+These functions do the expected and convert a @scheme[configuration-table]
+from (to) an S-expression. The format of this S-expresssion is:
+
+@schemeblock[
+`((port ,integer?)
+  (max-waiting ,integer?)
+  (initial-connection-timeout ,integer?)
+  (default-host-table
+    ,host-table-sexpr?)
+  (virtual-host-table
+   (list ,symbol? ,host-table-sexpr?)
+   ...))]
+
+where a @scheme[host-table-sexpr] is:
+
+@; XXX Allowable log-formats?
+@; XXX Where the paths are resolved relative to
+@schemeblock[
+`(host-table
+  (default-indices ,string? ...)
+  (log-format ,symbol?)
+  (messages
+   (servlet-message ,path-string?)
+   (authentication-message ,path-string?)
+   (servlets-refreshed ,path-string?)
+   (passwords-refreshed ,path-string?)
+   (file-not-found-message ,path-string?)
+   (protocol-message ,path-string?)
+   (collect-garbage ,path-string?))
+  (timeouts
+   (default-servlet-timeout ,integer?)
+   (password-connection-timeout ,integer?)
+   (servlet-connection-timeout ,integer?)
+   (file-per-byte-connection-timeout ,integer?)
+   (file-base-connection-timeout ,integer))
+  (paths
+   (configuration-root ,path-string?)
+   (host-root ,path-string?)
+   (log-file-path ,path-string?)
+   (file-root ,path-string?)
+   (servlet-root ,path-string?)
+   (mime-types ,path-string?)
+   (password-authentication ,path-string?)))]
+
+@defproc[(read-configuration-table (path path-string?))
+         configuration-table?]
+@defproc[(write-configuration-table (ctable configuration-table?) (path path-string?))
+         void]
+
+These functions do the expected and read (write) a @scheme[configuration-table]
+from (to) the given @scheme[path].
+
+@; ------------------------------------------------------------
+@section[#:tag "namespace"]{Servlet Namespaces}
+
+@; XXX Require dispatch-servlets and dispatch-lang
+
+@file{configuration/namespace.ss} provides a function to help create the
+@scheme[make-servlet-namespace] procedure needed by the @scheme[make] functions
+of @file{dispatchers/dispatch-servlets.ss} and @file{dispatchers/dispatch-lang.ss}.
+
+@; XXX Use actual keyword argument syntax
+@; XXX Require for current-namespace
+
+@defproc[(make-make-servlet-namespace (keyword to-be-copied-module-specs (listof module-spec?)))
+         (key-> ([additional-specs (listof module-spec?)])
+                namespace?)]
+
+This function creates a function that when called will construct a new @scheme[namespace] that
+has all the modules from @scheme[to-be-copied-module-specs] and @scheme[additional-specs], as well
+as @scheme[mzscheme] and @scheme[(lib "mred.ss" "mred")], provided they are already attached
+to the @scheme[(current-namespace)] of the call-site.
+
+@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
+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
+implements structures.
+
+Since, on occasion, a user will actually wanted servlets A and B to interact through module C.
+A custom @scheme[make-servlet-namespace] can be created, through this procedure, that attaches
+module C to all servlet namespaces. Through other means (see @secref["pipelines"]) different sets
+of servlets can share different sets of modules.
+
+@; ------------------------------------------------------------
+@section[#:tag "responders"]{Standard Responders}
 
 XXX

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

@@ -0,0 +1,13 @@
+#reader(lib "docreader.ss" "scribble")
+@require["../web-server.ss"]
+
+@title[#:style 'toc]{Dispatchers}
+
+XXX
+
+@local-table-of-contents[]
+
+@; ------------------------------------------------------------
+@section[#:tag "example"]{Example}
+
+XXX

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

@@ -0,0 +1,13 @@
+#reader(lib "docreader.ss" "scribble")
+@require["../web-server.ss"]
+
+@title[#:style 'toc]{Web Language}
+
+XXX
+
+@local-table-of-contents[]
+
+@; ------------------------------------------------------------
+@section[#:tag "example"]{Example}
+
+XXX

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

@@ -0,0 +1,13 @@
+#reader(lib "docreader.ss" "scribble")
+@require["../web-server.ss"]
+
+@title[#:style 'toc]{Continuation Managers}
+
+XXX
+
+@local-table-of-contents[]
+
+@; ------------------------------------------------------------
+@section[#:tag "example"]{Example}
+
+XXX

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

@@ -0,0 +1,13 @@
+#reader(lib "docreader.ss" "scribble")
+@require["../web-server.ss"]
+
+@title[#:style 'toc]{Internal}
+
+XXX
+
+@local-table-of-contents[]
+
+@; ------------------------------------------------------------
+@section[#:tag "example"]{Example}
+
+XXX

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

@@ -3,8 +3,20 @@
 
 @title{Web Server Reference Manual}
 
+The @file{web-server} collection provides libraries that can be used to
+develop Web applications in Scheme.
+
 @table-of-contents[]
 
 @include-section["configuration.scrbl"]
+@include-section["dispatchers.scrbl"]
+@include-section["lang.scrbl"]
+@include-section["managers.scrbl"]
+@include-section["private.scrbl"]
+@include-section["servlet-env.scrbl"]
+@include-section["servlet.scrbl"]
+@include-section["web-config-unit.scrbl"]
+@include-section["web-server-unit.scrbl"]
+@include-section["web-server.scrbl"]
 
 @index-section["web-server-ref-index"]

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

@@ -0,0 +1,13 @@
+#reader(lib "docreader.ss" "scribble")
+@require["../web-server.ss"]
+
+@title[#:style 'toc]{Servlet Environment}
+
+XXX
+
+@local-table-of-contents[]
+
+@; ------------------------------------------------------------
+@section[#:tag "example"]{Example}
+
+XXX

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

@@ -0,0 +1,13 @@
+#reader(lib "docreader.ss" "scribble")
+@require["../web-server.ss"]
+
+@title[#:style 'toc]{Servlets}
+
+XXX
+
+@local-table-of-contents[]
+
+@; ------------------------------------------------------------
+@section[#:tag "example"]{Example}
+
+XXX

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

@@ -0,0 +1,13 @@
+#reader(lib "docreader.ss" "scribble")
+@require["../web-server.ss"]
+
+@title[#:style 'toc]{Web Config Unit}
+
+XXX
+
+@local-table-of-contents[]
+
+@; ------------------------------------------------------------
+@section[#:tag "example"]{Example}
+
+XXX

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

@@ -0,0 +1,13 @@
+#reader(lib "docreader.ss" "scribble")
+@require["../web-server.ss"]
+
+@title[#:style 'toc]{Web Server Unit}
+
+XXX
+
+@local-table-of-contents[]
+
+@; ------------------------------------------------------------
+@section[#:tag "example"]{Example}
+
+XXX

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

@@ -0,0 +1,13 @@
+#reader(lib "docreader.ss" "scribble")
+@require["../web-server.ss"]
+
+@title[#:style 'toc]{Web Server}
+
+XXX
+
+@local-table-of-contents[]
+
+@; ------------------------------------------------------------
+@section[#:tag "example"]{Example}
+
+XXX