From f08dbc15dae0d5beec836e56688e82ffe384a4dd Mon Sep 17 00:00:00 2001
From: Matthew Flatt <mflatt@racket-lang.org>
Date: Tue, 8 Jan 2008 19:54:01 +0000
Subject: [PATCH] move/collapse web-server docs, scribble doc improvements

svn: r8262
---
 collects/scribblings/guide/guide.scrbl        |  2 +-
 collects/scribblings/scribble/how-to.scrbl    | 12 +++++++++-
 collects/scribblings/scribble/scribble.scrbl  |  9 ++++++-
 .../docs/{reference => }/configuration.scrbl  |  2 +-
 .../docs/{reference => }/dispatchers.scrbl    |  2 +-
 .../{reference => }/dummy-language-servlet.ss |  0
 .../docs/{reference => }/dummy-servlet.ss     |  0
 .../docs/{guide/web-guide.scrbl => faq.scrbl} |  8 ++-----
 collects/web-server/docs/info.ss              |  3 +++
 .../docs/{reference => }/lang.scrbl           |  4 ++--
 .../docs/{reference => }/managers.scrbl       |  2 +-
 .../docs/{reference => }/private.scrbl        |  2 +-
 .../docs/{reference => }/running.scrbl        | 24 ++++++++++---------
 .../docs/{reference => }/servlet-env.scrbl    |  2 +-
 .../docs/{reference => }/servlet.scrbl        |  6 ++---
 .../{reference => }/web-config-unit.scrbl     |  2 +-
 .../{reference => }/web-server-unit.scrbl     |  2 +-
 .../web-reference.scrbl => web-server.scrbl}  |  6 +++--
 collects/web-server/{private => }/gui.ss      |  2 +-
 collects/web-server/info.ss                   |  5 ++--
 collects/web-server/main.ss                   |  5 ++++
 collects/web-server/private/main.ss           |  5 ----
 22 files changed, 62 insertions(+), 43 deletions(-)
 rename collects/web-server/docs/{reference => }/configuration.scrbl (99%)
 rename collects/web-server/docs/{reference => }/dispatchers.scrbl (99%)
 rename collects/web-server/docs/{reference => }/dummy-language-servlet.ss (100%)
 rename collects/web-server/docs/{reference => }/dummy-servlet.ss (100%)
 rename collects/web-server/docs/{guide/web-guide.scrbl => faq.scrbl} (83%)
 create mode 100644 collects/web-server/docs/info.ss
 rename collects/web-server/docs/{reference => }/lang.scrbl (99%)
 rename collects/web-server/docs/{reference => }/managers.scrbl (99%)
 rename collects/web-server/docs/{reference => }/private.scrbl (99%)
 rename collects/web-server/docs/{reference => }/running.scrbl (80%)
 rename collects/web-server/docs/{reference => }/servlet-env.scrbl (97%)
 rename collects/web-server/docs/{reference => }/servlet.scrbl (99%)
 rename collects/web-server/docs/{reference => }/web-config-unit.scrbl (98%)
 rename collects/web-server/docs/{reference => }/web-server-unit.scrbl (98%)
 rename collects/web-server/docs/{reference/web-reference.scrbl => web-server.scrbl} (90%)
 rename collects/web-server/{private => }/gui.ss (90%)
 create mode 100644 collects/web-server/main.ss
 delete mode 100644 collects/web-server/private/main.ss

diff --git a/collects/scribblings/guide/guide.scrbl b/collects/scribblings/guide/guide.scrbl
index c04bf9b594..520b3f4431 100644
--- a/collects/scribblings/guide/guide.scrbl
+++ b/collects/scribblings/guide/guide.scrbl
@@ -118,7 +118,7 @@ executable.
 "top"]} describes tools for using Scheme to access libraries that are
 normally used by C programs.
 
-@italic{@secref[#:doc '(lib "web-server/docs/reference/web-reference.scrbl")
+@italic{@secref[#:doc '(lib "web-server/docs/web-server.scrbl")
 "top"]} describes the PLT Scheme web server, which supports servlets
 implemented in Scheme.
 
diff --git a/collects/scribblings/scribble/how-to.scrbl b/collects/scribblings/scribble/how-to.scrbl
index bea7a7f85b..0529b762c1 100644
--- a/collects/scribblings/scribble/how-to.scrbl
+++ b/collects/scribblings/scribble/how-to.scrbl
@@ -51,7 +51,17 @@ EOS
         gets large enough that you want it split into multiple pages,
         add the @scheme['multi-page] option (omitting the quote, since
         the whole right-hand side of the definition is already
-        quoted).}
+        quoted).
+
+        As usual, the @filepath{info.ss} module also needs a
+        @schemeidfont{name} field. If you do not already have an
+        @filepath{info.ss} module, here's a suitable complete module:
+
+        @schemeblock[
+          (module info setup/infotab
+            (define name "Some documentation")
+            (define scribblings '(("manual.scrbl" ()))))
+        ]}
 
   @item{Run @exec{setup-plt} to build your documentation. For a
         collection, optionally supply @Flag{l} followed by the
diff --git a/collects/scribblings/scribble/scribble.scrbl b/collects/scribblings/scribble/scribble.scrbl
index c4f70680b8..5bd3cc8453 100644
--- a/collects/scribblings/scribble/scribble.scrbl
+++ b/collects/scribblings/scribble/scribble.scrbl
@@ -7,7 +7,14 @@
        #:tag "top"]{@bold{Scribble}: PLT Documentation Tool}
 
 Scribble is a collection of tools for creating prose documents,
-especially those that document libraries.
+especially those that document libraries, and especially for HTML and
+PDF (via LaTeX) output.
+
+This document itself is written using Scribble. At the time that it
+was written, its source was available at
+@(let ([url "http://svn.plt-scheme.org/plt/trunk/collects/scribblings/scribble/"])
+   (link url url))
+starting with the @filepath{scribble.scrbl} file.
 
 @table-of-contents[]
 
diff --git a/collects/web-server/docs/reference/configuration.scrbl b/collects/web-server/docs/configuration.scrbl
similarity index 99%
rename from collects/web-server/docs/reference/configuration.scrbl
rename to collects/web-server/docs/configuration.scrbl
index 8221f547cc..80d61d8683 100644
--- a/collects/web-server/docs/reference/configuration.scrbl
+++ b/collects/web-server/docs/configuration.scrbl
@@ -1,5 +1,5 @@
 #lang scribble/doc
-@require["../web-server.ss"]
+@require["web-server.ss"]
 
 @title[#:tag "configuration"
        #:style 'toc]{Configuration}
diff --git a/collects/web-server/docs/reference/dispatchers.scrbl b/collects/web-server/docs/dispatchers.scrbl
similarity index 99%
rename from collects/web-server/docs/reference/dispatchers.scrbl
rename to collects/web-server/docs/dispatchers.scrbl
index 7d4bd3f6cf..c7f11dd0a7 100644
--- a/collects/web-server/docs/reference/dispatchers.scrbl
+++ b/collects/web-server/docs/dispatchers.scrbl
@@ -1,5 +1,5 @@
 #lang scribble/doc
-@(require "../web-server.ss"
+@(require "web-server.ss"
           (for-syntax scheme/base))
 
 @(define-syntax (a-dispatcher stx)
diff --git a/collects/web-server/docs/reference/dummy-language-servlet.ss b/collects/web-server/docs/dummy-language-servlet.ss
similarity index 100%
rename from collects/web-server/docs/reference/dummy-language-servlet.ss
rename to collects/web-server/docs/dummy-language-servlet.ss
diff --git a/collects/web-server/docs/reference/dummy-servlet.ss b/collects/web-server/docs/dummy-servlet.ss
similarity index 100%
rename from collects/web-server/docs/reference/dummy-servlet.ss
rename to collects/web-server/docs/dummy-servlet.ss
diff --git a/collects/web-server/docs/guide/web-guide.scrbl b/collects/web-server/docs/faq.scrbl
similarity index 83%
rename from collects/web-server/docs/guide/web-guide.scrbl
rename to collects/web-server/docs/faq.scrbl
index c0617a41ca..0f0053cde1 100644
--- a/collects/web-server/docs/guide/web-guide.scrbl
+++ b/collects/web-server/docs/faq.scrbl
@@ -1,9 +1,7 @@
 #lang scribble/doc
-@require["../web-server.ss"]
+@require["web-server.ss"]
 
-@title{Web Server User Guide}
-
-@table-of-contents[]
+@title{Troubleshooting}
 
 @section{General}
 
@@ -13,5 +11,3 @@ In quirks mode, IE does not parse your page as XML, in particular it will not re
 "empty tag shorthand", e.g. "<img src='...' />", whereas the @web-server uses @scheme[(lib "xml.ss" "xml")]
 to format XML, which uses empty tag shorthand by default. You can change the default with the @scheme[empty-tag-shorthand]
 parameter: @scheme[(empty-tag-shorthand 'never)].
-
-@index-section[]
diff --git a/collects/web-server/docs/info.ss b/collects/web-server/docs/info.ss
new file mode 100644
index 0000000000..839b578989
--- /dev/null
+++ b/collects/web-server/docs/info.ss
@@ -0,0 +1,3 @@
+(module info setup/infotab
+  (define name "Web Server documentation"))
+
diff --git a/collects/web-server/docs/reference/lang.scrbl b/collects/web-server/docs/lang.scrbl
similarity index 99%
rename from collects/web-server/docs/reference/lang.scrbl
rename to collects/web-server/docs/lang.scrbl
index 765fe5477b..dcd4b99efc 100644
--- a/collects/web-server/docs/reference/lang.scrbl
+++ b/collects/web-server/docs/lang.scrbl
@@ -1,5 +1,5 @@
 #lang scribble/doc
-@require["../web-server.ss"]
+@require["web-server.ss"]
 
 @title[#:tag "lang"
        #:style 'toc]{Web Language Servlets}
@@ -14,7 +14,7 @@ is different and what API is provided.
 @section[#:tag "lang-servlets"]{Definition}
 @require[(for-label "dummy-language-servlet.ss")] ; to give a binding context
 
-@declare-exporting[web-server/docs/reference/dummy-language-servlet]
+@declare-exporting[web-server/docs/dummy-language-servlet]
 
 A @defterm{Web language servlet} is a module written in the
 @scheme[(lib "lang.ss" "web-server")] module language. It should provide
diff --git a/collects/web-server/docs/reference/managers.scrbl b/collects/web-server/docs/managers.scrbl
similarity index 99%
rename from collects/web-server/docs/reference/managers.scrbl
rename to collects/web-server/docs/managers.scrbl
index cf1a39ea8b..3c4e45ad39 100644
--- a/collects/web-server/docs/reference/managers.scrbl
+++ b/collects/web-server/docs/managers.scrbl
@@ -1,5 +1,5 @@
 #lang scribble/doc
-@require["../web-server.ss"]
+@require["web-server.ss"]
 
 @title[#:tag "managers"
        #:style 'toc]{Continuation Managers}
diff --git a/collects/web-server/docs/reference/private.scrbl b/collects/web-server/docs/private.scrbl
similarity index 99%
rename from collects/web-server/docs/reference/private.scrbl
rename to collects/web-server/docs/private.scrbl
index 98e91203f0..c2a4c245f2 100644
--- a/collects/web-server/docs/reference/private.scrbl
+++ b/collects/web-server/docs/private.scrbl
@@ -1,5 +1,5 @@
 #lang scribble/doc
-@require["../web-server.ss"]
+@require["web-server.ss"]
 
 @title[#:tag "private"
        #:style 'toc]{Internal}
diff --git a/collects/web-server/docs/reference/running.scrbl b/collects/web-server/docs/running.scrbl
similarity index 80%
rename from collects/web-server/docs/reference/running.scrbl
rename to collects/web-server/docs/running.scrbl
index 7482807943..262f88f318 100644
--- a/collects/web-server/docs/reference/running.scrbl
+++ b/collects/web-server/docs/running.scrbl
@@ -1,5 +1,5 @@
 #lang scribble/doc
-@require["../web-server.ss"]
+@require["web-server.ss"]
 
 @title[#:tag "run.ss"
        #:style 'toc]{Running the Web Server}
@@ -12,24 +12,26 @@ 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 @web-server :
+One command-line utility is provided with the @|web-server|:
 
-@exec{plt-web-server-text [-f <file-name> -p <port> -a <ip-address>]}
+@commandline{plt-web-server [-f <file-name> -p <port> -a <ip-address>]}
 
-@exec{plt-web-server [-f <file-name> -p <port> -a <ip-address>]}
-
-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
-configuration shipped with the server is used. The optional port and ip-address
-arguments override the corresponding portions of the @scheme[configuration-table].
+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 configuration shipped with the server is used. The optional
+port and ip-address arguments override the corresponding portions of
+the @scheme[configuration-table].
 
 The @scheme[configuration-table] is given to @scheme[configuration-table->web-config\@]
 and used to construct a @scheme[web-config^] unit,
 and is linked with the @scheme[web-server\@] unit. The resulting unit is invoked, and
 the server runs until the process is killed.
 
+To run the web server with MrEd, use
+
+@commandline{mred -l- web-server/gui [-f <file-name> -p <port> -a <ip-address>]}
+
 @; ------------------------------------------------------------
 @section[#:tag "web-server.ss"]{Functional}
 @require[(for-label web-server/web-server)]
diff --git a/collects/web-server/docs/reference/servlet-env.scrbl b/collects/web-server/docs/servlet-env.scrbl
similarity index 97%
rename from collects/web-server/docs/reference/servlet-env.scrbl
rename to collects/web-server/docs/servlet-env.scrbl
index afd122fc8c..40f3d853ca 100644
--- a/collects/web-server/docs/reference/servlet-env.scrbl
+++ b/collects/web-server/docs/servlet-env.scrbl
@@ -1,5 +1,5 @@
 #lang scribble/doc
-@require["../web-server.ss"]
+@require["web-server.ss"]
 
 @title[#:tag "servlet-env.ss"
        #:style 'toc]{Environment}
diff --git a/collects/web-server/docs/reference/servlet.scrbl b/collects/web-server/docs/servlet.scrbl
similarity index 99%
rename from collects/web-server/docs/reference/servlet.scrbl
rename to collects/web-server/docs/servlet.scrbl
index 66f85e678f..495d9937de 100644
--- a/collects/web-server/docs/reference/servlet.scrbl
+++ b/collects/web-server/docs/servlet.scrbl
@@ -1,5 +1,5 @@
 #lang scribble/doc
-@require["../web-server.ss"]
+@require["web-server.ss"]
 
 @title[#:tag "servlet"
        #:style 'toc]{Scheme Servlets}
@@ -14,11 +14,11 @@ of these servlets. This API is provided by @filepath{servlet.ss}.
 @section[#:tag "module-servlets"]{Definition}
 @require[(for-label "dummy-servlet.ss")] ; to give a binding context
 
-@declare-exporting[web-server/docs/reference/dummy-servlet]
+@declare-exporting[web-server/docs/dummy-servlet]
 
 A @defterm{servlet} is a module that provides the following:
 
-@defthing[interface-version (or/c 'v1 'v2)]{
+@defthing[interface-version (one-of/c 'v1 'v2)]{
  A symbol indicating the servlet interface the servlet conforms
  to. This influences the other provided identifiers.
 }
diff --git a/collects/web-server/docs/reference/web-config-unit.scrbl b/collects/web-server/docs/web-config-unit.scrbl
similarity index 98%
rename from collects/web-server/docs/reference/web-config-unit.scrbl
rename to collects/web-server/docs/web-config-unit.scrbl
index 8239a119b6..d69f043f81 100644
--- a/collects/web-server/docs/reference/web-config-unit.scrbl
+++ b/collects/web-server/docs/web-config-unit.scrbl
@@ -1,5 +1,5 @@
 #lang scribble/doc
-@require["../web-server.ss"]
+@require["web-server.ss"]
 
 @title[#:tag "web-config-unit.ss"]{Web Config Unit}
 @require[(for-label web-server/web-config-unit)]
diff --git a/collects/web-server/docs/reference/web-server-unit.scrbl b/collects/web-server/docs/web-server-unit.scrbl
similarity index 98%
rename from collects/web-server/docs/reference/web-server-unit.scrbl
rename to collects/web-server/docs/web-server-unit.scrbl
index 03857ca1ad..11a2d7e322 100644
--- a/collects/web-server/docs/reference/web-server-unit.scrbl
+++ b/collects/web-server/docs/web-server-unit.scrbl
@@ -1,5 +1,5 @@
 #lang scribble/doc
-@require["../web-server.ss"]
+@require["web-server.ss"]
 
 @title[#:tag "web-server-unit.ss"]{Web Server Unit}
 @require[(for-label web-server/web-server-sig)]
diff --git a/collects/web-server/docs/reference/web-reference.scrbl b/collects/web-server/docs/web-server.scrbl
similarity index 90%
rename from collects/web-server/docs/reference/web-reference.scrbl
rename to collects/web-server/docs/web-server.scrbl
index a7581e7e51..748609e460 100644
--- a/collects/web-server/docs/reference/web-reference.scrbl
+++ b/collects/web-server/docs/web-server.scrbl
@@ -1,7 +1,7 @@
 #lang scribble/doc
-@require["../web-server.ss"]
+@require["web-server.ss"]
 
-@title[#:tag "web-server-ref"]{Web Server Reference Manual}
+@title[#:tag "web-server-ref"]{@bold{Web Server}: Reference Manual}
 @author{Jay McCarthy (jay@"@"plt-scheme.org)}
 
 The @web-server collection provides libraries that can be used to
@@ -22,6 +22,8 @@ develop Web applications in Scheme.
 
 @include-section["private.scrbl"]
 
+@include-section["faq.scrbl"]
+
 @; ------------------------------------------------------------
 @section[#:tag "ack"]{Acknowledgements}
 
diff --git a/collects/web-server/private/gui.ss b/collects/web-server/gui.ss
similarity index 90%
rename from collects/web-server/private/gui.ss
rename to collects/web-server/gui.ss
index 70a7ab2e45..79632430be 100644
--- a/collects/web-server/private/gui.ss
+++ b/collects/web-server/gui.ss
@@ -1,7 +1,7 @@
 #lang scheme/base
 (require (lib "class.ss")
          (lib "mred.ss" "mred"))
-(require "launch.ss")
+(require "private/launch.ss")
 
 (define shutdown (serve))
 
diff --git a/collects/web-server/info.ss b/collects/web-server/info.ss
index 24b0769d7e..4891e1f812 100644
--- a/collects/web-server/info.ss
+++ b/collects/web-server/info.ss
@@ -1,9 +1,8 @@
 (module info setup/infotab
   (define name "Web Server")  
-  (define scribblings '(("docs/reference/web-reference.scrbl" (multi-page main-doc))
-                        ("docs/guide/web-guide.scrbl" (multi-page main-doc))))
+  (define scribblings '(("docs/web-server.scrbl" (multi-page main-doc))))
   
   (define mzscheme-launcher-libraries
-    (list "private/main.ss"))
+    (list "main.ss"))
   (define mzscheme-launcher-names
     (list "PLT Web Server")))
\ No newline at end of file
diff --git a/collects/web-server/main.ss b/collects/web-server/main.ss
new file mode 100644
index 0000000000..8fc19ab549
--- /dev/null
+++ b/collects/web-server/main.ss
@@ -0,0 +1,5 @@
+#lang scheme/base
+(require "private/launch.ss"
+         (only-in "web-server.ss" do-not-return))
+(void (serve))
+(do-not-return)
\ No newline at end of file
diff --git a/collects/web-server/private/main.ss b/collects/web-server/private/main.ss
deleted file mode 100644
index b1e2477dc6..0000000000
--- a/collects/web-server/private/main.ss
+++ /dev/null
@@ -1,5 +0,0 @@
-#lang scheme/base
-(require "launch.ss"
-         (only-in "../web-server.ss" do-not-return))
-(serve)
-(do-not-return)
\ No newline at end of file